Inicio rápido

Esta guía te lleva de cero a una integración funcional en tres pasos. Asume que ya tienes tu ApiKey y el dominio de Hosana. La forma más cómoda de probar es con Postman; si ya integras desde código, las pestañas traen el equivalente en PHP, Node y C#.

Si vas a usar Postman, conviene importar primero la colección lista, que ya trae las cuatro peticiones armadas con una factura real de ejemplo.

Verifica conectividad
Sección titulada «Verifica conectividad»

El health check no requiere ApiKey, así que sirve para confirmar que llegas al servidor.
- Método GET
- URL: https://<dominio-hosana>/api/v1/ping
- Send
Ventana de terminal
curl -X GET "https://<dominio-hosana>/api/v1/ping"
$res = $client->get('ping'); echo json_decode($res->getBody(), true)['status']; // "ok"
const res = await fetch("https://<dominio-hosana>/api/v1/ping"); console.log((await res.json()).status); // "ok"
var data = await http.GetFromJsonAsync<JsonElement>("ping"); Console.WriteLine(data.GetProperty("status").GetString()); // "ok"
Respuesta:
```
{ "status": "ok", "service": "Distribuidora Hosana API", "version": "v1", "timestamp": "2026-06-05T08:30:00-06:00" }
```

Inserta un lote de facturas

Se envía un array JSON de facturas. El siguiente es un ejemplo real: una factura del manifiesto 800002, bodega OAC, con sus datos fiscales (RTN, CAI), importes e ISV, y dos líneas de producto.

Método POST, URL https://<dominio-hosana>/api/v1/facturas/insertar
Pestaña Headers: ApiKey con tu clave
Pestaña Body → raw → JSON, y pega:

[
  {
    "Nfactura": "002-001-01-04001001",
    "NumeroManifiesto": "800002",
    "FechaFactura": "2026-06-05T00:00:00.000Z",
    "FechaVencimiento": "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",
    "Depto": "LA PAZ",
    "Municipio": "Santiago de Puringla",
    "Direccion": "BARRIO LAS BRISAS, SANTIAGO DE PURINGLA, LA PAZ",
    "Tel": "97689223",
    "NumeroPedido": "6915760",
    "NumeroRuta": "230",
    "NumeroFacturaLX": "4001001",
    "TipoPago": "CONTADO",
    "DiasCred": 0,
    "TipoFactura": "FAC",
    "EstadoFactura": 1,
    "ImporteGrabado": 878.29,
    "ImporteGravado_ISV15": 131.75,
    "ImporteGravado_Total": 1010.04,
    "Isv15": 131.75,
    "Isv18": 0.0,
    "DescuentosRebajas": 0.0,
    "Total": 1010.04,
    "LineasFactura": [
      {
        "Id": 3001001,
        "InvoiceId": 700101,
        "NumeroLinea": 1,
        "ProductoId": "30110205",
        "ProductoDesc": "ORISOL LIGHT OLIVA 410 mL 1/24 HN",
        "UniVenta": "UN",
        "TipoProducto": "A",
        "CantidadFracciones": 6.0,
        "CantidadCaja": 0.0,
        "FactorConversion": 24,
        "Precio": 748.8,
        "PrecioUnidadMinVenta": 31.2,
        "Subtotal": 187.2,
        "Descuento": 0.0,
        "Impuesto": 28.08,
        "PorcentajeImpuesto": 15.0,
        "Total": 215.28,
        "Peso": 2.3115
      },
      {
        "Id": 3001002,
        "InvoiceId": 700101,
        "NumeroLinea": 2,
        "ProductoId": "81800012",
        "ProductoDesc": "KETCHUP 8X12X87GR",
        "UniVenta": "UN",
        "TipoProducto": "A",
        "CantidadFracciones": 12.0,
        "CantidadCaja": 0.0,
        "FactorConversion": 96,
        "Precio": 642.11,
        "PrecioUnidadMinVenta": 6.6883,
        "Subtotal": 80.26,
        "Descuento": 0.0,
        "Impuesto": 12.04,
        "PorcentajeImpuesto": 15.0,
        "Total": 92.3,
        "Peso": 1.195
      }
    ]
  }
]

curl -X POST "https://<dominio-hosana>/api/v1/facturas/insertar" \
  -H "ApiKey: TU_CLAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d @factura-800002.json

Donde factura-800002.json contiene el array de facturas (el mismo JSON de la pestaña Postman). Para lotes reales conviene mandar el cuerpo desde un archivo.

$facturas = [[
    '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',
    'Total'            => 1010.04,
    'Isv15'            => 131.75,
    '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,
        ],
        [
            'NumeroLinea' => 2, 'ProductoId' => '81800012',
            'ProductoDesc' => 'KETCHUP 8X12X87GR', 'UniVenta' => 'UN',
            'CantidadFracciones' => 12.0, 'FactorConversion' => 96,
            'Precio' => 642.11, 'Impuesto' => 12.04, 'Total' => 92.30,
        ],
    ],
]];

$response = $client->post('facturas/insertar', [
    'headers' => ['ApiKey' => 'TU_CLAVE_AQUI'],
    'json'    => $facturas,
]);

const facturas = [{
  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",
  Total: 1010.04,
  Isv15: 131.75,
  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 },
    { NumeroLinea: 2, ProductoId: "81800012", ProductoDesc: "KETCHUP 8X12X87GR", UniVenta: "UN", CantidadFracciones: 12.0, FactorConversion: 96, Precio: 642.11, Impuesto: 12.04, Total: 92.30 },
  ],
}];

const res = await fetch("https://<dominio-hosana>/api/v1/facturas/insertar", {
  method: "POST",
  headers: { "ApiKey": "TU_CLAVE_AQUI", "Content-Type": "application/json" },
  body: JSON.stringify(facturas),
});

var facturas = new[] { new {
    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",
    Total = 1010.04,
    Isv15 = 131.75,
    LineasFactura = new object[] {
        new { 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 },
        new { NumeroLinea = 2, ProductoId = "81800012", ProductoDesc = "KETCHUP 8X12X87GR", UniVenta = "UN", CantidadFracciones = 12.0, FactorConversion = 96, Precio = 642.11, Impuesto = 12.04, Total = 92.30 }
    }
}};

var res = await http.PostAsJsonAsync("facturas/insertar", facturas);

Respuesta:

{
  "success": true,
  "message": "Facturas procesadas correctamente.",
  "batch_uuid": "9f1c2a7e-3b4d-4f1a-8c2e-1a2b3c4d5e6f",
  "manifiestos": ["800002"],
  "resumen": { "recibidas": 1, "insertadas": 1, "actualizadas": 0, "sin_cambios": 0, "pendientes_revision": 0, "rechazadas": 0 }
}

Consulta las devoluciones del día

La fecha que quieres consultar va en el header Fecha, con formato dd/MM/yyyy.

Método GET, URL https://<dominio-hosana>/api/v1/devoluciones/listar
Pestaña Headers: ApiKey con tu clave, y Fecha con 05/06/2026
Send

curl -X GET "https://<dominio-hosana>/api/v1/devoluciones/listar" \
  -H "ApiKey: TU_CLAVE_AQUI" \
  -H "Fecha: 05/06/2026"

$res = $client->get('devoluciones/listar', [
    'headers' => ['ApiKey' => 'TU_CLAVE_AQUI', 'Fecha' => '05/06/2026'],
]);
$devoluciones = json_decode($res->getBody(), true);

const res = await fetch("https://<dominio-hosana>/api/v1/devoluciones/listar", {
  headers: { "ApiKey": "TU_CLAVE_AQUI", "Fecha": "05/06/2026" },
});
const devoluciones = await res.json();

using var req = new HttpRequestMessage(HttpMethod.Get, "devoluciones/listar");
req.Headers.Add("Fecha", "05/06/2026");
var res = await http.SendAsync(req);

La respuesta es un array de devoluciones, o [] si no hubo ese día.

Siguiente paso

Probar con Postman — la colección y la configuración en detalle.
Pipeline de inserción — el orden de las validaciones.
Cómo reaccionar a un rechazo — qué hacer ante cada motivo.
Casos resueltos — escenarios completos con request y response.

Inicio rápido

Verifica conectividad

Inserta un lote de facturas

Consulta las devoluciones del día

Siguiente paso