Receptores

Antes de emitir podés confirmar que la identificación de un receptor es válida, sin crear ningún documento.

curl -X POST https://api.timbrecr.com/core/v1/receivers/validate \
  -H "Authorization: Bearer timbre_sk_…" \
  -H 'Content-Type: application/json' \
  -d '{
    "identificacion": { "tipo": "02", "numero": "3101123456" }
  }'

{
  "status": "valid",
  "source": "registry",
  "checkedAt": "2026-09-24T14:02:00.000Z"
}

status

• valid: el registro de Hacienda confirma la identificación.
• invalid: el registro la rechaza explícitamente.
• unknown: no se pudo confirmar (por ejemplo, el registro no respondió a tiempo); revisá warning para el motivo.

source

De dónde salió la respuesta:

• registry: se le preguntó al registro de Hacienda en ese momento.
• cache: Hacienda ya había respondido por esa identificación hace poco y se reusó su respuesta.
• local: no se consultó el registro, porque el formato ya era inválido o porque la política es disabled.

policy

Por defecto se usa la política configurada del proyecto. Podés forzar una distinta por request:

• required: la respuesta siempre es 200. No hay un código de error para un rechazo bajo esta política: la integración es responsable de tratar cualquier status distinto de valid como rechazado.
• best_effort: se valida si se puede, pero nunca bloquea.
• disabled: no se consulta el registro; responde unknown, salvo que el formato local ya sea inválido (el chequeo de formato corre antes de aplicar la política, así que "disabled" no significa "siempre unknown").

curl -X POST https://api.timbrecr.com/core/v1/receivers/validate \
  -H "Authorization: Bearer timbre_sk_…" \
  -H 'Content-Type: application/json' \
  -d '{
    "identificacion": { "tipo": "02", "numero": "3101123456" },
    "policy": "best_effort"
  }'

Cuando el registro no responde a tiempo, warning explica por qué:

{
  "status": "unknown",
  "source": "registry",
  "checkedAt": "2026-09-24T14:02:00.000Z",
  "warning": "Hacienda registry was unreachable or timed out; the receiver could not be confirmed (required policy)"
}