Emisión de CFE

Host Factura ofrece dos formas de emitir un CFE. Elegí según tu situación:

	POST /v1/cfe/emitir (JSON)	POST /v1/cfe/emitir-xml (XML)
Para quién	Integraciones nuevas	Proveedores con armador de XML DGI propio
Qué enviás	JSON estructurado	XML del CFE en formato DGI nativo
Quién calcula totales / IVA	Host Factura	Tu sistema
Curva de aprendizaje	Baja	Alta (formato DGI)

En ambos casos Host Factura asigna CAE, serie y número, firma el XML con el certificado de la cuenta, arma y valida el sobre contra los XSD de DGI, y lo envía.

Opción A: payload JSON (recomendado)

Indicás el tipo de CFE (ver Tipos de CFE) y los datos de la operación; Host Factura arma el XML, calcula totales, IVA y redondeos. Hay un cuerpo de ejemplo para cada caso común (empresa con RUT, moneda extranjera, notas, cobranza, cuenta ajena) en Ejemplos.

Ítems

Cada elemento de items[] puede ser:

• De catálogo: { id, quantity }. Los datos del producto salen del catálogo de la cuenta.

• Ad-hoc: { name, quantity, price, billingIndex, description?, unit?, code? }. billingIndex es obligatorio e indica el tratamiento de IVA:

  billingIndex	Tratamiento de IVA
  1	Exento
  2	Tasa mínima (10%)
  3	Tasa básica (22%)
  4	Otra tasa
  6 / 7	No facturable (por ejemplo, las líneas de una cobranza)

Moneda extranjera

Cuando moneda != "UYU", cambio es obligatorio. Obtené el tipo de cambio vigente con GET /v1/cotizaciones (datos del BCU, con caché de 24 h).

Metadatos personalizados

El campo opcional metadata te permite adjuntar datos propios del negocio (no fiscales) a la emisión — número de transacción, método de pago, referencia externa, etc. Ver Metadatos personalizados para el detalle completo (definición de campos, validación y cómo consultarlos después). No disponible en la Opción B (XML pre-armado).

Notas de Crédito / Débito

Enviá el tipo correspondiente (102, 103, 112, 113, …) y referenciaId con el UUID del CFE original. No reenvíes el receptor ni la fecha: se heredan. Los items[] representan las líneas que se acreditan/debitan.

Opción B: XML pre-armado (formato DGI nativo)

Pensado para proveedores que ya operaban contra los servicios SOAP de DGI y no quieren reescribir su armador de XML. Enviás el XML del CFE sin CAEData, Signature, IdDoc.Serie ni IdDoc.Nro (esos los inyecta Host Factura; si los incluís, recibís 400 XML_EXTERNO_CAMPO_PROHIBIDO).

Responsabilidad del cliente

Por esta vía, tu sistema es responsable de calcular y cuadrar los montos (netos por tasa, IVA, total, redondeos). Host Factura no recalcula totales: si no cierran, DGI rechaza el CFE. Además, debés mantener tu armador al día con los formatos que DGI publica periódicamente.

El nombre del nodo interno debe corresponder al TipoCFE declarado (eTck, eFact, eFact_Exp, eRem, eResg, eBoleta). Para Notas, tu XML debe incluir el nodo Referencia (no se completa automáticamente por esta vía).

Pre-requisitos de la cuenta

Para que la emisión funcione, la cuenta debe tener:

• CVA (certificado digital) activo,
• CAE vigente para el tipo + serie + sucursal,
• datos básicos de empresa cargados.

Si falta algo, recibís un error específico (409 NO_CAE_VIGENTE, CAE_RANGE_EXHAUSTED, etc.).

Estados del CFE

La respuesta incluye data.estado:

Estado	Significado
aceptado	DGI aceptó el CFE.
pendiente	Aceptado, falta respuesta definitiva de DGI.
observado	DGI lo observó (revisar motivoRechazo).
rechazado	DGI lo rechazó (revisar motivoRechazo).

Ejemplos

Cuerpos de POST /v1/cfe/emitir para los casos más comunes, tomados de la Referencia de la API. Las líneas resaltadas son las que cambian respecto del e-Ticket básico. Para enviarlos, usá el mismo request del Inicio rápido cambiando solo el cuerpo.

e-Ticket a consumidor final

El caso típico de un punto de venta: venta de bajo monto sin datos del comprador. En el e-Ticket (101) el receptor es opcional mientras el monto neto no supere el tope en UI que fija DGI (del orden de 10.000 UI).

POST /v1/cfe/emitir

{
  "tipo": 101,
  "moneda": "UYU",
  "formaPago": 1,
  "items": [
    {
      "name": "Café americano",
      "quantity": 2,
      "price": 90,
      "billingIndex": 3
    },
    {
      "name": "Medialuna",
      "quantity": 1,
      "price": 60,
      "billingIndex": 3
    }
  ]
}

e-Factura a una empresa (RUT)

Venta a una empresa identificada por RUT (tipoDocumento: 2), a crédito (formaPago: 2). Mezcla un ítem de catálogo (solo id y quantity) con uno ad-hoc. compraId es el campo estándar de DGI para el número de orden de compra del receptor (hasta 50 caracteres) y adenda agrega texto libre a la representación impresa.

POST /v1/cfe/emitir

{
  "tipo": 111,
  "moneda": "UYU",
  "formaPago": 2,
  "cliente": {
    "tipoDocumento": 2,
    "documento": "219999830019",
    "razonSocial": "EMPRESA EJEMPLO S.A.",
    "direccion": "18 DE JULIO 1234",
    "ciudad": "MONTEVIDEO",
    "estado": "MONTEVIDEO",
    "pais": "UY",
    "email": "facturacion@empresa-ejemplo.com.uy"
  },
  "items": [
    {
      "id": "3f1a5c80-7b22-4e8d-9f1c-2b3a4c5d6e7f",
      "quantity": 3
    },
    {
      "name": "Servicio de consultoría — Septiembre",
      "quantity": 1,
      "price": 12500,
      "billingIndex": 3,
      "description": "Horas: 40 — Hora: $312.50"
    }
  ],
  "compraId": "OC-2026-00845",
  "adenda": "Forma de pago: transferencia BROU 001-1234567-89"
}

En moneda extranjera

Con cualquier moneda distinta de UYU (USD, ARS, BRL, EUR), cambio es obligatorio. Tomá el tipo de cambio vigente del BCU con GET /v1/cotizaciones.

POST /v1/cfe/emitir

{
  "tipo": 111,
  "moneda": "USD",
  "cambio": 39.85,
  "formaPago": 2,
  "cliente": {
    "tipoDocumento": 2,
    "documento": "219999830019",
    "razonSocial": "EXPORTADORA EJEMPLO S.A.",
    "pais": "UY"
  },
  "items": [
    {
      "name": "Producto X",
      "quantity": 10,
      "price": 100,
      "billingIndex": 3
    }
  ]
}

Nota de crédito

Reduce el monto de un CFE ya emitido: una devolución, un error de cobro o un descuento posterior. Es tipo 102 si el original es un e-Ticket y 112 si es una e-Factura. referenciaId lleva el UUID del CFE original; la fecha y el receptor se heredan, así que no se reenvían.

POST /v1/cfe/emitir

{
  "tipo": 102,
  "moneda": "UYU",
  "referenciaId": "8a7b6c5d-4e3f-2a1b-9c8d-7e6f5a4b3c2d",
  "items": [
    {
      "name": "Devolución por error de cobro",
      "quantity": 1,
      "price": 240,
      "billingIndex": 3
    }
  ]
}

Nota de débito

Aumenta el monto de un CFE ya emitido: intereses por mora, cargos adicionales o ajustes de precio. Es tipo 103 si el original es un e-Ticket y 113 si es una e-Factura, con el mismo referenciaId que la nota de crédito.

POST /v1/cfe/emitir

{
  "tipo": 113,
  "moneda": "UYU",
  "referenciaId": "8a7b6c5d-4e3f-2a1b-9c8d-7e6f5a4b3c2d",
  "items": [
    {
      "name": "Intereses por mora — atraso 45 días",
      "quantity": 1,
      "price": 1830,
      "billingIndex": 3,
      "description": "TNA 12% sobre saldo $15.250"
    }
  ]
}

Cobranza de una venta a crédito (e-Recibo)

Documenta el cobro de una factura emitida a crédito. Es un e-Ticket (101) o una e-Factura (111) con esCobranza: true, y todas las líneas van como no facturables (billingIndex 6 o 7): el IVA ya se generó en la factura original y la cobranza solo documenta el ingreso de dinero. referenciaId apunta a la factura cobrada; DGI rechaza la cobranza sin esa referencia (error E05). Admite cobros parciales: el monto cobrado es el de las líneas.

POST /v1/cfe/emitir

{
  "tipo": 111,
  "moneda": "UYU",
  "formaPago": 1,
  "esCobranza": true,
  "referenciaId": "8a7b6c5d-4e3f-2a1b-9c8d-7e6f5a4b3c2d",
  "cliente": {
    "tipoDocumento": 2,
    "documento": "219999830019",
    "razonSocial": "EMPRESA EJEMPLO S.A.",
    "pais": "UY"
  },
  "items": [
    {
      "name": "Cobranza Factura A-123",
      "quantity": 1,
      "price": 12200,
      "billingIndex": 6
    }
  ],
  "adenda": "Cancelación de Factura A-123 — Transferencia BROU 001-1234567-89"
}

Por cuenta ajena

Ventas que tu cuenta hace por cuenta y orden de un tercero: consignación, comisionista o una plataforma que factura en nombre de un vendedor. mandante identifica a ese tercero y viaja en la zona de Complemento Fiscal del CFE; el RUC emisor de esa zona es siempre el de tu cuenta. Ver Tipos de CFE.

Tipo	Comprobante	Receptor	mandante
131	e-Ticket por cuenta ajena	Obligatorio	Obligatorio
132 / 133	Nota de crédito / débito del 131	Heredado del original	Obligatorio
141	e-Factura por cuenta ajena	Obligatorio	Obligatorio
142 / 143	Nota de crédito / débito del 141	Heredado del original	Obligatorio

Reglas que valen para los seis:

• mandante lleva tipoDocumento (1 NIE, 2 RUC, 3 CI, 4 Otros, 5 Pasaporte, 6 DNI, 7 NIFE), pais (ISO de dos letras), documento (hasta 20 caracteres; se valida el dígito verificador de RUC y CI uruguayos) y razonSocial (hasta 150). Los cuatro son obligatorios.
• En las notas el mandante no se hereda: se envía de nuevo, junto con referenciaId.
• Enviar mandante en cualquier otro tipo de CFE devuelve 422.

e-Ticket por cuenta ajena (131)

Venta a consumidor final hecha en nombre del mandante. La referencia de la API marca el receptor como obligatorio en el 131, así que el ejemplo lo incluye (una persona con CI, tipoDocumento: 3).

POST /v1/cfe/emitir

{
  "tipo": 131,
  "moneda": "UYU",
  "formaPago": 1,
  "cliente": {
    "tipoDocumento": 3,
    "documento": "12345672",
    "razonSocial": "MARÍA RODRÍGUEZ",
    "pais": "UY"
  },
  "mandante": {
    "tipoDocumento": 2,
    "pais": "UY",
    "documento": "215521750017",
    "razonSocial": "PRODUCTOR EJEMPLO S.R.L."
  },
  "items": [
    {
      "name": "Artesanía en consignación",
      "quantity": 1,
      "price": 850,
      "billingIndex": 3
    }
  ]
}

Nota de crédito de e-Ticket por cuenta ajena (132)

Reduce un 131. referenciaId apunta al e-Ticket original y el receptor se hereda, pero el mandante se vuelve a enviar: es obligatorio en las notas de esta familia.

POST /v1/cfe/emitir

{
  "tipo": 132,
  "moneda": "UYU",
  "referenciaId": "4c3b2a19-8f7e-4d6c-9b5a-3e2d1c0b9a87",
  "mandante": {
    "tipoDocumento": 2,
    "pais": "UY",
    "documento": "215521750017",
    "razonSocial": "PRODUCTOR EJEMPLO S.R.L."
  },
  "items": [
    {
      "name": "Devolución de artesanía en consignación",
      "quantity": 1,
      "price": 850,
      "billingIndex": 3
    }
  ]
}

Nota de débito de e-Ticket por cuenta ajena (133)

Aumenta un 131, por ejemplo por un cargo que no se incluyó en la venta. Misma forma que la nota de crédito.

POST /v1/cfe/emitir

{
  "tipo": 133,
  "moneda": "UYU",
  "referenciaId": "4c3b2a19-8f7e-4d6c-9b5a-3e2d1c0b9a87",
  "mandante": {
    "tipoDocumento": 2,
    "pais": "UY",
    "documento": "215521750017",
    "razonSocial": "PRODUCTOR EJEMPLO S.R.L."
  },
  "items": [
    {
      "name": "Envío a domicilio no facturado",
      "quantity": 1,
      "price": 250,
      "billingIndex": 3
    }
  ]
}

e-Factura por cuenta ajena (141)

Venta a una empresa en nombre del mandante. El receptor es obligatorio, como en la e-Factura (111).

POST /v1/cfe/emitir

{
  "tipo": 141,
  "moneda": "UYU",
  "formaPago": 2,
  "cliente": {
    "tipoDocumento": 2,
    "documento": "219999830019",
    "razonSocial": "EMPRESA EJEMPLO S.A.",
    "direccion": "18 DE JULIO 1234",
    "ciudad": "MONTEVIDEO",
    "pais": "UY"
  },
  "mandante": {
    "tipoDocumento": 2,
    "pais": "UY",
    "documento": "215521750017",
    "razonSocial": "PRODUCTOR EJEMPLO S.R.L."
  },
  "items": [
    {
      "name": "Lote de mercadería en consignación",
      "quantity": 10,
      "price": 1500,
      "billingIndex": 3
    }
  ]
}

Nota de crédito de e-Factura por cuenta ajena (142)

Reduce un 141: por ejemplo, la devolución de parte del lote. Receptor heredado; mandante obligatorio.

POST /v1/cfe/emitir

{
  "tipo": 142,
  "moneda": "UYU",
  "referenciaId": "8a7b6c5d-4e3f-2a1b-9c8d-7e6f5a4b3c2d",
  "mandante": {
    "tipoDocumento": 2,
    "pais": "UY",
    "documento": "215521750017",
    "razonSocial": "PRODUCTOR EJEMPLO S.R.L."
  },
  "items": [
    {
      "name": "Devolución parcial del lote en consignación",
      "quantity": 2,
      "price": 1500,
      "billingIndex": 3
    }
  ]
}

Nota de débito de e-Factura por cuenta ajena (143)

Aumenta un 141, por ejemplo por un flete que no se facturó en la venta original.

POST /v1/cfe/emitir

{
  "tipo": 143,
  "moneda": "UYU",
  "referenciaId": "8a7b6c5d-4e3f-2a1b-9c8d-7e6f5a4b3c2d",
  "mandante": {
    "tipoDocumento": 2,
    "pais": "UY",
    "documento": "215521750017",
    "razonSocial": "PRODUCTOR EJEMPLO S.R.L."
  },
  "items": [
    {
      "name": "Flete no facturado en la venta original",
      "quantity": 1,
      "price": 900,
      "billingIndex": 3
    }
  ]
}

Con metadatos personalizados

Adjunta datos propios del negocio, no fiscales, al CFE. Las claves tienen que existir como campos personalizados de la cuenta (Configuración → Campos personalizados en el panel); una clave desconocida o un valor fuera de tipo devuelve 422 METADATA_INVALIDA. Detalle en Metadatos personalizados.

POST /v1/cfe/emitir

{
  "tipo": 101,
  "moneda": "UYU",
  "formaPago": 1,
  "items": [
    {
      "name": "Cuota mensual — Plan Premium",
      "quantity": 1,
      "price": 1490,
      "billingIndex": 3
    }
  ],
  "metadata": {
    "numero_transaccion": "TXN-8827461",
    "metodo_pago": "tarjeta",
    "referencia_externa": "sub_9F2K1"
  }
}

Respuesta de una emisión

La respuesta trae el CFE completo. Estos son los campos que casi siempre vas a leer (resumida; la lista completa está en la referencia):

200 OK

{
  "data": {
    "id": "8a7b6c5d-4e3f-2a1b-9c8d-7e6f5a4b3c2d",
    "tipo": 111,
    "tipoDescripcion": "e-Factura",
    "serie": "A",
    "numero": 1234,
    "moneda": "UYU",
    "subtotal": 12500,
    "iva": 2750,
    "total": 15250,
    "estado": "aceptado",
    "estadoDgi": "A",
    "fechaEstadoDgi": "2026-05-17T13:42:11.000Z",
    "motivoRechazo": null
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

Guardá data.id: es el que se usa como referenciaId en notas y cobranzas, y para pedir el PDF.

Errores frecuentes

Código	Status	Qué pasó
NO_CAE_VIGENTE	409	No hay CAE activo para ese tipo de CFE
CAE_RANGE_EXHAUSTED	409	Se agotó el rango de numeración del CAE
CERTIFICADO_NO_VIGENTE	409	La empresa no tiene un certificado vigente
METADATA_INVALIDA	422	Una clave de metadata no existe o su valor no cumple el tipo

Los 409 de certificado o CAE no consumen numeración: se corrige la configuración de la empresa y se reintenta. Todos los errores tienen la misma forma:

409 Conflict

{
  "error": {
    "code": "NO_CAE_VIGENTE",
    "message": "No hay CAE vigente para eTck"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

Esquemas completos, parámetros y ejemplos de cada endpoint: Referencia OpenAPI.