Inicio rápido

Antes de empezar

• Una cuenta de Golem con el RUC de tu empresa y un usuario administrador: solo los administradores crean tokens.
• La firma electrónica de la empresa cargada y vigente en la aplicación.
• Créditos disponibles: cada comprobante emitido consume un crédito, también en el ambiente de pruebas. Si el SRI no lo autoriza, el crédito vuelve al saldo.
• Para el ambiente de pruebas, el RUC habilitado para pruebas en SRI en línea. Si no lo está, el SRI devuelve los comprobantes.

1. Crea un token de pruebas

1. En la aplicación, abre Cuenta > API e integraciones y elige Crear token.
2. Escribe un nombre que identifique la integración, elige el ambiente Pruebas y, si quieres, un punto de emisión por defecto.
3. Copia el token. Golem lo muestra una sola vez y solo guarda su huella: si lo pierdes, crea otro.

Guárdalo en una variable de entorno para no escribirlo en los comandos:

export GOLEM_TOKEN="glm_prueba_..."

En PowerShell: $env:GOLEM_TOKEN = "glm_prueba_...". La página Autenticación explica el formato del token y cómo revocarlo.

2. Comprueba el token

GET /empresa devuelve la empresa del token, sus establecimientos y puntos de emisión, los créditos y la vigencia de la firma:

curl https://api.golem.ec/v1/empresa \
  -H "Authorization: Bearer $GOLEM_TOKEN"

Revisa en la respuesta:

• ambiente: PRUEBAS.
• creditosDisponibles: mayor que 0.
• firma.vigente: true.
• establecimientos[].codigo y establecimientos[].puntosEmision[].codigo: los códigos de 3 dígitos que usarás al emitir.

Si la respuesta es 401, el token no llegó completo o fue revocado: revisa la variable de entorno.

3. Emite una factura

Cambia establecimiento y puntoEmision por los de tu empresa. La cabecera Idempotency-Key identifica la operación: genera una clave nueva (por ejemplo, un UUID v4) para cada factura y repítela solo si reintentas la misma solicitud.

# 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: 7b1e4d2a-5c3f-4a8e-9d61-2f0c8b3e5a17" \
  -d '{
    "establecimiento": "001",
    "puntoEmision": "001",
    "cliente": {
      "identificacion": "0990000000001",
      "razonSocial": "CLIENTE DEMO S.A.",
      "email": "[email protected]"
    },
    "items": [
      { "codigo": "P-001", "descripcion": "Producto de ejemplo",
        "cantidad": 10, "precioUnitario": 7.80, "iva": 15 }
    ],
    "formaPago": "20"
  }'

El precio unitario va sin IVA. Golem calcula el subtotal (10 × 7.80 = 78.00), el IVA del 15 % (11.70) y el total (89.70), asigna el número y la clave de acceso, firma el XML y lo envía al SRI.

Golem espera la respuesta del SRI hasta 12 segundos:

• 201: el comprobante llegó a un estado final. Revisa estado: AUTORIZADO, o DEVUELTO, NO_AUTORIZADO o ERROR con los motivos en mensajes.
• 202: el SRI aún no responde. El estado es EN_PROCESO y Golem sigue el proceso por su cuenta; consulta el comprobante más tarde.

{
  "tipo": "FACTURA",
  "claveAcceso": "2409202601179000000000120010010000001481234567815",
  "numero": "001-001-000000148",
  "estado": "AUTORIZADO",
  "ambiente": "PRODUCCION",
  "fechaAutorizacion": "2026-09-24T10:42:31-05:00",
  "total": 89.70,
  "mensajes": [],
  "enlaces": {
    "self": "https://api.golem.ec/v1/comprobantes/2409202601179000000000120010010000001481234567815",
    "pdf": "https://api.golem.ec/v1/comprobantes/2409202601179000000000120010010000001481234567815/pdf",
    "xml": "https://api.golem.ec/v1/comprobantes/2409202601179000000000120010010000001481234567815/xml"
  }
}

La respuesta de ejemplo es de producción; con un token de pruebas, ambiente es PRUEBAS. Guarda la claveAcceso: identifica el comprobante en las demás operaciones.

4. Consulta el comprobante

CLAVE="2409202601179000000000120010010000001481234567815"
curl https://api.golem.ec/v1/comprobantes/$CLAVE \
  -H "Authorization: Bearer $GOLEM_TOKEN"

Si la emisión respondió 202, repite esta consulta (por ejemplo a los 5, 15 y 60 segundos) hasta que estado deje de ser EN_PROCESO. Para seguir muchos comprobantes, usa el listado con cambiadoDesde en lugar de consultar uno por uno.

5. Descarga el XML y el RIDE

Solo los comprobantes autorizados tienen XML autorizado y RIDE:

curl https://api.golem.ec/v1/comprobantes/$CLAVE/xml \
  -H "Authorization: Bearer $GOLEM_TOKEN" -o factura.xml

curl https://api.golem.ec/v1/comprobantes/$CLAVE/pdf \
  -H "Authorization: Bearer $GOLEM_TOKEN" -o factura.pdf

El XML incluye el envoltorio de autorización del SRI con el comprobante firmado. En pruebas, el correo con el XML y el RIDE no llega al cliente: va a un buzón de Golem.

6. Pasa a producción

1. Crea un token con el ambiente Producción. Los comprobantes que emite tienen validez tributaria y se envían por correo al cliente.
2. Reemplaza el token en tu sistema. No cambia nada más: la URL, los campos y las respuestas son los mismos.
3. Revoca el token de pruebas si ya no lo usas.

Los secuenciales de producción son distintos de los de pruebas, y un token solo consulta los comprobantes de su ambiente. Detalle en Ambientes.

Siguientes pasos

• Importa la colección de Postman y completa la variable token, o genera un cliente desde la especificación OpenAPI.
• Revisa los campos y el cálculo de facturas, los estados y los errores.