Autenticación

La API usa tres niveles de autenticación según el endpoint.

API Key

Toda request lleva tu API key en el header:

X-API-Key: <tu_api_key>

La key (y el client_secret para HMAC) se entregan fuera de banda al firmar contrato con Trisenda.

Firma HMAC (solo para POST /v1/events)

Las escrituras requieren, además del API key, dos headers:

X-Trisenda-Timestamp: <unix segundos UTC>
X-Trisenda-Signature: <hex HMAC-SHA256>

La firma es HMAC-SHA256(client_secret, timestamp + "." + raw_body).

Reglas:

• El timestamp es unix en segundos UTC y debe estar dentro de una ventana de 300s (anti-replay).
• Firma el raw body, no el body re-serializado.
• Incluye un header Idempotency-Key único por operación: el mismo key con el mismo body retorna el mismo event_id sin duplicar.

TS=$(date +%s)
SIG=$(echo -n "${TS}.${BODY}" | openssl dgst -sha256 -hmac "$CLIENT_SECRET" -hex | cut -d' ' -f2)

OTP (Reporte Especial)

El paso 2 del Reporte Especial se autentica con un OTP de 6 dígitos enviado al email del titular: vive 10 minutos, es de un solo uso, admite 3 intentos máximo, y hay un rate limit de 1 OTP por titular cada 60s.

Errores

Todos los errores comparten el mismo schema:

{
  "error": "invalid_signature",
  "message": "X-Trisenda-Signature no coincide con HMAC-SHA256(client_secret, X-Trisenda-Timestamp + '.' + raw_body).",
  "request_id": "fca1f013-217b-5ef7-bbe7-96009dedb7ae",
  "hint": "Verifica que el timestamp esté en segundos UTC y que estés firmando el raw body."
}