Idempotencia

Repetir una petición con la misma Idempotency-Key devuelve la misma respuesta sin volver a emitir; cómo usar external_id y qué hacer tras un reinicio.

Ver como Markdown

Emitir un documento no se puede hacer «a ciegas dos veces»: duplicaría una factura. Por eso Idempotency-Key es obligatoria al crear o corregir un documento.

Evita los duplicados tras un reinicio

La clave automática de un SDK protege los reintentos de una misma llamada. Si tu proceso muere y vuelves a llamar, el SDK genera otra clave y podrías duplicar el documento. Manda siempre un external_id tuyo y una idempotencyKey derivada de tu venta (por ejemplo VENTA-2026-000123). Si la API responde external_id_in_use o duplicate_document, usa error.problem.existing_id para seguir con el documento que ya existe.

Cómo funciona

Manda un UUID nuevo (o una clave derivada de tu venta, de 1 a 255 caracteres ASCII visibles) por cada documento.
Repetir la misma clave con el mismo cuerpo (durante 7 días) devuelve la misma respuesta, con Idempotent-Replayed: true, sin volver a emitir.
La misma clave con otro cuerpo es idempotency_key_reused: nunca te devolvemos otro documento en silencio.
Si la primera petición no terminó (402, 503, o el 202 processing), el reintento con la misma clave sigue con el mismo documento y el mismo número. En la versión 2026-10-22, el reintento sobre un documento que Trevol está resolviendo no envía nada: responde otro 202 con el estado actual (o el 201 si ya se validó).
Mientras la primera petición sigue en curso, la segunda recibe request_in_progress (409): consulta su estado en unos segundos.

`external_id`

Tu identificador del documento, opcional. Repetido es external_id_in_use con el existing_id del que ya existe. Es la forma de que dos procesos distintos no emitan lo mismo.

En los SDK

Los SDK generan la Idempotency-Key si no la pasas y la repiten en todos los reintentos. Para controlarla, pásala tú:

POST /v1/invoices

cURL

curl -X POST "https://api.trevol.si/v1/invoices" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "VENTA-2026-000123",
  "customer": {
    "document_type": "31",
    "document_number": "900123456",
    "name": "COMERCIALIZADORA ANDINA SAS",
    "person_type": "legal",
    "email": "[email protected]",
    "address": "Calle 72 # 10-34, Oficina 501",
    "municipality_code": "11001"
  },
  "items": [
    {
      "code": "LIC-ANUAL",
      "description": "Licencia anual de software",
      "quantity": "2",
      "unit_price": "150000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "code": "SOP-MES",
      "description": "Soporte técnico mensual",
      "quantity": "1",
      "unit_price": "80000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ],
  "payment": {
    "form": "credit",
    "term_days": 30
  },
  "notes": [
    "Gracias por su compra"
  ]
}'

Probar en el Playground

En los fragmentos, el parámetro idempotencyKey (o su equivalente en cada lenguaje) viene comentado: descoméntalo con una clave derivada de tu venta. Las operaciones que no la declaran (por ejemplo POST /v1/webhook_endpoints o …/send) no la reciben.