API v1.0.0 · FUNCIONAMIENTO

Idempotencia

Si la conexión se corta durante una emisión, no sabes si el comprobante se creó. Con la cabecera Idempotency-Key puedes repetir la solicitud sin crear un comprobante duplicado ni consumir otro crédito.

Cómo funciona

Envía en cada emisión (factura, nota de crédito o retención) una clave única generada por tu sistema:

Terminal

# 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: e9a03c57-2d4b-4f18-a6c9-5b7e1d0f3a62" \
  -d @factura.json

Si repites la solicitud con la misma clave y el mismo cuerpo, Golem no crea otro comprobante: responde con el comprobante que creó la primera vez, en su estado actual, y agrega la cabecera Idempotent-Replayed: true.

Reglas

Formato: de 8 a 100 caracteres, con letras, números, -, _, . o :. Se recomienda un UUID v4. Otro formato responde 400 IDEMPOTENCY_KEY_INVALIDA.
Vigencia: 24 horas desde la primera solicitud. Después, la misma clave corresponde a una operación nueva.
Ámbito: la clave vale por empresa y por ambiente. La misma clave con un token de pruebas y con uno de producción son dos operaciones distintas.
Cuerpo: se compara el contenido del JSON. El orden de los campos, los espacios y los ceros a la derecha de los decimales (7.8 y 7.80) no lo cambian.
Opcional: sin la cabecera, cada solicitud crea un comprobante.

Respuestas al repetir una clave

Situación	Respuesta
La solicitud original creó el comprobante	El comprobante en su estado actual: `201` si es final, `202` si sigue `EN_PROCESO`, con `Idempotent-Replayed: true`. No consume otro crédito.
La solicitud original todavía se está procesando	`409 IDEMPOTENCIA_EN_PROCESO` con `Retry-After`. Repite después de esos segundos.
La clave se usó con otro cuerpo o en otra ruta	`409 IDEMPOTENCIA_CUERPO_DISTINTO`. No se crea nada.
La solicitud original terminó en error sin crear el comprobante (por ejemplo `400`, `402` o `422`)	La clave queda libre: corrige los datos y repite con la misma clave.

La respuesta repetida no es una copia de la primera: trae el estado actual del comprobante. Un reintento después de un 202 puede recibir el 201 con el estado final.

Recomendaciones

Genera la clave cuando tu sistema decide emitir el comprobante y guárdala junto al pedido o la venta, antes de llamar al API. Así un reintento después de un reinicio usa la misma clave.
Usa una clave distinta para cada comprobante. Si usas el número de pedido, agrega el tipo: factura-PED-1001 y nc-PED-1001.
Para emitir un comprobante nuevo que reemplace a uno devuelto, usa una clave nueva: con la misma, recibirías el comprobante devuelto.
Configura un tiempo de espera del cliente de al menos 30 segundos y reintenta con espera creciente (por ejemplo 1, 2, 4 y 8 segundos).

Node.js 18+

import { randomUUID } from 'node:crypto';

// Genera la clave una vez y guárdala con el pedido antes de emitir.
const clave = pedido.idempotencyKey ?? (pedido.idempotencyKey = randomUUID());

const respuesta = await fetch('https://api.golem.ec/v1/comprobantes/facturas', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GOLEM_TOKEN}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': clave,
  },
  body: JSON.stringify(factura),
  signal: AbortSignal.timeout(30_000),
});

Sin Idempotency-Key

Cada solicitud crea un comprobante y consume un crédito. Si una emisión sin clave termina en un error de red o en 500, busca el comprobante antes de reintentar:

Terminal

curl "https://api.golem.ec/v1/comprobantes?referencia=PED-2026-00481" \
  -H "Authorization: Bearer $GOLEM_TOKEN"

Para eso, envía en cada emisión el campo referencia con el identificador del documento en tu sistema. referencia no tiene que ser única y no reemplaza a Idempotency-Key: sirve para buscar.