Convenciones del API

Convenciones transversales que aplican a todos los endpoints. Conviene leerlas antes de integrar cualquier endpoint específico.

Base URL y versión

https://<dominio-hosana>/api/v1/

La versión v1 es parte de la ruta. Todos los ejemplos de esta documentación asumen ese prefijo.

Tipo de contenido

• Las solicitudes con cuerpo (POST) deben enviar Content-Type: application/json.
• Todas las respuestas son application/json; charset=utf-8.

Forma de las respuestas

Casi todas las respuestas siguen una estructura predecible:

{
  "success": true,
  "message": "Texto legible para humanos.",
  "...": "campos específicos del endpoint"
}

Campo	Tipo	Significado
success	boolean	true si la operación se completó sin rechazos; false si hubo error o rechazo.
message	string	Descripción legible del resultado. Útil para logs y soporte.
motivo	string	(Solo en rechazos) Código máquina del motivo. Ver catálogo de errores.

success no equivale a HTTP 200

El endpoint insertar puede responder HTTP 422 con success: false cuando algunos manifiestos fueron rechazados, aunque otros se hayan procesado. Siempre evalúa el cuerpo, no solo el código HTTP.

Códigos HTTP

HTTP	Significado en este API
200	Operación exitosa. (También se usa para batches duplicados ya procesados.)
404	El recurso consultado no existe (p. ej. manifiesto inexistente en estado).
401	Falta el ApiKey o es inválido.
422	El payload o las reglas de negocio rechazaron la solicitud. El cuerpo trae el detalle.
429	Se superó el rate limit del endpoint.
500	Error interno en Hosana al procesar. El equipo técnico es notificado automáticamente.
503	El servidor no está configurado para recibir solicitudes (falta clave).

Formatos de fecha

Este es un punto frecuente de errores. El API acepta varios formatos de fecha según el contexto:

En el payload de facturas (FechaFactura, FechaVencimiento, etc.)

Se aceptan todos estos formatos:

Formato	Ejemplo	Nota
ISO 8601 con Z y milisegundos	2025-12-28T00:00:00.000Z	Formato real de Jaremar (recomendado)
ISO 8601 con Z	2025-12-28T00:00:00Z
ISO 8601 sin zona	2025-12-28T00:00:00
Fecha plana	2025-12-28
Latinoamericano	28/12/2025	dd/mm/yyyy (pruebas / Postman)

Recomendación sobre la zona horaria

Hosana opera en America/Tegucigalpa (UTC-6, sin horario de verano). Un timestamp T00:00:00Z se interpreta como ese día calendario (no se le restan 6 horas). Para evitar ambigüedad, envía fechas planas (2025-12-28) o timestamps a medianoche UTC. Ver el detalle en reglas de fecha.

En el header Fecha (endpoint de devoluciones)

El endpoint listar devoluciones exige estrictamente el formato dd/MM/yyyy:

Fecha: 17/12/2025

Cualquier otro formato responde 422.

Idempotencia y reintentos

• insertar detecta batches duplicados por hash del contenido durante el mismo día. Si reenvías un batch idéntico, recibes 200 con el resumen del proceso original, sin duplicar facturas. Es seguro reintentar ante un timeout.
• listar devoluciones es de solo lectura; reintentar no tiene efectos secundarios.