Vista general

Host Factura — API pública v1 (1.0.0)

Host Factura API v1

API REST para emisión, consulta y gestión de Comprobantes Fiscales Electrónicos (CFE) en Uruguay, integrada con DGI (Dirección General Impositiva). Pensada para integraciones con POS, e-commerce, ERPs y cualquier sistema que necesite emitir facturación electrónica sin armar la integración SOAP/XML contra DGI desde cero.

Convenciones generales

Estructura común de respuesta

Todas las respuestas JSON exitosas tienen el formato:

{ "data": <T>, "meta": { ... } }

• data contiene el recurso o lista.
• meta aparece solo cuando hay metadata adicional (paginación, etc.).

Todas las respuestas de error tienen el formato:

{
  "error": { "code": "CODIGO_ESTABLE", "message": "Mensaje legible en español", "details": { ... } },
  "requestId": "uuid-de-correlación"
}

• code es un identificador estable en SCREAMING_SNAKE_CASE. Usá este campo para lógica condicional, no el message.
• message puede cambiar entre versiones; no parsearlo.
• requestId es el mismo que se devuelve en el header X-Request-ID. Incluilo en tickets de soporte.

Idioma

La API es enteramente en español: campos de DTOs, mensajes de error, descripciones. Los códigos de error son en inglés porque son identificadores técnicos.

Headers comunes

Header	Tipo	Cuándo
Authorization: Bearer <API_KEY>	obligatorio	Siempre
x-branch-id: <uuid>	opcional	Operar contra una sucursal específica cuando el ApiAccess es global
x-point-id: <uuid>	opcional	Cuando la sucursal tiene 2+ puntos de emisión activos
X-Request-ID: <uuid>	opcional	Si lo enviás, se respeta; si no, lo genera el servidor

Rate limits

• Cuentas estándar: 60 requests/minuto por ApiAccess.
• Cuentas proveedor (revendedor / proveedor de facturación electrónica): 600 requests/minuto.

Los headers de cada respuesta incluyen:

• RateLimit-Limit: cuota total en la ventana.
• RateLimit-Remaining: cuántos requests te quedan.
• RateLimit-Reset: segundos hasta que se resetea la ventana.

Al exceder el límite recibís 429 API_RATE_LIMITED con header Retry-After: <segundos>.

Sucursales y puntos de emisión

• Si tu ApiAccess está fijado a una sucursal, todas las emisiones se atribuyen a esa sucursal. Si enviás x-branch-id con un valor distinto, recibís 403 API_ACCESS_BRANCH_MISMATCH.
• Si tu ApiAccess es global, podés enviar x-branch-id para apuntar a una sucursal específica. Sin el header, se asume la casa central.
• Si la sucursal resuelta tiene 2 o más puntos de emisión activos, es obligatorio enviar x-point-id. Con uno solo, se selecciona automáticamente.

Códigos de error globales

Estos pueden devolverse en cualquier endpoint:

HTTP	Code	Causa
401	API_AUTH_HEADER_MISSING	Falta el header Authorization o no es Bearer
401	API_AUTH_HEADER_INVALID	El esquema no es Bearer
401	API_ACCESS_INVALID	La API_KEY no existe, fue rotada o el access está active=false
403	API_FEATURE_DISABLED	El plan de la cuenta no tiene la API habilitada
403	API_ACCESS_BRANCH_MISMATCH	x-branch-id distinto a la sucursal fijada en el access
400	SUCURSAL_INVALIDA	x-branch-id no existe, no pertenece o está inactiva
400	PUNTO_EMISION_INVALIDO	x-point-id no pertenece a la sucursal resuelta
400	PUNTO_EMISION_REQUERIDO	Sucursal con múltiples puntos: x-point-id es obligatorio
429	API_RATE_LIMITED	Excediste el rate limit. Esperá según Retry-After

---

Tipos de Comprobante Fiscal Electrónico (CFE)

Un CFE es el documento fiscal con validez legal que reemplaza a las facturas y tiques en papel en Uruguay. DGI define un tipo de CFE por cada clase de operación (venta a consumidor final, venta a empresa, exportación, traslado de mercadería, retención de impuestos, etc.). Cada tipo:

• tiene un código numérico (101 a 182),
• se serializa en un nodo XML propio (eTck, eFact, eFact_Exp, eRem, eResg, eBoleta),
• y tiene reglas de validación específicas (qué campos son obligatorios, si el receptor debe identificarse, cómo se trata el IVA, etc.).

Al emitir por POST /v1/cfe/emitir solo indicás el código en el campo tipo; Host Factura arma el nodo XML correcto, calcula totales e IVA, asigna CAE y numeración, firma y envía a DGI.

Tabla de referencia rápida

Código	Descripción	Nodo XML	Receptor
101	e-Ticket	eTck	Opcional (consumidor final)
102	Nota de Crédito e-Ticket	eTck	Heredado de la referencia
103	Nota de Débito e-Ticket	eTck	Heredado de la referencia
111	e-Factura	eFact	Obligatorio
112	Nota de Crédito e-Factura	eFact	Heredado de la referencia
113	Nota de Débito e-Factura	eFact	Heredado de la referencia
121	e-Factura Exportación	eFact_Exp	Obligatorio
122	Nota de Crédito e-Factura Exportación	eFact_Exp	Heredado de la referencia
123	Nota de Débito e-Factura Exportación	eFact_Exp	Heredado de la referencia
124	e-Remito Exportación	eRem_exp	Obligatorio
131	e-Ticket por Cuenta Ajena	eTck	Obligatorio
132	Nota de Crédito e-Ticket por Cuenta Ajena	eTck	Heredado de la referencia
133	Nota de Débito e-Ticket por Cuenta Ajena	eTck	Heredado de la referencia
141	e-Factura por Cuenta Ajena	eFact	Obligatorio
142	Nota de Crédito e-Factura por Cuenta Ajena	eFact	Heredado de la referencia
143	Nota de Débito e-Factura por Cuenta Ajena	eFact	Heredado de la referencia
151	e-Boleta de Entrada	eBoleta	Obligatorio
152	Nota de Crédito e-Boleta de Entrada	eBoleta	Heredado de la referencia
153	Nota de Débito e-Boleta de Entrada	eBoleta	Heredado de la referencia
181	e-Remito	eRem	Obligatorio
182	e-Resguardo	eResg	Obligatorio

Nodo XML: nombre del elemento interno del CFE en el formato DGI. Relevante sobre todo si emitís por POST /v1/cfe/emitir-xml (XML pre-armado). Receptor: si el comprobante exige identificar al adquirente. En las Notas, el receptor se hereda del comprobante referenciado.

Detalle por familia (explicación DGI)

A continuación, cada familia de CFE descrita como la plantea la normativa de DGI: qué operación documenta, cuándo corresponde emitirla, cómo se trata al receptor y qué campos especiales requiere.

e-Ticket — código base 101 · nodo XML eTck

Qué documenta. Documenta ventas de bienes y prestaciones de servicios a consumidores finales o a adquirentes que no precisan respaldar la operación con sus datos. Es el equivalente electrónico del ticket / boleta de contado del régimen tradicional.

Cuándo se usa. Operación de mostrador / punto de venta donde el comprador no requiere crédito fiscal (retail, gastronomía, comercio minorista).

Receptor. Opcional mientras el monto de la operación no supere el tope vigente en Unidades Indexadas (UI). Por debajo del tope la venta se informa a DGI de forma agregada en el reporte diario. Superado el tope, Host Factura exige identificar al receptor y reporta el comprobante de forma individual a DGI; omitir los datos del receptor en ese caso produce rechazo (falta el campo TipoDocRecep).

Particularidades.

• Admite forma de pago contado o crédito.
• El IVA se discrimina por tasa (básica 22%, mínima 10%, exento) pero no se imprime desglosado al consumidor final; se totaliza.

Código	Comprobante	Rol
101	e-Ticket	Comprobante base
102	Nota de Crédito e-Ticket	Nota de Crédito (reduce/anula el monto)
103	Nota de Débito e-Ticket	Nota de Débito (aumenta el monto)

Las Notas de esta familia referencian un 101 (e-Ticket) previo mediante referenciaId y heredan de él el receptor, la fecha de emisión y los datos fiscales.

e-Factura — código base 111 · nodo XML eFact

Qué documenta. Documenta ventas a otros contribuyentes (empresas con RUT) o a personas que necesitan respaldar la operación para deducir crédito fiscal (IVA) o como comprobante de gasto.

Cuándo se usa. Ventas B2B, ventas a empresas, o a personas físicas que solicitan factura con sus datos.

Receptor. Obligatorio siempre. Debe identificarse con tipo y número de documento (RUT, cédula de identidad, documento extranjero) junto con razón social y domicilio.

Particularidades.

• El IVA se discrimina por tasa y se imprime desglosado.
• Admite forma de pago contado o crédito.

Código	Comprobante	Rol
111	e-Factura	Comprobante base
112	Nota de Crédito e-Factura	Nota de Crédito (reduce/anula el monto)
113	Nota de Débito e-Factura	Nota de Débito (aumenta el monto)

Las Notas de esta familia referencian un 111 (e-Factura) previo mediante referenciaId y heredan de él el receptor, la fecha de emisión y los datos fiscales.

e-Factura de Exportación — código base 121 · nodo XML eFact_Exp

Qué documenta. Documenta exportaciones de bienes y servicios, es decir ventas cuyo destino es el exterior del país. El e-Remito de Exportación (124) ampara el traslado de la mercadería destinada a exportarse.

Cuándo se usa. Ventas al exterior, sujetas al régimen de exportación (IVA en suspenso / tasa 0).

Receptor. Obligatorio, típicamente un cliente del exterior. Se admite documento extranjero / pasaporte y país distinto de UY.

Particularidades.

• Requiere el bloque exportacionInfo: cláusula de venta (Incoterm: FOB, CIF, CFR, …), modalidad de venta y vía de transporte.
• Habitualmente se emite en moneda extranjera; en ese caso cambio es obligatorio.
• La operación es de exportación, por lo que no genera IVA al receptor (régimen de tasa 0).

Código	Comprobante	Rol
121	e-Factura Exportación	Comprobante base
124	e-Remito Exportación	Traslado asociado
122	Nota de Crédito e-Factura Exportación	Nota de Crédito (reduce/anula el monto)
123	Nota de Débito e-Factura Exportación	Nota de Débito (aumenta el monto)

Las Notas de esta familia referencian un 121 (e-Factura Exportación) previo mediante referenciaId y heredan de él el receptor, la fecha de emisión y los datos fiscales.

e-Ticket por Cuenta Ajena — código base 131 · nodo XML eTck

Qué documenta. Variante del e-Ticket para operaciones que un intermediario realiza por cuenta y orden de un tercero (mandante). El emisor documenta una venta a consumidor final que en realidad es del mandante.

Cuándo se usa. Consignaciones, comisionistas, plataformas que cobran en nombre de un vendedor a consumidor final.

Receptor. Mismas reglas que el e-Ticket (101): identificación del receptor según tope en UI.

Particularidades.

• Requiere identificar al mandante (por cuenta de quién se vende) en la zona de Complemento Fiscal del CFE.

Código	Comprobante	Rol
131	e-Ticket por Cuenta Ajena	Comprobante base
132	Nota de Crédito e-Ticket por Cuenta Ajena	Nota de Crédito (reduce/anula el monto)
133	Nota de Débito e-Ticket por Cuenta Ajena	Nota de Débito (aumenta el monto)

Las Notas de esta familia referencian un 131 (e-Ticket por Cuenta Ajena) previo mediante referenciaId y heredan de él el receptor, la fecha de emisión y los datos fiscales.

e-Factura por Cuenta Ajena — código base 141 · nodo XML eFact

Qué documenta. Variante de la e-Factura para ventas a contribuyentes realizadas por cuenta y orden de un tercero (mandante).

Cuándo se usa. Operaciones B2B canalizadas a través de un intermediario o mandatario.

Receptor. Obligatorio, igual que la e-Factura (111).

Particularidades.

• Requiere identificar al mandante en la zona de Complemento Fiscal del CFE.

Código	Comprobante	Rol
141	e-Factura por Cuenta Ajena	Comprobante base
142	Nota de Crédito e-Factura por Cuenta Ajena	Nota de Crédito (reduce/anula el monto)
143	Nota de Débito e-Factura por Cuenta Ajena	Nota de Débito (aumenta el monto)

Las Notas de esta familia referencian un 141 (e-Factura por Cuenta Ajena) previo mediante referenciaId y heredan de él el receptor, la fecha de emisión y los datos fiscales.

e-Boleta de Entrada — código base 151 · nodo XML eBoleta

Qué documenta. Documenta compras que un contribuyente realiza a sujetos no obligados a documentar (por ejemplo productores rurales o personas no registradas como contribuyentes). Lo emite el comprador para respaldar la entrada de los bienes a su empresa.

Cuándo se usa. Adquisición de bienes a proveedores que no emiten CFE; agro, recolección, compra a particulares.

Receptor. El “receptor” del documento es el vendedor/proveedor que entrega los bienes; debe identificárselo.

Particularidades.

• Invierte el rol habitual: lo emite quien compra, no quien vende.

Código	Comprobante	Rol
151	e-Boleta de Entrada	Comprobante base
152	Nota de Crédito e-Boleta de Entrada	Nota de Crédito (reduce/anula el monto)
153	Nota de Débito e-Boleta de Entrada	Nota de Débito (aumenta el monto)

Las Notas de esta familia referencian un 151 (e-Boleta de Entrada) previo mediante referenciaId y heredan de él el receptor, la fecha de emisión y los datos fiscales.

e-Remito — código base 181 · nodo XML eRem

Qué documenta. Ampara el traslado de mercadería sin que medie (todavía) una operación de venta documentada: movimientos entre depósitos o sucursales, envíos a consignación, retiros, etc.

Cuándo se usa. Transporte de bienes en la vía pública que no está respaldado por una factura.

Receptor. Obligatorio (destinatario del traslado).

Particularidades.

• Requiere el bloque remitoInfo: tipo de traslado (venta / traslado interno) y, si aplica, propiedad de la mercadería.
• No documenta una venta: no lleva totales de IVA a pagar ni forma de pago.
• No admite Notas de Crédito ni de Débito.

Código	Comprobante	Rol
181	e-Remito	Comprobante base

Esta familia no admite Notas de Crédito ni de Débito.

e-Resguardo — código base 182 · nodo XML eResg

Qué documenta. Documenta retenciones y percepciones de impuestos (IRPF, IRAE, IRNR, IVA) practicadas por un agente de retención/percepción designado por DGI.

Cuándo se usa. Cada vez que un agente de retención retiene/percibe un impuesto al realizar un pago o cobro.

Receptor. Obligatorio (el sujeto a quien se le practica la retención/percepción).

Particularidades.

• Cada línea lleva un código de retención válido (CodRet) con formato FFFF-LLL (4 dígitos de formulario + 3 de línea). Ver la sección de retenciones/percepciones.
• No lleva forma de pago ni IVA a pagar al estilo de una factura.
• No admite Notas de Crédito ni de Débito.

Código	Comprobante	Rol
182	e-Resguardo	Comprobante base

Esta familia no admite Notas de Crédito ni de Débito.

Notas de Crédito y Notas de Débito (concepto general)

Las Notas modifican el monto de un CFE ya emitido y aceptado; no se emiten “sueltas”.

• Nota de Crédito → reduce o anula el monto del comprobante original. Casos típicos: devolución de mercadería, error de facturación, descuento o bonificación posterior.
• Nota de Débito → aumenta el monto del comprobante original. Casos típicos: intereses por mora, cargos adicionales (flete, envasado), ajustes de precio detectados después.

Reglas que aplican a todas las Notas:

1. referenciaId obligatorio apuntando al UUID del CFE original que modifican.
2. El receptor, la fecha de emisión y los datos fiscales se heredan automáticamente del CFE referenciado — no hay que reenviarlos.
3. Correspondencia estricta de tipo: una Nota solo puede referenciar al comprobante de su propia familia. Una Nota de Crédito de e-Ticket (102) solo referencia un e-Ticket (101); una de e-Factura (112) solo referencia una e-Factura (111); y así sucesivamente.
4. Al emitir por XML (POST /v1/cfe/emitir-xml), el nodo Referencia.FechaCFEref debe ser exactamente la FchEmis del CFE original; si difiere, DGI rechaza con el código E12.

---

Códigos de retenciones y percepciones (e-Resguardo)

Para emitir un e-Resguardo (tipo 182), cada línea de retención debe llevar el campo CodRet con un código válido de la tabla DGI. El formato exigido es FFFF-LLL (4 dígitos de formulario + guion + 3 dígitos de línea), por ejemplo 2183-010.

Formularios disponibles

Formulario	Descripción	Códigos
1144	IRPF – Rentas del trabajo y AFAP	8
1145	IRPF – Rendimientos de capital y otras rentas	4
1146	IRPF / IRNR – Intereses y dividendos	76
1246	(consultar tabla DGI)	105
1700	(consultar tabla DGI)	3
1701	(consultar tabla DGI)	3
1845	(consultar tabla DGI)	5
1892	(consultar tabla DGI)	11
1901	(consultar tabla DGI)	1
2142	(consultar tabla DGI)	45
2180	(consultar tabla DGI)	2
2181	IVA – Régimen general / Resp. agente	21
2183	IVA – Retención exportadores e industria	66
2192	IVA – Régimen específico	11

Total: 361 códigos de retención/percepción en la tabla DGI vigente.

Reglas de validación

• El código debe existir exactamente en la tabla DGI vigente (la tabla se actualiza periódicamente).
• El formato debe ser FFFF-LLL o FFFF/LLL (DGI acepta ambos separadores).
• Si el código no es válido, DGI rechaza el CFE con código de error E05.

Cómo consultar la tabla completa

La lista completa de los códigos vigentes (auto-generada desde la tabla oficial DGI tabla_codigos_cfe) está disponible en la guía complementaria de la documentación. En el código fuente vive en src/modules/cfe/data/retenciones_percepciones_data.ts y se actualiza cuando DGI publica una nueva versión.

---

SDKs y ejemplos

Tenemos SDK oficial en JavaScript (sdk/js/). Si necesitás otro lenguaje, el OpenAPI spec se puede usar con openapi-generator para PHP, Python, .NET, Java, Go, etc.

Soporte

Reportá problemas con el requestId que devuelve la respuesta de error.

• Soporte Host Factura: https://hostfactura.com.uy/soporte
• License: Proprietary
• OpenAPI version: 3.0.3

Authentication

BearerAuth

Autenticación HTTP Bearer con la API_KEY de tu ApiAccess.

Header requerido: Authorization: Bearer <API_KEY>

La API_KEY es el token de acceso a la API. Se genera al crear un ApiAccess en tu cuenta de Host Factura, y se muestra una sola vez al momento de la creación o rotación.

Cómo obtenerla:

1. Ingresá al panel de Host Factura con tu usuario administrador.
2. En Configuración → API, creá un nuevo Access. Opcionalmente asocialo a una sucursal específica para que las emisiones queden atribuidas a esa sucursal sin necesidad de header.
3. Al crearlo, se muestra una sola vez la API_KEY. Copiala a tu vault (1Password, AWS Secrets Manager, Vault, etc.).
4. Si la perdés o sospechás filtración, rotala desde el panel — la API_KEY anterior se invalida en el acto.

Buenas prácticas:

• Nunca commitees la API_KEY en repositorios (ni siquiera privados).
• Usá una API_KEY distinta por entorno (producción, staging, sandbox).
• Restringí la API_KEY a una sucursal específica si tu integración solo opera contra una.
• Rotala periódicamente (cada 90 días es una buena cadencia).

Security scheme type: http

Bearer format: opaque