API v1.0.0 · COMPROBANTES

Notas de crédito

Una nota de crédito modifica una factura autorizada: devoluciones, descuentos posteriores a la venta o correcciones. Puede referirse a una factura emitida en Golem o fuera de Golem.

Factura emitida en Golem

Envía la clave de acceso de la factura en documentoModificado:

documentoModificado

{ "claveAcceso": "2409202601179000000000120010010000001481234567815" }

Golem toma de la factura su número, su fecha y los datos del cliente, y comprueba:

Regla	Error
La factura es de la empresa y del ambiente del token.	`422 SUSTENTO_NO_ENCONTRADO`
La factura está autorizada.	`422 SUSTENTO_NO_AUTORIZADO`
Si envías `cliente`, su identificación es la de la factura.	`422 CLIENTE_NO_COINCIDE`
La factura no se emitió a consumidor final.	`422 CLIENTE_NO_PERMITIDO`
Cada ítem usa una tarifa de IVA que la factura tiene.	`422 TARIFA_IVA_NO_COINCIDE`
La nota de crédito, sumada a las anteriores de la misma factura, no supera su total. No cuentan las anuladas ni las que el SRI no aceptó.	`422 NOTA_CREDITO_EXCEDE_SALDO`

No hace falta enviar cliente: se toma de la factura.

Factura emitida fuera de Golem

Si la factura se emitió con otro sistema, envía su código, su número y su fecha, y los datos del cliente:

documentoModificado

{ "codDoc": "01", "numero": "001-001-000004210", "fechaEmision": "2023-11-14" }

En esta versión, el documento modificado es siempre una factura (codDoc 01).
cliente es obligatorio y debe estar identificado: no se admite consumidor final (422 CLIENTE_NO_PERMITIDO).
Golem comprueba que las tarifas de IVA estén vigentes en la fecha de la factura, pero no conoce su contenido: no puede comprobar su saldo ni que las tarifas sean las que tuvo. Revisa en tu sistema que la nota de crédito no supere lo facturado.

Receptor identificado

La nota de crédito necesita un receptor identificado: no se emite a consumidor final (9999999999999) ni sobre una factura emitida a consumidor final. En los dos casos la respuesta es 422 CLIENTE_NO_PERMITIDO.

Tarifas de IVA por fecha

Las tarifas admitidas son las vigentes en la fecha de la factura modificada, no en la de la nota de crédito:

Tarifa	`iva`	`codigoIva`	Facturas emitidas
12 %	12	`2`	Hasta el 31 de marzo de 2024
14 %	14	`3`	Del 1 de junio de 2016 al 31 de mayo de 2017
15 %, 5 % y 13 %	15, 5, 13	`4`, `5`, `10`	Desde el 1 de abril de 2024
0 %, no objeto, exento y diferenciado	0, 8	`0`, `6`, `7`, `8`	Cualquier fecha

Una tarifa fuera de su vigencia responde 422 TARIFA_IVA_NO_VIGENTE.

Ítems y totales

Los ítems tienen los mismos campos y el mismo cálculo que en una factura: el precio unitario va sin IVA y Golem calcula subtotales, IVA y total.
Describe en cada ítem lo que se devuelve o se descuenta; la descripción se imprime en la nota de crédito.
Si un ítem corresponde a un producto con control de inventario, la nota de crédito devuelve esas unidades al inventario.
motivo (hasta 300 caracteres) es la razón que se imprime en el comprobante.
El total de la nota de crédito es el valor de la modificación, con IVA. Para compararlo con tu cálculo, envía totalEsperado.
Una nota de crédito no lleva formas de pago.

Fecha y punto de emisión

fechaEmision: por defecto hoy; se acepta hoy o ayer (hora de Ecuador), y no puede ser anterior a la de la factura modificada.
El punto de emisión de la nota de crédito puede ser distinto del de la factura. Si omites establecimiento y puntoEmision, se usa el punto por defecto del token.

Nota de crédito o anulación

Una nota de crédito deja constancia de la devolución o del descuento y la factura sigue vigente. Para dejar sin efecto una factura completa también se puede anular, en la aplicación de Golem y en SRI en línea; el API no anula comprobantes.

Emitir una nota de crédito

POST /comprobantes/notas-credito

Requiere token
Idempotency-Key
Espera al SRI hasta 12 s

Crea una nota de crédito (código 04) que modifica una factura.

Si la factura se emitió en Golem, basta su claveAcceso en documentoModificado: Golem toma de ella el número, la fecha y los datos del cliente, verifica que esté autorizada, que las tarifas de IVA sean las de la factura y que la suma de sus notas de crédito no supere su total.
Si la factura se emitió fuera de Golem, envía codDoc, numero y fechaEmision del documento y los datos del cliente.
El receptor debe estar identificado: no se emite una nota de crédito a consumidor final (9999999999999), tampoco si la factura modificada fue a consumidor final (422 CLIENTE_NO_PERMITIDO).
Las tarifas de IVA admitidas son las vigentes a la fecha de la factura modificada (por ejemplo, 12 % para facturas anteriores al 1 de abril de 2024).

Límites: 60 solicitudes por minuto por token; 20 emisiones por minuto por token y 40 por empresa.

Parámetros

Parámetros de emitir una nota de crédito
Campo	Descripción
`Idempotency-Key` cabecera string	Clave única de la operación, generada por tu sistema (se recomienda un UUID v4). Entre 8 y 100 caracteres: letras, números, `-`, `_`, `.` o `:`. Vale 24 horas por empresa y por ambiente. Es opcional, pero sin ella un reintento después de un corte de red crea otro comprobante. De 8 a 100 caracteres Formato `^[A-Za-z0-9._:-]{8,100}$`
`Prefer` cabecera string	`respond-async` responde de inmediato con `202` sin esperar al SRI. Sin esta cabecera, Golem espera el resultado hasta 12 segundos. Otros valores se ignoran.
`X-Request-Id` cabecera string	Identificador propio de la solicitud (hasta 64 caracteres: letras, números y `-`). Si no lo envías, Golem genera uno. Vuelve en la cabecera de respuesta y en los errores; cítalo al escribir a soporte. Hasta 64 caracteres Formato `^[A-Za-z0-9-]{1,64}$`

Cuerpo de la solicitud

JSON (application/json). Los campos que no están en esta tabla se rechazan con 400 VALIDACION.

Campos del cuerpo (NotaCreditoSolicitud)
Campo	Descripción
`establecimiento` string	Código de 3 dígitos del establecimiento, como en el número del comprobante. Formato `^\d{3}$`
`puntoEmision` string	Código de 3 dígitos del punto de emisión. Formato `^\d{3}$`
`fechaEmision` string (date)	Fecha de emisión. Por defecto, hoy; se acepta hoy o ayer, como en la factura. No puede ser anterior a la del documento modificado.
`referencia` string	De 1 a 100 caracteres
`documentoModificado` object obligatorio	Sin descripción
Una de las formas: Factura emitida en Golem
`documentoModificado. claveAcceso` string obligatorio	Clave de acceso de 49 dígitos. En el esquema offline del SRI es también el número de autorización. Formato `^\d{49}$`
Una de las formas: Documento emitido fuera de Golem
`documentoModificado. codDoc` string obligatorio	Código del SRI del documento modificado. En esta versión, 01 (factura). Valores: `01`
`documentoModificado. numero` string obligatorio	Número del comprobante con establecimiento, punto de emisión y secuencial. Formato `^\d{3}-\d{3}-\d{9}$`
`documentoModificado. fechaEmision` string (date) obligatorio	Sin descripción
`motivo` string obligatorio	Razón de la nota de crédito, como se imprime. De 1 a 300 caracteres
`cliente` object	Obligatorio si la factura se emitió fuera de Golem; si se emitió en Golem, se toma de ella y, si lo envías, su identificación debe coincidir. No se admite consumidor final.
`cliente. tipoIdentificacion` string	Tipo de identificación del SRI (tabla 6): 04 RUC, 05 cédula, 06 pasaporte, 07 consumidor final, 08 identificación del exterior. Valores: `04`, `05`, `06`, `07`, `08`
`cliente. identificacion` string obligatorio	Cédula (10 dígitos), RUC (13 dígitos), pasaporte o identificación del exterior. Para consumidor final, `9999999999999`. Si omites `tipoIdentificacion`, se deduce: 13 dígitos válidos → RUC, 10 dígitos válidos → cédula, `9999999999999` → consumidor final; en otro caso indícalo. De 3 a 20 caracteres Formato `^[A-Za-z0-9-]{3,20}$`
`cliente. razonSocial` string	Nombres y apellidos o razón social. Obligatorio salvo para consumidor final. De 3 a 300 caracteres
`cliente. email` string (email)	Hasta 255 caracteres
`cliente. direccion` string	Hasta 300 caracteres
`cliente. telefono` string	Hasta 30 caracteres
`items` object[] obligatorio	De 1 a 200 elementos
`items[]. codigo` string obligatorio	Código principal del ítem. Si no existe en el catálogo de la empresa, se crea con estos datos. De 1 a 25 caracteres
`items[]. codigoAuxiliar` string	Hasta 25 caracteres
`items[]. descripcion` string obligatorio	Descripción que se imprime en el comprobante (el catálogo no se modifica). De 1 a 300 caracteres
`items[]. cantidad` number obligatorio	Cantidad, mayor que 0, con hasta 2 decimales (por ejemplo 1.25 kg). Mayor que 0, hasta 999999999.99
`items[]. precioUnitario` number obligatorio	Precio unitario sin IVA, con hasta 4 decimales. Si tu sistema tiene el precio con IVA incluido (PVP), envía PVP ÷ (1 + tarifa/100) redondeado a 4 decimales y, si quieres comparar con lo cobrado, usa `totalEsperado` (tolera 0.01). Desde 0, hasta 999999999.9999
`items[]. descuento` number	Descuento en dólares de la línea completa, con hasta 2 decimales. No puede superar cantidad × precio. Desde 0 Por defecto `0`
`items[]. iva` number	Porcentaje de IVA del ítem. Se traduce al código del SRI (15 → 4, 5 → 5, 0 → 0, 13 → 10, 8 → 8; 12 → 2 y 14 → 3 solo en notas de crédito de facturas de esas fechas). Obligatorio si no envías `codigoIva`. Valores: `0`, `5`, `8`, `12`, `13`, `14`, `15`
`items[]. codigoIva` string	Código de porcentaje de IVA del SRI (tabla 17): 0 (0 %), 2 (12 %, hasta el 31-03-2024), 3 (14 %, del 01-06-2016 al 31-05-2017), 4 (15 %, desde el 01-04-2024), 5 (5 %), 6 (no objeto de IVA), 7 (exento de IVA), 8 (IVA diferenciado), 10 (13 %). Valores: `0`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `10`
`items[]. tipo` string	Tipo del ítem. Solo se usa para crear el producto en el catálogo de la empresa cuando su código no existe. Valores: `BIEN`, `SERVICIO`
`items[]. detallesAdicionales` object[]	Hasta 3 detalles adicionales del ítem. Hasta 3 elementos
`items[].detallesAdicionales[]. nombre` string obligatorio	De 1 a 300 caracteres
`items[].detallesAdicionales[]. valor` string obligatorio	De 1 a 300 caracteres
`informacionAdicional` object[]	Hasta 14 elementos
`informacionAdicional[]. nombre` string obligatorio	De 1 a 300 caracteres
`informacionAdicional[]. valor` string obligatorio	De 1 a 300 caracteres
`totalEsperado` number	Total (valor de la modificación) que calculó tu sistema. Si difiere en más de 0.01, no se emite. Desde 0, hasta 999999999.99

Ejemplo de solicitud

Los ejemplos leen el token de la variable de entorno GOLEM_TOKEN. Usa una clave nueva por cada comprobante en Idempotency-Key: la del ejemplo de curl es solo una muestra. Si repites la solicitud después de un corte de conexión, usa la misma clave.

Terminal

# Usa una clave nueva por cada comprobante en Idempotency-Key (por ejemplo, un UUID v4).
curl -X POST https://api.golem.ec/v1/comprobantes/notas-credito \
  --max-time 30 \
  -H "Authorization: Bearer $GOLEM_TOKEN" \
  -H "Idempotency-Key: 06c4ab39-bcd4-4673-a1ee-49d4e7b8c657" \
  -H "Content-Type: application/json" \
  -d '{
    "establecimiento": "001",
    "puntoEmision": "001",
    "referencia": "DEV-2026-0012",
    "documentoModificado": {
      "claveAcceso": "2409202601179000000000120010010000001481234567815"
    },
    "motivo": "Devolución de 2 unidades",
    "items": [
      {
        "codigo": "P-001",
        "descripcion": "Producto de ejemplo",
        "cantidad": 2,
        "precioUnitario": 7.8,
        "iva": 15
      }
    ]
  }'

Node.js 18+ (fetch)

import { randomUUID } from 'node:crypto';

const respuesta = await fetch('https://api.golem.ec/v1/comprobantes/notas-credito', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GOLEM_TOKEN}`,
    'Idempotency-Key': randomUUID(), // una clave nueva por cada comprobante; guárdala para repetir la solicitud si la conexión se corta
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    establecimiento: '001',
    puntoEmision: '001',
    referencia: 'DEV-2026-0012',
    documentoModificado: {
      claveAcceso: '2409202601179000000000120010010000001481234567815',
    },
    motivo: 'Devolución de 2 unidades',
    items: [
      {
        codigo: 'P-001',
        descripcion: 'Producto de ejemplo',
        cantidad: 2,
        precioUnitario: 7.8,
        iva: 15,
      },
    ],
  }),
  signal: AbortSignal.timeout(30000),
});
const datos = await respuesta.json();
console.log(respuesta.status, datos);

Python (requests)

import os
import uuid

import requests

respuesta = requests.post(
    "https://api.golem.ec/v1/comprobantes/notas-credito",
    headers={
        "Authorization": f"Bearer {os.environ['GOLEM_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),  # una clave nueva por cada comprobante; guárdala para repetir la solicitud si la conexión se corta
    },
    json={
        "establecimiento": "001",
        "puntoEmision": "001",
        "referencia": "DEV-2026-0012",
        "documentoModificado": {
            "claveAcceso": "2409202601179000000000120010010000001481234567815",
        },
        "motivo": "Devolución de 2 unidades",
        "items": [
            {
                "codigo": "P-001",
                "descripcion": "Producto de ejemplo",
                "cantidad": 2,
                "precioUnitario": 7.8,
                "iva": 15,
            },
        ],
    },
    timeout=30,
)
print(respuesta.status_code, respuesta.json())

PHP (Guzzle)

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

use GuzzleHttp\Client;
use Ramsey\Uuid\Uuid;

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

$respuesta = $cliente->post('comprobantes/notas-credito', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('GOLEM_TOKEN'),
        'Idempotency-Key' => Uuid::uuid4()->toString(), // una clave nueva por cada comprobante; guárdala para repetir la solicitud si la conexión se corta
    ],
    'json' => [
        'establecimiento' => '001',
        'puntoEmision' => '001',
        'referencia' => 'DEV-2026-0012',
        'documentoModificado' => [
            'claveAcceso' => '2409202601179000000000120010010000001481234567815',
        ],
        'motivo' => 'Devolución de 2 unidades',
        'items' => [
            [
                'codigo' => 'P-001',
                'descripcion' => 'Producto de ejemplo',
                'cantidad' => 2,
                'precioUnitario' => 7.8,
                'iva' => 15,
            ],
        ],
    ],
    'http_errors' => false,
]);

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

Respuestas

201 application/json

Comprobante creado y procesado hasta un estado final: AUTORIZADO, NO_AUTORIZADO, DEVUELTO o ERROR. En los tres últimos el crédito vuelve al saldo y los motivos están en mensajes.

Esquema Comprobante.

Respuesta 201: Factura autorizada

{
  "tipo": "FACTURA",
  "codDoc": "01",
  "claveAcceso": "2409202601179000000000120010010000001481234567815",
  "numero": "001-001-000000148",
  "estado": "AUTORIZADO",
  "ambiente": "PRODUCCION",
  "fechaEmision": "2026-09-24",
  "fechaEnvio": "2026-09-24T10:42:28-05:00",
  "fechaAutorizacion": "2026-09-24T10:42:31-05:00",
  "numeroAutorizacion": "2409202601179000000000120010010000001481234567815",
  "fechaActualizacion": "2026-09-24T10:42:33.512-05:00",
  "establecimiento": "001",
  "puntoEmision": "001",
  "referencia": null,
  "origen": "API",
  "total": 89.7,
  "cliente": {
    "tipoIdentificacion": "04",
    "identificacion": "0990000000001",
    "razonSocial": "CLIENTE DEMO S.A.",
    "email": "[email protected]",
    "direccion": null,
    "telefono": null
  },
  "items": [
    {
      "codigo": "P-001",
      "codigoAuxiliar": null,
      "descripcion": "Producto de ejemplo",
      "cantidad": 10,
      "precioUnitario": 7.8,
      "descuento": 0,
      "subtotal": 78,
      "codigoIva": "4",
      "tarifaIva": 15,
      "valorIva": 11.7,
      "detallesAdicionales": []
    }
  ],
  "pagos": [
    {
      "formaPago": "20",
      "total": 89.7,
      "plazo": null,
      "unidadTiempo": null
    }
  ],
  "guiaRemision": null,
  "totales": {
    "subtotal": 78,
    "descuento": 0,
    "subtotalesIva": [
      {
        "codigoIva": "4",
        "tarifa": 15,
        "baseImponible": 78,
        "valor": 11.7
      }
    ],
    "iva": 11.7,
    "propina": 0,
    "total": 89.7
  },
  "mensajes": [],
  "anulacion": null,
  "informacionAdicional": [
    {
      "nombre": "RUC Proveedor",
      "valor": "0195113076001"
    }
  ],
  "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"
  }
}

Más ejemplos de la respuesta 201

Factura devuelta por el SRI (el crédito vuelve al saldo)

{
  "tipo": "FACTURA",
  "codDoc": "01",
  "claveAcceso": "2609202601179000000000120010010000001501122334419",
  "numero": "001-001-000000150",
  "estado": "DEVUELTO",
  "ambiente": "PRODUCCION",
  "fechaEmision": "2026-09-26",
  "fechaEnvio": "2026-09-26T09:20:11-05:00",
  "fechaAutorizacion": null,
  "numeroAutorizacion": null,
  "fechaActualizacion": "2026-09-26T09:20:12.845-05:00",
  "establecimiento": "001",
  "puntoEmision": "001",
  "referencia": "PED-2026-00483",
  "origen": "API",
  "total": 11.5,
  "cliente": {
    "tipoIdentificacion": "04",
    "identificacion": "0990000000001",
    "razonSocial": "CLIENTE DEMO S.A.",
    "email": "[email protected]",
    "direccion": null,
    "telefono": null
  },
  "items": [
    {
      "codigo": "P-002",
      "codigoAuxiliar": null,
      "descripcion": "Servicio de ejemplo",
      "cantidad": 1,
      "precioUnitario": 10,
      "descuento": 0,
      "subtotal": 10,
      "codigoIva": "4",
      "tarifaIva": 15,
      "valorIva": 1.5,
      "detallesAdicionales": []
    }
  ],
  "pagos": [
    {
      "formaPago": "20",
      "total": 11.5,
      "plazo": null,
      "unidadTiempo": null
    }
  ],
  "guiaRemision": null,
  "totales": {
    "subtotal": 10,
    "descuento": 0,
    "subtotalesIva": [
      {
        "codigoIva": "4",
        "tarifa": 15,
        "baseImponible": 10,
        "valor": 1.5
      }
    ],
    "iva": 1.5,
    "propina": 0,
    "total": 11.5
  },
  "mensajes": [
    {
      "origen": "SRI",
      "identificador": "56",
      "mensaje": "ESTABLECIMIENTO CERRADO",
      "informacionAdicional": "El establecimiento 001 del RUC 1790000000001 está cerrado en el catastro.",
      "tipo": "ERROR"
    }
  ],
  "anulacion": null,
  "informacionAdicional": [],
  "enlaces": {
    "self": "https://api.golem.ec/v1/comprobantes/2609202601179000000000120010010000001501122334419",
    "pdf": null,
    "xml": null
  }
}

Nota de crédito autorizada

{
  "tipo": "NOTA_CREDITO",
  "codDoc": "04",
  "claveAcceso": "2609202604179000000000120010010000000095550123411",
  "numero": "001-001-000000009",
  "estado": "AUTORIZADO",
  "ambiente": "PRODUCCION",
  "fechaEmision": "2026-09-26",
  "fechaEnvio": "2026-09-26T11:02:40-05:00",
  "fechaAutorizacion": "2026-09-26T11:02:43-05:00",
  "numeroAutorizacion": "2609202604179000000000120010010000000095550123411",
  "fechaActualizacion": "2026-09-26T11:02:44.087-05:00",
  "establecimiento": "001",
  "puntoEmision": "001",
  "referencia": "DEV-2026-0012",
  "origen": "API",
  "total": 17.94,
  "cliente": {
    "tipoIdentificacion": "04",
    "identificacion": "0990000000001",
    "razonSocial": "CLIENTE DEMO S.A.",
    "email": "[email protected]",
    "direccion": null,
    "telefono": null
  },
  "documentoModificado": {
    "codDoc": "01",
    "numero": "001-001-000000148",
    "fechaEmision": "2026-09-24",
    "claveAcceso": "2409202601179000000000120010010000001481234567815"
  },
  "motivo": "Devolución de 2 unidades",
  "items": [
    {
      "codigo": "P-001",
      "codigoAuxiliar": null,
      "descripcion": "Producto de ejemplo",
      "cantidad": 2,
      "precioUnitario": 7.8,
      "descuento": 0,
      "subtotal": 15.6,
      "codigoIva": "4",
      "tarifaIva": 15,
      "valorIva": 2.34,
      "detallesAdicionales": []
    }
  ],
  "totales": {
    "subtotal": 15.6,
    "descuento": 0,
    "subtotalesIva": [
      {
        "codigoIva": "4",
        "tarifa": 15,
        "baseImponible": 15.6,
        "valor": 2.34
      }
    ],
    "iva": 2.34,
    "total": 17.94
  },
  "mensajes": [],
  "anulacion": null,
  "informacionAdicional": [
    {
      "nombre": "RUC Proveedor",
      "valor": "0195113076001"
    }
  ],
  "enlaces": {
    "self": "https://api.golem.ec/v1/comprobantes/2609202604179000000000120010010000000095550123411",
    "pdf": "https://api.golem.ec/v1/comprobantes/2609202604179000000000120010010000000095550123411/pdf",
    "xml": "https://api.golem.ec/v1/comprobantes/2609202604179000000000120010010000000095550123411/xml"
  }
}

Comprobante de retención autorizado

{
  "tipo": "RETENCION",
  "codDoc": "07",
  "claveAcceso": "2609202607179000000000120010010000000223141592611",
  "numero": "001-001-000000022",
  "estado": "AUTORIZADO",
  "ambiente": "PRODUCCION",
  "fechaEmision": "2026-09-26",
  "fechaEnvio": "2026-09-26T12:10:05-05:00",
  "fechaAutorizacion": "2026-09-26T12:10:08-05:00",
  "numeroAutorizacion": "2609202607179000000000120010010000000223141592611",
  "fechaActualizacion": "2026-09-26T12:10:09.301-05:00",
  "establecimiento": "001",
  "puntoEmision": "001",
  "referencia": "CXP-2026-0931",
  "origen": "API",
  "total": 62.5,
  "sujetoRetenido": {
    "tipoIdentificacion": "04",
    "identificacion": "0990000000001",
    "razonSocial": "PROVEEDOR DEMO S.A.",
    "email": "[email protected]",
    "direccion": null,
    "telefono": null
  },
  "periodoFiscal": "2026-09",
  "documentoSustento": {
    "codDoc": "01",
    "numero": "002-001-000004521",
    "fechaEmision": "2026-09-22",
    "claveAcceso": null
  },
  "retenciones": [
    {
      "codigoImpuesto": "1",
      "codigoRetencion": "312",
      "baseImponible": 1000,
      "porcentaje": 1.75,
      "valorRetenido": 17.5
    },
    {
      "codigoImpuesto": "2",
      "codigoRetencion": "1",
      "baseImponible": 150,
      "porcentaje": 30,
      "valorRetenido": 45
    }
  ],
  "mensajes": [],
  "anulacion": null,
  "informacionAdicional": [
    {
      "nombre": "RUC Proveedor",
      "valor": "0195113076001"
    }
  ],
  "enlaces": {
    "self": "https://api.golem.ec/v1/comprobantes/2609202607179000000000120010010000000223141592611",
    "pdf": "https://api.golem.ec/v1/comprobantes/2609202607179000000000120010010000000223141592611/pdf",
    "xml": "https://api.golem.ec/v1/comprobantes/2609202607179000000000120010010000000223141592611/xml"
  }
}

202 application/json

Comprobante creado; el SRI aún no responde. Estado EN_PROCESO. Consulta Location más tarde (por ejemplo a los 5, 15 y 60 segundos). Golem reintenta el envío y la autorización por su cuenta.

Esquema Comprobante.

Respuesta 202: Factura en proceso (el SRI aún no responde)

{
  "tipo": "FACTURA",
  "codDoc": "01",
  "claveAcceso": "2609202601179000000000120010010000001498765432115",
  "numero": "001-001-000000149",
  "estado": "EN_PROCESO",
  "ambiente": "PRODUCCION",
  "fechaEmision": "2026-09-26",
  "fechaEnvio": "2026-09-26T09:15:04-05:00",
  "fechaAutorizacion": null,
  "numeroAutorizacion": null,
  "fechaActualizacion": "2026-09-26T09:15:04.120-05:00",
  "establecimiento": "001",
  "puntoEmision": "001",
  "referencia": "PED-2026-00482",
  "origen": "API",
  "total": 89.7,
  "cliente": {
    "tipoIdentificacion": "04",
    "identificacion": "0990000000001",
    "razonSocial": "CLIENTE DEMO S.A.",
    "email": "[email protected]",
    "direccion": null,
    "telefono": null
  },
  "items": [
    {
      "codigo": "P-001",
      "codigoAuxiliar": null,
      "descripcion": "Producto de ejemplo",
      "cantidad": 10,
      "precioUnitario": 7.8,
      "descuento": 0,
      "subtotal": 78,
      "codigoIva": "4",
      "tarifaIva": 15,
      "valorIva": 11.7,
      "detallesAdicionales": []
    }
  ],
  "pagos": [
    {
      "formaPago": "20",
      "total": 89.7,
      "plazo": null,
      "unidadTiempo": null
    }
  ],
  "guiaRemision": null,
  "totales": {
    "subtotal": 78,
    "descuento": 0,
    "subtotalesIva": [
      {
        "codigoIva": "4",
        "tarifa": 15,
        "baseImponible": 78,
        "valor": 11.7
      }
    ],
    "iva": 11.7,
    "propina": 0,
    "total": 89.7
  },
  "mensajes": [],
  "anulacion": null,
  "informacionAdicional": [],
  "enlaces": {
    "self": "https://api.golem.ec/v1/comprobantes/2609202601179000000000120010010000001498765432115",
    "pdf": null,
    "xml": null
  }
}

Errores: HTTP 400, 401, 402, 403, 409, 413, 415, 422, 429, 500, 503

Códigos de error de emitir una nota de crédito
HTTP	Código	Causa y solución
400	`JSON_INVALIDO`	El cuerpo no es un JSON válido. Revisa la sintaxis cerca de la línea y la columna que indica el mensaje.
400	`VALIDACION`	Uno o más campos no cumplen el formato. `detalles` lista cada campo con su código: `CAMPO_REQUERIDO`, `CAMPO_DESCONOCIDO`, `TIPO_INVALIDO`, `FORMATO_INVALIDO`, `VALOR_INVALIDO`, `LONGITUD_INVALIDA` o `DECIMALES_EXCEDIDOS`. Corrige los campos de `detalles`. Los campos que el API no conoce se rechazan: revisa los nombres.
400	`PARAMETRO_INVALIDO`	Un parámetro de la ruta o de la consulta no es válido: por ejemplo, una clave de acceso sin 49 dígitos, un rango de fechas de más de 366 días o un `cambiadoDesde` anterior a 90 días. Corrige el parámetro que indica `campo`.
400	`IDEMPOTENCY_KEY_INVALIDA`	La cabecera `Idempotency-Key` no tiene entre 8 y 100 caracteres, o usa caracteres distintos de letras, números, `-`, `_`, `.` y `:`. Genera la clave con un UUID v4.
400	`TOKEN_EN_URL`	La URL incluye `token`, `access_token` o `api_key`. Envía el token solo en la cabecera `Authorization`. Revoca ese token y crea otro: la URL pudo quedar en registros.
401	`TOKEN_REQUERIDO`	Falta la cabecera `Authorization`. Envía `Authorization: Bearer <token>`.
401	`TOKEN_INVALIDO`	El token no existe o no tiene el formato de un token de Golem. Copia el token completo, con su prefijo. Si no lo tienes, crea otro: Golem no puede mostrarlo de nuevo.
401	`TOKEN_REVOCADO`	El token fue revocado. Crea otro en Cuenta > API e integraciones.
402	`SIN_CREDITOS`	La empresa no tiene créditos para emitir o reprocesar. Compra una recarga en la aplicación. Las consultas y descargas siguen disponibles.
403	`EMPRESA_SUSPENDIDA`	La empresa no está activa. Afecta a las emisiones y las acciones; las consultas siguen disponibles. Escribe a [email protected].
403	`PUNTO_NO_PERMITIDO`	El token no puede emitir en ese punto de emisión, o está restringido y no tiene puntos. Usa uno de los puntos que devuelve `GET /empresa` en `token.puntosPermitidos`, o cambia los puntos del token en la aplicación.
403	`PLAN_NO_PERMITE`	El plan de la empresa no incluye la emisión de comprobantes electrónicos. Revisa el plan en la aplicación o escribe a [email protected].
409	`IDEMPOTENCIA_CUERPO_DISTINTO`	La `Idempotency-Key` ya se usó con otro cuerpo o en otra ruta. Usa una clave nueva para cada operación distinta y la misma clave solo para repetir la misma solicitud.
409	`IDEMPOTENCIA_EN_PROCESO`	La solicitud original con esa `Idempotency-Key` todavía se está procesando. Repite la solicitud después de los segundos de `Retry-After`.
413	`CUERPO_DEMASIADO_GRANDE`	El cuerpo supera 256 KB. Reduce el comprobante: admite hasta 200 ítems.
415	`TIPO_CONTENIDO_NO_SOPORTADO`	Una emisión llegó sin `Content-Type: application/json`. Envía el cuerpo como JSON con esa cabecera.
422	`PUNTO_EMISION_NO_EXISTE`	El establecimiento o el punto de emisión que indica la solicitud no existe en la empresa. Usa los códigos que devuelve `GET /empresa`.
422	`IDENTIFICACION_INVALIDA`	La cédula o el RUC no son válidos para el `tipoIdentificacion` indicado, o se indicó consumidor final como sujeto retenido. Sin `tipoIdentificacion`, una cédula o un RUC inválido responde `400 VALIDACION` (`CAMPO_REQUERIDO` en `tipoIdentificacion`), porque no se puede deducir el tipo. Corrige la identificación. Para pasaportes y documentos del exterior, indica `tipoIdentificacion` 06 u 08.
422	`TARIFA_IVA_NO_VIGENTE`	La tarifa de IVA no está vigente en la fecha del comprobante (en notas de crédito, en la fecha de la factura modificada). Usa una tarifa del catálogo `tarifas-iva` vigente en esa fecha.
422	`TARIFA_IVA_NO_COINCIDE`	En una nota de crédito sobre una factura de Golem, un ítem usa una tarifa de IVA que la factura no tiene. Usa en cada ítem una de las tarifas de la factura modificada.
422	`PAGOS_NO_CUADRAN`	La suma de `pagos` difiere del total de la factura en más de 0.01. Ajusta los pagos al total calculado, o usa `formaPago` para un solo pago por el total.
422	`TOTAL_NO_COINCIDE`	El total que calcula Golem difiere de `totalEsperado` en más de 0.01. El mensaje muestra el desglose. Compara el cálculo de tu sistema con el de la guía de facturas; con precios con IVA incluido, revisa la conversión.
422	`DESCUENTO_INVALIDO`	El descuento de una línea supera la cantidad por el precio unitario. Envía el descuento en dólares de la línea completa, sin superar su valor.
422	`CONSUMIDOR_FINAL_EXCEDE_LIMITE`	Una factura a consumidor final supera el tope que permite el SRI. Identifica al comprador con su cédula, RUC o pasaporte.
422	`FECHA_FUERA_DE_RANGO`	La fecha de emisión no es la de hoy ni la de ayer (hora de Ecuador), o es anterior a la del documento modificado o sustento. Omite `fechaEmision` para usar la de hoy. El SRI exige transmitir el comprobante al emitirlo.
422	`FIRMA_NO_VIGENTE`	La empresa no tiene firma electrónica o la firma venció. Carga una firma vigente en la aplicación.
422	`SIN_STOCK`	Un ítem usa un producto con control de inventario sin existencias suficientes. Registra el ingreso en la aplicación o quita el control de inventario del producto.
422	`SUSTENTO_NO_ENCONTRADO`	La factura que modifica la nota de crédito no existe en la empresa y el ambiente del token. Revisa la clave de acceso. Si la factura se emitió fuera de Golem, envía `codDoc`, `numero` y `fechaEmision`.
422	`SUSTENTO_NO_AUTORIZADO`	La factura que modifica la nota de crédito no está autorizada. Emite la nota de crédito cuando la factura esté autorizada.
422	`NOTA_CREDITO_EXCEDE_SALDO`	La nota de crédito, sumada a las anteriores de la misma factura, supera el total de la factura. Reduce el valor de la nota de crédito al saldo de la factura.
422	`CLIENTE_NO_COINCIDE`	La identificación de `cliente` no es la de la factura modificada. Omite `cliente`: se toma de la factura.
422	`CLIENTE_NO_PERMITIDO`	Una nota de crédito a consumidor final, o sobre una factura emitida a consumidor final. El SRI exige un receptor identificado en las notas de crédito.
422	`CODIGO_RETENCION_INVALIDO`	El código de retención no existe o no está vigente para ese impuesto. Usa un código de los catálogos `retenciones-renta` o `retenciones-iva`.
422	`PORCENTAJE_RETENCION_INVALIDO`	Falta `porcentaje` en un código de porcentaje variable, o el porcentaje enviado no coincide con el de un código de porcentaje fijo. Envía `porcentaje` solo en los códigos con porcentaje variable.
422	`SIN_CORREO`	El comprobante no tiene un correo de destino. El correo se toma del comprobante al emitirlo; en ese caso, envía el XML y el RIDE por tu cuenta.
429	`LIMITE_EXCEDIDO`	Se superó un límite de solicitudes por minuto. Repite la solicitud después de los segundos de `Retry-After`.
500	`ERROR_INTERNO`	Error inesperado de Golem. Si ocurrió al emitir, repite la solicitud con la misma `Idempotency-Key`. Escribe a [email protected] con el `requestId`.
503	`SRI_NO_DISPONIBLE`	El SRI no responde. Repite la solicitud después de los segundos de `Retry-After`.
503	`SERVICIO_NO_DISPONIBLE`	Un servicio interno de Golem no responde. Repite la solicitud después de los segundos de `Retry-After`.
503	`MANTENIMIENTO`	Golem está en mantenimiento. Los mantenimientos se avisan por correo con 24 horas de anticipación. Repite la solicitud después de los segundos de `Retry-After`.

Formato y lista completa en Errores.

Más ejemplos de solicitud

Nota de crédito de una factura emitida fuera de Golem, con la tarifa de IVA vigente en su fecha:

Nota de crédito de una factura de 2023 emitida fuera de Golem (IVA 12 %)

{
  "documentoModificado": {
    "codDoc": "01",
    "numero": "001-001-000004210",
    "fechaEmision": "2023-11-14"
  },
  "motivo": "Descuento posterior a la venta",
  "cliente": {
    "tipoIdentificacion": "04",
    "identificacion": "0990000000001",
    "razonSocial": "CLIENTE DEMO S.A.",
    "email": "[email protected]"
  },
  "items": [
    {
      "codigo": "DESC-2023",
      "descripcion": "Descuento sobre factura 001-001-000004210",
      "cantidad": 1,
      "precioUnitario": 25,
      "iva": 12
    }
  ]
}