Ir al contenido

Beta privada · apertura 23 de diciembre

Idempotencia

Si una petición se corta por la red, no sabes si llegó. Con Idempotency-Key puedes repetirla sin riesgo: si ya la procesamos, te devolvemos la misma respuesta y no se cobra dos veces ni se emite un segundo comprobante.

Envía un identificador único por operación, por ejemplo un UUID:

Ventana de terminal
curl -X POST "https://api-sandbox.opennexum.com/v1/emisores/20000000001/comprobantes" \
-H "Authorization: Bearer $ONX_CLAVE" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d @boleta.json
  • Formato: de 8 a 255 caracteres entre letras, números y . _ : -.
  • Obligatoria en toda operación que cobra (comprobantes, guías, SIRE, comprobante por WhatsApp) y en las que crean claves, recargas, resúmenes o webhooks. Sin ella, la API rechaza la petición.
  • Opcional en otras creaciones (emisores, series, conexiones, plantillas). Úsala igual.
  • No aplica a las lecturas.
  • Cada página de la referencia dice en su ficha si la cabecera es obligatoria.
Repites con Resultado
La misma clave y el mismo cuerpo La misma respuesta de la primera vez. No se cobra de nuevo.
La misma clave y otro cuerpo idempotencia_en_conflicto (HTTP 409).
La misma clave mientras la primera sigue en curso solicitud_en_curso (HTTP 409). Espera unos segundos y consulta.

La clave se guarda 24 horas.

  1. Genera la clave antes de la primera llamada y guárdala junto a la operación.
  2. Si hay un corte, un tiempo agotado o un error_interno, repite con la misma clave y el mismo cuerpo.
  3. Si quieres hacer una operación distinta, genera una clave nueva.
  4. Un 202 no se repite: en_cola se completa solo y requiere_confirmacion espera a una persona. Mira Para agentes de IA.