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-cuenta-id: <uuid>	opcional	Sólo credenciales de revendedor: operar sobre una subcuenta de la cartera
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
Idempotency-Key: <clave>	opcional	En POST /v1/cfe/emitir, POST /v1/cfe/emitir-xml y los POST de /v1/pagos (obligatoria en /v1/pagos/cobrar)
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	La cuenta no tiene la API habilitada en su plan
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
403	API_ALCANCE_INSUFICIENTE	La credencial no tiene el alcance de la operación. Ver Alcances
403	API_CUENTA_FUERA_DE_CARTERA	x-cuenta-id apunta a una cuenta que no es de la cartera
429	API_RATE_LIMITED	Excediste el rate limit. Esperá según Retry-After

Ninguno de los 403 se arregla reintentando: todos exigen cambiar la credencial, el header o la habilitación comercial de la cuenta.

---

Alcances de la credencial

Cada ApiAccess lleva una lista de alcances (ApiAccess.alcances) y cada operación exige uno o varios. La semántica es OR: alcanza con tener alguno de los que la ruta declara en su extensión x-alcance.

Alcance	Etiqueta	Qué habilita
cfe:emitir	Emitir comprobantes	Emitir y validar CFE contra DGI, mandar la representación impresa por correo y emitir el comprobante de un cobro (al cobrar o después). Consume numeración: un CFE quema su número aunque después se anule.
cfe:leer	Leer comprobantes	Listar los CFE emitidos, consultar su estado en DGI y descargar el PDF. No emite nada.
recibidos:leer	Leer comprobantes recibidos	Listar y consultar los CFE que la empresa RECIBIÓ de sus proveedores (por intercambio, correo o importación), con su estado en DGI y su estado comercial, y descargar su PDF y su XML firmado. Sólo lectura: no acepta ni rechaza nada. Disponible aunque la empresa no emita comprobantes.
consultas	Consultas públicas	Consultar un RUT en DGI, buscar en el padrón de emisores electrónicos, leer las cotizaciones del BCU y el echo de diagnóstico. No toca datos de la empresa.
clientes:leer	Ver clientes	Listar y buscar los clientes de la empresa y consultar uno por su id. Sólo lectura.
clientes:escribir	Crear y actualizar clientes	Dar de alta un cliente o actualizar sus datos (upsert por tu referencia o por su documento). Es lo que da el id que piden las tarjetas, los cobros y las suscripciones.
pagos:leer	Ver cobros	Listar y consultar links de cobro y pagos, y descargar el comprobante de pago no fiscal. Sólo lectura.
pagos:cobrar	Cobrar	Crear links de cobro, mandarlos por correo, cobrar con una tarjeta ya registrada y anular un cobro. Mueve plata real. Emitir el comprobante del cobro exige además cfe:emitir.
pagos:tarjetas	Tarjetas del cliente	Iniciar el alta de una tarjeta, listarlas y darlas de baja. Nunca expone PAN ni CVV.
pagos:suscripciones	Planes y suscripciones	Crear planes, invitar clientes a contratarlos, y pausar, reanudar, cancelar o cambiarle el precio a una suscripción. Una suscripción activa cobra sola.
pagos:configurar	Configurar pagos	Leer y escribir las preferencias de cobro de la empresa: medios habilitados, política fiscal, aviso al comprador y el interruptor que apaga los cobros. No expone credenciales.
webhooks:gestionar	Gestionar webhooks	Registrar, listar, borrar y probar los endpoints a los que Host Factura le avisa de los eventos de la cuenta. El secreto de firma se muestra una sola vez al crear.

La regla del null

Una credencial con alcances: null es anterior al modelo de alcances y tiene acceso total. No es lo mismo que [], que es una credencial sin ningún permiso. La columna se agregó con DEFAULT NULL y sin backfill para no apagar ninguna integración viva, así que la restricción es opt-in: hay que editar la credencial en Integraciones → API para acotarla. El panel lo muestra como “acceso total (credencial anterior)”.

Al crear una credencial sin mandar el campo, nace con el preset Solo facturación (cfe:emitir, cfe:leer, consultas). Al actualizar, omitir el campo conserva lo que tenía.

Qué devuelve un 403 por alcance

{
  "error": {
    "code": "API_ALCANCE_INSUFICIENTE",
    "message": "La credencial de API no tiene ninguno de los alcances necesarios para esta operación (pagos:cobrar)",
    "requerido": ["pagos:cobrar"]
  },
  "requestId": "3f6b1c2e-9a4d-4f80-bc11-7e2d5a8f0c31"
}

requerido va dentro de error, al lado de code y message — no en error.details. Es la única excepción del wrapper y está acotada a este error.

---

Revendedores: la cabecera x-cuenta-id

Una credencial de una cuenta proveedora (revendedor, proveedor de facturación electrónica) puede operar sobre cualquier subcuenta de su cartera mandando:

x-cuenta-id: <uuid de la subcuenta>

La cuenta efectiva del request pasa a ser esa: emite con sus CAE, cobra con su configuración y queda registrada en su log. Sin la cabecera, la cuenta es la de la credencial.

• Una credencial que no es de proveedor, o una subcuenta que no está en la cartera, recibe 403 API_CUENTA_FUERA_DE_CARTERA.
• La credencial del revendedor debe ser de cuenta (sin sucursal fijada) para poder delegar.
• Es la única forma de cambiar de cuenta: no hay ningún parámetro ni campo de cuerpo que la elija. Si integrás empresas que no son de tu cartera, usá una API_KEY por empresa.
• El identificador de cada subcuenta está en el panel: Cartera de clientes → empresa → Resumen → Identificador para integraciones.
• Para que una integración opere sólo sobre una empresa, creale la credencial desde Cartera de clientes → empresa → API: esa credencial pertenece a la empresa y un x-cuenta-id a otra cuenta recibe 403 API_CUENTA_FUERA_DE_CARTERA.
• Auditoría: cada request delegado queda en el Registro de API de las dos cuentas — el revendedor lo ve con la empresa operada (y puede filtrar por ella), y la subcuenta lo ve marcado como hecho desde la cartera del revendedor. Se registra si cualquiera de las dos cuentas tiene la auditoría encendida.

---

Idempotencia

Todos los POST de /v1/pagos aceptan la cabecera Idempotency-Key con el mismo contrato. Es opcional en todos salvo POST /v1/pagos/cobrar, que la exige.

Situación	Respuesta
Sin cabecera	La operación se ejecuta normalmente (cada llamada es nueva)
Misma clave + mismo cuerpo	Se replica la respuesta original con meta.reusada: true, sin re-ejecutar
Misma clave + otro cuerpo, u otro endpoint	409 PAGOS_IDEMPOTENCY_KEY_CONFLICTO
Misma clave con la operación en curso	409 PAGOS_IDEMPOTENCY_EN_CURSO

• Forma de la clave: 8 a 128 caracteres de A-Za-z0-9._:~-.
• Ventana: 24 horas. Pasado ese plazo la misma clave es una operación nueva.
• Sólo se cachean las respuestas 2xx. Un 4xx o 5xx libera la clave, así que podés corregir el cuerpo y reintentar con la MISMA clave sin perder la protección.
• La huella es método + ruta + cuerpo canónico (claves ordenadas; los arrays conservan su orden, que es semántico).

⚠️ Nunca reintentes un cobro con una clave nueva. Una clave al azar simula idempotencia mientras cada reintento es un cobro real y distinto. Si el cobro quedó en en_verificacion, reintentá con la misma clave o esperá el evento de conciliación.

En la emisión de CFE

POST /v1/cfe/emitir y POST /v1/cfe/emitir-xml aceptan la misma cabecera, con dos diferencias que existen porque un comprobante emitido en DGI no se puede deshacer:

Situación	Respuesta
Misma clave, emisión terminada	Se devuelve el mismo CFE con meta.reusada: true
Misma clave, emisión en curso	409 CFE_IDEMPOTENCY_EN_CURSO — reintentá con la misma clave
El envío a DGI no se confirmó (timeout o corte)	409 CFE_EMISION_INCIERTA — no reintentes con otra clave
Misma clave + otro cuerpo, u otro endpoint	409 CFE_IDEMPOTENCY_KEY_CONFLICTO
Clave con formato inválido	400 CFE_IDEMPOTENCY_KEY_INVALIDA (no se ignora)
No se pudo registrar la clave	503 CFE_IDEMPOTENCIA_NO_DISPONIBLE — el comprobante no se emitió

• Un error antes de llegar a DGI (validación, CAE, sucursal) o un rechazo explícito de DGI libera la clave: corregí y reintentá con la misma.
• Si cortás la conexión mientras DGI procesa, la emisión sigue y la clave queda tomada: el reintento con la misma clave recibe el CFE cuando termina.
• Una emisión incierta mantiene la clave 7 días.

---

Monedas de los cobros

los cobros se procesan sólo en UYU y USD. Cualquier otro ISO-4217 se rechaza con 422 PAGOS_MONEDA_NO_SOPORTADA, que devuelve la lista admitida en error.details.monedasAdmitidas. (La emisión de CFE sí admite el resto de las monedas de DGI: el límite es del cobro, no del comprobante.)

---

Habilitaciones por cuenta (gates)

Dos interruptores comerciales, que administración enciende y la API no puede cambiar:

Gate	Qué corta	Error
pagosEnabled	Todo /v1/pagos/**	403 PAGOS_NO_HABILITADO
facturacionEnabled	La emisión de CFE (canal web y jobs fiscales)	403 FACTURACION_NO_HABILITADA

• Con pagosEnabled: false el módulo de cobros no existe para esa cuenta: ni los links, ni el cobro con tarjeta. Es una habilitación comercial, no un permiso de usuario. Si el flag no se puede leer, la respuesta es 503 PAGOS_ESTADO_INDETERMINADO: un gate que falla, cierra.
• Con facturacionEnabled: false la cuenta puede cobrar pero no emitir: la única política fiscal posible es solo_registrar, y el comprobante que se le entrega al comprador es el comprobante de pago NO fiscal (GET /v1/pagos/{id}/comprobante.pdf). Cualquier otra política se rechaza con 409 PAGOS_POLITICA_REQUIERE_FACTURACION.
• Los avisos entrantes de la red de pagos y el retorno del navegador no pasan por el gate: un 403 ahí sería perder el aviso de un cobro que ya ocurrió.

---

Webhooks salientes

Host Factura le hace POST a tu servidor cuando algo pasa en la cuenta. Las suscripciones se gestionan por /v1/webhooks (alcance webhooks:gestionar) y el catálogo completo de eventos, con el payload de cada uno, está en la extensión x-webhooks de este spec y en la guía de webhooks.

Evento	Qué significa
cfe.emitido	CFE emitido
cfe.actualizado	Cambió el estado de un CFE en DGI
cfe_recibido.creado	Llegó un CFE de otro emisor
cfe_recibido.actualizado	Cambió un CFE recibido
reporte_diario.aceptado	Reporte diario aceptado por DGI
reporte_diario.rechazado	Reporte diario RECHAZADO por DGI
reporte_diario.error	El reporte diario falló antes de llegar a DGI
cae.por_vencer	Un CAE está por vencer
cae.por_agotarse	Un CAE está por agotar su numeración
certificado.por_vencer	El certificado digital está por vencer
recurrente.emitido	Se emitió una factura recurrente
pago.confirmado	El cobro se confirmó: la plata entró
pago.fallido	El cobro fue rechazado de forma definitiva
pago.anulado	El cobro se anuló (total o parcialmente)
pago.facturado	Se emitió el comprobante fiscal del cobro
pago.pendiente_facturacion	Plata cobrada SIN comprobante
pago.en_verificacion	Estado AMBIGUO del cobro: puede estar cobrado
link.anulado	El link de cobro se anuló antes de pagarse
link.expirado	El link de cobro venció sin pagarse
suscripcion.cobro_exitoso	Se cobró un período de la suscripción
suscripcion.cobro_fallido	Declinó el cobro de un período
suscripcion.cancelada	Se dio de baja la suscripción
suscripcion.pausada	La suscripción se pausó
suscripcion.reanudada	La suscripción volvió a cobrar
tarjeta.enrolada	Se enroló una tarjeta del cliente
tarjeta.baja	Se dio de baja una tarjeta

Envelope: { id, tipo, creadoEn, cuentaId, sucursalId, datos }. Firma: X-HostFactura-Signature: t=<epoch>,v1=<hmac_sha256 de "<t>.<cuerpo raw>">. Deduplicá por X-HostFactura-Event-Id, que es estable entre reintentos. Backoff: 5 s, 30 s, 5 min, 30 min, 2 h, 12 h; agotados los 6 intentos la entrega queda DEAD.

---

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 Venta por Cuenta Ajena	eTck	Obligatorio
132	Nota de Crédito de e-Ticket Venta por Cuenta Ajena	eTck	Heredado de la referencia
133	Nota de Débito de e-Ticket Venta por Cuenta Ajena	eTck	Heredado de la referencia
141	e-Factura Venta por Cuenta Ajena	eFact	Obligatorio
142	Nota de Crédito de e-Factura Venta por Cuenta Ajena	eFact	Heredado de la referencia
143	Nota de Débito de e-Factura Venta 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 Venta 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: enviá el objeto mandante (tipoDocumento, pais, documento, razonSocial). Es obligatorio también en sus Notas (132/133).

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

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

e-Factura Venta 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: enviá el objeto mandante (tipoDocumento, pais, documento, razonSocial). Es obligatorio también en sus Notas (142/143).

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

Las Notas de esta familia referencian un 141 (e-Factura Venta 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.
• monto (B-C22 MntSujetoaRet, la base imponible) debe ser mayor a 0.
• infoAdicional (B-C22.1 InfoAdicionalRet, hasta 150 caracteres) es la leyenda normativa de la línea. Si se envía, la representación impresa la imprime: DGI lo exige.

Formulario 2181 = crédito fiscal (no retención)

Los códigos cuyo formulario es 2181 (2181-xxx) NO son retenciones/percepciones sino créditos fiscales. Van igual en la tabla retenciones del request y en el RetencPercep del XML, pero su importe se agrega a un total DISTINTO:

Códigos	Total del CFE	Campo del request
2181-xxx	A-C125.1 MntTotCredFisc	mntTotCredFisc (derivado, no se envía)
todos los demás	A-C125 MntTotRetenido	mntTotRetenido

Por eso mntTotRetenido, cuando se envía explícitamente, debe ser igual a la suma de los importes de los códigos que no son del 2181; enviar la suma de TODOS los códigos devuelve 422. Un e-Resguardo que solo documenta créditos fiscales lleva mntTotRetenido: 0 (el XSD exige el elemento igual, con valor 0.00). El total que devuelve la API para un e-Resguardo es A-C125 MntTotRetenido — el mismo valor que va en el QR del comprobante.

Multi-línea y resguardo de ajuste

lineasResguardo (excluyente con retenciones) permite emitir un e-Resguardo con VARIAS líneas de detalle. Una línea con ajuste: true se emite con B-C4 IndFact=9 y sus importes restan del agregado por código (A-C128); exige referenciaId apuntando al e-Resguardo que se ajusta.

Restricciones propias del 182

• No admite formaPago (A-C11) ni compraId: el XSD del e-Resguardo no los declara.
• No admite emisión recurrente.

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