Probar el API con Postman

Postman es la forma más rápida de probar el API mientras desarrollas la integración. Esta página explica cómo dejarlo configurado y cómo se arma cada petición. Si prefieres no configurar nada a mano, importa la colección que ya viene lista.

Colección lista para importar

Descarga el archivo y, en Postman, usa Import (botón arriba a la izquierda) y suelta el archivo:

Descargar colección de Postman

La colección trae las cuatro peticiones (ping, insertar facturas, estado de manifiesto y listar devoluciones) ya armadas, con sus headers y un cuerpo de ejemplo.

Configurar las variables

La colección usa dos variables para no repetir el dominio ni la clave en cada petición. Después de importarla, haz clic derecho sobre la colección → Edit → pestaña Variables, y completa:

Variable	Qué poner	Ejemplo
baseUrl	El dominio de Hosana (sin barra al final).	https://api.hosana.hn
apiKey	La clave que te entregó Hosana.	a1b2c3d4...

Guarda con Save. A partir de ahí, todas las peticiones usan {{baseUrl}} y {{apiKey}} automáticamente.

Configuración manual (sin la colección)

Si prefieres armar las peticiones tú mismo, esto es lo que necesita cada una.

1. La autenticación va en Headers

En cualquier petición protegida, ve a la pestaña Headers y agrega una fila:

Key	Value
ApiKey	tu clave

El nombre del header es exactamente ApiKey. No es Authorization ni X-Api-Key. Si lo escribes distinto, recibirás un 401.

2. Para insertar facturas, el cuerpo va en Body

1. Método POST, URL {{baseUrl}}/api/v1/facturas/insertar.

2. Pestaña Headers: agrega ApiKey. (Postman pone el Content-Type: application/json solo al elegir el tipo de cuerpo en el paso siguiente.)

3. Pestaña Body → selecciona raw → en el desplegable de la derecha elige JSON. Pega el array de facturas (ejemplo real de Jaremar):

   [
     {
       "Nfactura": "002-001-01-04001001",
       "NumeroManifiesto": "800002",
       "FechaFactura": "2026-06-05T00:00:00.000Z",
       "Almacen": "OAC",
       "Vendedorid": "11983",
       "Vendedor": "WALTER REYNALDO MARADIAGA",
       "Clienteid": "98065401",
       "Cliente": "PULPERIA ASLYN",
       "Rtn": "12181986001440",
       "Cai": "2F0037-619ACD-2A66E0-63BE03-0909DC-56",
       "Isv15": 131.75,
       "Total": 1010.04,
       "LineasFactura": [
         {
           "NumeroLinea": 1,
           "ProductoId": "30110205",
           "ProductoDesc": "ORISOL LIGHT OLIVA 410 mL 1/24 HN",
           "UniVenta": "UN",
           "CantidadFracciones": 6.0,
           "FactorConversion": 24,
           "Precio": 748.8,
           "Impuesto": 28.08,
           "Total": 215.28
         }
       ]
     }
   ]

4. Send. La respuesta aparece abajo; revisa el código (200 o 422) y el cuerpo.

3. Para listar devoluciones, la fecha va en Headers

El endpoint de devoluciones no lleva cuerpo. La fecha que quieres consultar va como un header, no como query param obligatorio:

Key	Value
ApiKey	tu clave
Fecha	06/06/2026

El formato del header Fecha es dd/MM/yyyy. La paginación, si la necesitas, va en la URL: {{baseUrl}}/api/v1/devoluciones/listar?pagina=1.

Leer la respuesta

El código HTTP no basta para saber si todo salió bien. El endpoint de inserción puede devolver 422 con algunas facturas insertadas y otras rechazadas. Mira siempre el cuerpo:

• success indica si hubo o no rechazos.
• resumen trae los conteos (insertadas, rechazadas, etc.).
• motivo y manifiestos_rechazados aparecen cuando algo se rechazó.

El significado de cada campo está en insertar facturas y en el catálogo de errores.