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.
Cómo usarla
Sección titulada «Cómo usarla»Envía un identificador único por operación, por ejemplo un UUID:
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.
Qué pasa al repetir
Sección titulada «Qué pasa al repetir»| 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.
Reglas para reintentar
Sección titulada «Reglas para reintentar»- Genera la clave antes de la primera llamada y guárdala junto a la operación.
- Si hay un corte, un tiempo agotado o un
error_interno, repite con la misma clave y el mismo cuerpo. - Si quieres hacer una operación distinta, genera una clave nueva.
- Un
202no se repite:en_colase completa solo yrequiere_confirmacionespera a una persona. Mira Para agentes de IA.