Cómo reaccionar a un rechazo

Esta guía traduce cada respuesta del API en una acción concreta para tu integración. El objetivo es que tu sistema reaccione automáticamente y solo escale a un humano cuando hace falta.

Árbol de decisión

flowchart TD
    R[Respuesta de POST /facturas/insertar] --> H{Código HTTP?}
    H -- 401 --> A1[Revisar header ApiKey.<br/>No reintentar hasta corregir.]
    H -- 429 --> A2[Rate limit. Esperar Retry-After<br/>o 60s y reintentar el mismo batch.]
    H -- 503 --> A3[Servidor sin clave.<br/>Reportar a Hosana.]
    H -- 500 --> A4[Guardar batch_uuid.<br/>Reintentar con backoff; si persiste, escalar.]
    H -- 200 --> S{success y mensaje}
    H -- 422 --> M{leer 'motivo'}
    S -- ya procesado --> A5[Duplicado: tu envío anterior entró.<br/>No reenviar.]
    S -- normal --> A6[Éxito. Si hay pendientes_revision, registrar.]
    M -- FECHAS_INVALIDAS --> B1[Nada entró. Corregir fechas y reenviar.<br/>Usar manifiestos_validos·]
    M -- MANIFIESTOS_FECHA_INVALIDA --> B2[Nada entró. Reenviar con manifiesto nuevo.<br/>Usar manifiestos_no_afectados·]
    M -- ALMACENES / CERRADO / DUPLICADAS --> B3[Parte entró. Corregir los<br/>manifiestos_rechazados· y reenviarlos solos.]
    M -- MOTIVOS_MIXTOS --> B4[Recorrer manifiestos_rechazados·<br/>y tratar cada uno por su motivo.]

    style A6 fill:#dcf3e3,stroke:#1f8a4c,color:#14532d
    style A5 fill:#dcf3e3,stroke:#1f8a4c,color:#14532d

Cuando success: true pero hay pendientes_revision

Algunas facturas llegaron con diferencias respecto a una versión ya existente en el mismo manifiesto. Hosana no las sobrescribe: las marca para revisión manual y las lista en advertencias[].

Acción recomendada: registra cuáles facturas quedaron pendientes (advertencias[].factura y campos_con_cambio). No las reenvíes esperando que “se corrijan solas”: un humano de Hosana debe resolver el conflicto. Si el cambio fue intencional de tu lado, coordínalo con Hosana.

Rechazos de batch completo (nada entró)

motivo: FECHAS_INVALIDAS

La validación es por factura y atómica: una sola factura inválida rechaza el manifiesto completo. Recorre manifiestos_rechazados[] y mira el sub-motivo de cada uno; el detalle te dice exactamente qué facturas fallaron.

Sub-motivo	Dónde mirar	Acción
FECHA_FACTURA_FUTURA	detalle.facturas_futuras	Corrige la fecha en origen; no puede ser futura.
FECHA_FACTURA_DEMASIADO_ANTIGUA	detalle.facturas_antiguas	Saca del lote las facturas viejas; para cargarlas, coordina con Hosana (carga manual).
FECHA_FACTURA_INVALIDA	detalle.facturas_afectadas	Revisa el formato de la fecha.
FECHAS_MEZCLADAS	detalle.facturas_por_fecha	Solo aparece si Hosana activó el modo estricto; entonces separa por fecha.

Usa manifiestos_validos[] para reenviar los manifiestos que sí estaban bien, en un batch aparte.

motivo: MANIFIESTOS_FECHA_INVALIDA

Intentaste agregar facturas a manifiestos de días anteriores.

Acción: reenvía esas facturas bajo un número de manifiesto nuevo. Los manifiestos válidos que venían en el mismo batch están en manifiestos_no_afectados[]: reenvíalos solos.

Rechazos por manifiesto (parte entró)

Las facturas de los manifiestos válidos ya se insertaron. Solo debes corregir y reenviar los manifiestos listados en manifiestos_rechazados[].

motivo: ALMACENES_DESCONOCIDOS

Código de bodega no reconocido. Acción: corrige el Almacen (válidos: OAC, OAS, OAO) o pide a Hosana que registre la bodega. Reenvía el manifiesto limpio.

motivo: MANIFIESTO_CERRADO

El manifiesto ya está cerrado. Acción: usa un manifiesto nuevo, o coordina con Hosana si el cierre fue prematuro.

motivo: FACTURAS_DUPLICADAS_EN_OTRO_MANIFIESTO

Facturas que ya existen bajo otro manifiesto. El campo manifiesto_existente te dice dónde. Acción: quita las facturas duplicadas y reenvía el manifiesto limpio. Investiga por qué la misma factura apareció en dos manifiestos.

motivo: MOTIVOS_MIXTOS

Varios manifiestos rechazados por motivos distintos. Acción: recorre manifiestos_rechazados[] y trata cada entrada según su propio motivo.

Buenas prácticas de reintento

• Guarda siempre el batch_uuid de cada respuesta: es la clave para que Hosana rastree un caso.
• Es seguro reenviar el mismo batch ante un timeout: el detector de duplicados evita doble inserción el mismo día.
• No reenvíes en loop ante 401/503: son problemas de configuración.
• Corrige antes de reenviar ante 422: el mismo payload dará el mismo rechazo.
• Reenvía manifiestos válidos por separado cuando un rechazo de batch completo los haya arrastrado (manifiestos_validos[] / manifiestos_no_afectados[]).

Para ver estos motivos con request y response completos, revisa los casos resueltos.