API de facturación electrónica

El API se llama desde tu servidor: no admite CORS, para que el token no quede expuesto en un navegador.

Antes de empezar

• Una cuenta de Golem con el RUC de la empresa y un usuario administrador, que es quien crea los tokens en Cuenta > API e integraciones.
• La firma electrónica de la empresa cargada y vigente en la aplicación.
• Establecimientos y puntos de emisión configurados en la aplicación.
• Créditos disponibles para emitir.
• Para el ambiente de pruebas, el RUC habilitado para pruebas en SRI en línea.

Cómo se emite un comprobante

1. Tu sistema envía el comprobante con los datos del cliente, los ítems con su precio sin IVA y la forma de pago.
2. Golem valida los datos, calcula subtotales, IVA y total, y asigna el secuencial y la clave de acceso.
3. Golem firma el XML con la firma de la empresa, lo envía al SRI y espera la autorización hasta 12 segundos.
4. La respuesta es 201 con el estado final (AUTORIZADO, NO_AUTORIZADO, DEVUELTO o ERROR) o 202 con EN_PROCESO si el SRI aún no responde. Ver Estados.
5. En producción, Golem envía al receptor el correo con el XML autorizado y el RIDE.

# Usa una clave nueva por cada comprobante en Idempotency-Key (por ejemplo, la salida de uuidgen).
curl -X POST https://api.golem.ec/v1/comprobantes/facturas \
  --max-time 30 \
  -H "Authorization: Bearer $GOLEM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5d8c1f3e-9b2a-4e67-8c04-3f6a2b9d7e15" \
  -d @factura.json

La cabecera Idempotency-Key permite repetir la solicitud sin duplicar el comprobante si la conexión se corta. Usa una clave nueva por cada comprobante: la del ejemplo es solo una muestra. Ver Idempotencia.

Créditos

Cada comprobante emitido por el API consume un crédito del saldo de la empresa, igual que en la aplicación y también en el ambiente de pruebas. Si el comprobante termina DEVUELTO, NO_AUTORIZADO o ERROR, el crédito vuelve al saldo. Sin créditos, la emisión responde 402 SIN_CREDITOS. Las consultas, el listado y las descargas no consumen créditos y siguen disponibles sin saldo. GET /empresa devuelve los créditos disponibles.

Especificación y colección

La especificación OpenAPI es la fuente de esta documentación. Sirve para generar un cliente o para importar las operaciones en tu herramienta:

• Especificación OpenAPI 3.1 (JSON)
• Especificación OpenAPI 3.1 (YAML)
• Colección de Postman

La colección de Postman tiene las 14 operaciones con sus ejemplos. Al importarla, completa la variable token; cada emisión genera su propia Idempotency-Key.

curl https://api.golem.ec/v1/openapi.json \
  --max-time 30

const respuesta = await fetch('https://api.golem.ec/v1/openapi.json', {
  signal: AbortSignal.timeout(30000),
});
const datos = await respuesta.json();
console.log(respuesta.status, datos);

import requests

respuesta = requests.get(
    "https://api.golem.ec/v1/openapi.json",
    timeout=30,
)
print(respuesta.status_code, respuesta.json())

<?php
// composer require guzzlehttp/guzzle
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$cliente = new Client(['base_uri' => 'https://api.golem.ec/v1/', 'timeout' => 30]);

$respuesta = $cliente->get('openapi.json', [
    'http_errors' => false,
]);

echo $respuesta->getStatusCode(), PHP_EOL, $respuesta->getBody(), PHP_EOL;