Inicio rápido

Esta guía te lleva de cero a un e-Ticket emitido contra el entorno de homologación, que es el indicado para probar la integración. Cada paso enlaza a la página que lo explica en detalle.

Entorno	URL base
Homologación / pruebas	https://testing.hostfactura.com.uy/api
Producción	https://hostfactura.com.uy/api

1. Conseguí una API_KEY de homologación

   En el panel de Host Factura, entrá a Configuración → API y creá un Access. Sin elegir alcances, la credencial nace con el preset Solo facturación (cfe:emitir, cfe:leer, consultas), que alcanza para esta guía. La clave se muestra una sola vez: guardala en tu gestor de secretos.

   Detalle de credenciales, alcances y headers en Autenticación y contexto.

2. Verificá la credencial con GET /v1/echo

   El echo no emite nada: te devuelve qué cuenta, sucursal y punto de emisión resuelve la API con los headers que mandás. Usalo también como health check de tu integración.

   curl

   curl https://testing.hostfactura.com.uy/api/v1/echo \
     -H "Authorization: Bearer $HOSTFACTURA_API_KEY"

   Node.js

   echo.mjs

   const res = await fetch("https://testing.hostfactura.com.uy/api/v1/echo", {
     headers: { Authorization: `Bearer ${process.env.HOSTFACTURA_API_KEY}` },
   });
   console.log(await res.json());

   PHP

   echo.php

   <?php
   $ch = curl_init('https://testing.hostfactura.com.uy/api/v1/echo');
   curl_setopt_array($ch, [
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('HOSTFACTURA_API_KEY')],
   ]);
   echo curl_exec($ch);

   Si la respuesta trae data.cuenta con la razón social de tu empresa, la credencial funciona. Un 401 indica una clave inválida o rotada.

3. Emití un e-Ticket con POST /v1/cfe/emitir

   El caso más simple: un e-Ticket (tipo: 101) a consumidor final, sin datos del receptor. Mandás los ítems con su tratamiento de IVA (billingIndex: 3 es tasa básica) y Host Factura arma el XML, calcula totales, asigna CAE y numeración, firma y envía a DGI.

   curl

   curl https://testing.hostfactura.com.uy/api/v1/cfe/emitir \
     -H "Authorization: Bearer $HOSTFACTURA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "tipo": 101,
       "moneda": "UYU",
       "formaPago": 1,
       "items": [
         { "name": "Café americano", "quantity": 2, "price": 90, "billingIndex": 3 },
         { "name": "Medialuna", "quantity": 1, "price": 60, "billingIndex": 3 }
       ]
     }'

   Node.js

   emitir.mjs

   const res = await fetch("https://testing.hostfactura.com.uy/api/v1/cfe/emitir", {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.HOSTFACTURA_API_KEY}`,
       "Content-Type": "application/json",
     },
     body: JSON.stringify({
       tipo: 101,
       moneda: "UYU",
       formaPago: 1,
       items: [
         { name: "Café americano", quantity: 2, price: 90, billingIndex: 3 },
         { name: "Medialuna", quantity: 1, price: 60, billingIndex: 3 },
       ],
     }),
   });
   
   const { data, error } = await res.json();
   if (error) throw new Error(`${error.code}: ${error.message}`);
   console.log(data.id, data.serie, data.numero, data.estado);

   PHP

   emitir.php

   <?php
   $payload = [
       'tipo'      => 101,
       'moneda'    => 'UYU',
       'formaPago' => 1,
       'items'     => [
           ['name' => 'Café americano', 'quantity' => 2, 'price' => 90, 'billingIndex' => 3],
           ['name' => 'Medialuna', 'quantity' => 1, 'price' => 60, 'billingIndex' => 3],
       ],
   ];
   
   $ch = curl_init('https://testing.hostfactura.com.uy/api/v1/cfe/emitir');
   curl_setopt_array($ch, [
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_POST           => true,
       CURLOPT_HTTPHEADER     => [
           'Authorization: Bearer ' . getenv('HOSTFACTURA_API_KEY'),
           'Content-Type: application/json',
       ],
       CURLOPT_POSTFIELDS     => json_encode($payload),
   ]);
   
   $respuesta = json_decode(curl_exec($ch), true);
   if (isset($respuesta['error'])) {
       throw new RuntimeException($respuesta['error']['code'] . ': ' . $respuesta['error']['message']);
   }
   $cfe = $respuesta['data'];
   echo "{$cfe['id']} {$cfe['serie']}-{$cfe['numero']} {$cfe['estado']}\n";

   Para empresas con RUT, moneda extranjera, notas de crédito o cobranzas, cambiá solo el cuerpo: hay un ejemplo de cada caso en Emisión de CFE.

   Guardá el data.id (UUID del CFE): es la referencia para consultarlo, descargar el PDF o emitir una nota de crédito después.

4. Revisá el estado en DGI

   La respuesta trae data.estado: aceptado, pendiente, observado o rechazado. Si es observado o rechazado, el motivo viene en motivoRechazo. Qué significa cada uno, en Estados del CFE.

   Si la emisión falla con 409 NO_CAE_VIGENTE u otro error de cuenta, revisá los pre-requisitos de la cuenta.

5. Descargá el PDF

   GET /v1/cfe/pdf/{id} devuelve el comprobante con el QR de DGI. El parámetro formato elige entre a4 y ticket (rollo térmico).

   curl "https://testing.hostfactura.com.uy/api/v1/cfe/pdf/$CFE_ID?formato=ticket" \
     -H "Authorization: Bearer $HOSTFACTURA_API_KEY" \
     -o comprobante.pdf

Próximos pasos

• Elegí el comprobante que corresponde a cada operación en Tipos de CFE.
• Facturá a empresas, en moneda extranjera o con notas de crédito: Emisión de CFE.
• Enterate de cada cambio de estado sin consultar la API: Webhooks.
• Todos los endpoints, parámetros y errores: Referencia de la API.