CFE recibidos

Además de emitir, Host Factura recibe los comprobantes que te mandan tus proveedores. Con la API podés leerlos desde tu sistema: los datos de cada comprobante, su PDF y el XML firmado por quien lo emitió.

No hace falta emitir para usarla. Está pensada también para quien sólo recibe: por ejemplo, una institución que recibe las facturas de sus proveedores y quiere cargarlas en su sistema contable, guardar el XML y tener el PDF a mano.

El permiso recibidos:leer

Todas las operaciones de esta guía exigen el alcance recibidos:leer en la credencial. Es un permiso propio: cfe:leer (que lee los comprobantes que emitís) no alcanza.

• No viene incluido por defecto. Una credencial nueva nace con el preset Solo facturación (cfe:emitir, cfe:leer, consultas), que no lo trae.
• Para habilitarlo, en el panel entrá a Integraciones API → Credenciales, editá la credencial (o creá una nueva) y marcá Leer comprobantes recibidos.
• Está disponible para toda empresa que tenga la API habilitada, aunque no emita comprobantes.

Ver Autenticación y contexto para el modelo completo de alcances.

De dónde salen los comprobantes recibidos

La API muestra los comprobantes que llegaron a Host Factura:

1. Por intercambio electrónico: el emisor le manda el comprobante a tu empresa (por webservice o por correo) y Host Factura lo registra automáticamente. Es el caso normal.
2. Por importación desde el panel: en Comprobantes → Importar recibidos podés cargar el XML que te mandó el proveedor por otra vía.

El XML firmado existe sólo si llegó de una de esas dos formas. Cada comprobante del listado trae xmlDisponible: si es false, el PDF, los datos de impresión y el XML responden 404 CFE_RECIBIDO_SIN_XML.

Nota

Hoy la API no le pide a DGI comprobantes que no hayan llegado a Host Factura. Si un proveedor te emitió un comprobante pero nunca te lo mandó, pedíselo e importalo desde el panel.

Las operaciones

Operación	Devuelve
GET /api/v1/cfe/recibidos	Listado paginado y filtrable
GET /api/v1/cfe/recibidos/{id}	Detalle: emisor, receptor, totales, líneas, referencias, CAE, código de seguridad
GET /api/v1/cfe/recibidos/{id}/pdf	PDF (A4 o ticket)
GET /api/v1/cfe/recibidos/{id}/representacion-impresa	Los datos con los que se arma el PDF, en JSON
GET /api/v1/cfe/recibidos/{id}/xml	El XML firmado por el emisor

Los ejemplos usan el entorno de homologación (https://testing.hostfactura.com.uy/api); en producción es https://hostfactura.com.uy/api. Los recibidos son de la empresa, no de una sucursal: una credencial fijada a una sucursal los ve todos.

Listar

curl "https://testing.hostfactura.com.uy/api/v1/cfe/recibidos?fechaEmisionDesde=2026-10-01&fechaEmisionHasta=2026-10-31&porPagina=50" \
  -H "Authorization: Bearer $API_KEY"

{
  "data": [
    {
      "id": "3c1e9f62-8a4b-4d7e-b0c2-5f6a7b8c9d0e",
      "tipo": 111,
      "tipoDescripcion": "e-Factura",
      "serie": "A",
      "numero": 4521,
      "rutEmisor": "214567890018",
      "razonSocialEmisor": "Proveedora del Sur S.A.",
      "fechaEmision": "2026-10-01",
      "moneda": "UYU",
      "subtotal": 10000,
      "iva": 2200,
      "total": 12200,
      "estado": "aceptado",
      "estadoDgi": "A",
      "estadoComercial": "pendiente",
      "anulado": false,
      "recibidoEn": "2026-10-01T14:32:10.000Z",
      "xmlDisponible": true
    }
  ],
  "meta": {
    "paginacion": { "pagina": 1, "porPagina": 50, "totalFilas": 1, "totalPaginas": 1 }
  }
}

El ejemplo está recortado; la Referencia de la API tiene todos los campos.

Los filtros son opcionales y se combinan entre sí:

Filtro	Descripción
rutEmisor	RUT del proveedor, exacto
tipo, serie, numero	Identificación del comprobante (tipo numérico: 101, 111, 112…)
fechaEmisionDesde, fechaEmisionHasta	Fecha de emisión del comprobante (YYYY-MM-DD, inclusive)
recibidoDesde, recibidoHasta	Fecha en que llegó a Host Factura (YYYY-MM-DD, inclusive, hora de Uruguay)
estado	Estado ante DGI: pendiente, aceptado, rechazado, observado
estadoDgi	El mismo estado en su valor corto: P, A, R, O
estadoComercial	Tu aceptación comercial: pendiente, aceptado, rechazado
pagina, porPagina	Paginación. porPagina va de 1 a 200 (por defecto 20)
orden	desc (por defecto, lo último que llegó primero) o asc

Un parámetro que no está en la lista es un 422: así un filtro mal escrito no te devuelve el listado entero sin filtrar.

Detalle

curl "https://testing.hostfactura.com.uy/api/v1/cfe/recibidos/$CFE_ID" \
  -H "Authorization: Bearer $API_KEY"

Trae lo del listado más el emisor, el receptor, los totales desglosados por tasa de IVA, las líneas (detalle), las referencias (en notas de crédito y débito), el CAE, la adenda y el codigoSeguridad. Los nombres de los campos son propios y estables; si necesitás procesar el comprobante (importes, impuestos, líneas), usá esta operación.

PDF

# A4 (por defecto)
curl "https://testing.hostfactura.com.uy/api/v1/cfe/recibidos/$CFE_ID/pdf" \
  -H "Authorization: Bearer $API_KEY" -o factura.pdf

# Rollo térmico de ~80 mm
curl "https://testing.hostfactura.com.uy/api/v1/cfe/recibidos/$CFE_ID/pdf?formato=ticket" \
  -H "Authorization: Bearer $API_KEY" -o factura-ticket.pdf

Responde el PDF directamente (application/pdf), sin el envoltorio JSON. El nombre sugerido es <rutEmisor>-<serie>-<numero>.pdf, con el RUT del proveedor adelante para que no se confunda con tus propios comprobantes de igual serie y número.

El PDF lo arma Host Factura a partir del XML del emisor, con el QR de DGI y el código de seguridad del emisor. No se le agrega nada de tu empresa (ni logo, ni leyendas, ni datos de contacto): es el comprobante de tu proveedor.

Datos de la representación impresa

curl "https://testing.hostfactura.com.uy/api/v1/cfe/recibidos/$CFE_ID/representacion-impresa" \
  -H "Authorization: Bearer $API_KEY"

Devuelve, dentro de data, los datos con los que se arma el PDF (Emisor, Receptor, IdDoc, Totales, Detalle, CaeData, Referencias, Adenda, el QR como imagen y el código de seguridad en Parametros). Sirve si querés imprimir con tu propia plantilla.

Precaución

Esta estructura sigue al generador de PDF y no es un contrato estable campo a campo: puede cambiar cuando cambian las reglas de impresión de DGI. Leé los campos que necesitás y tolerá los que aparezcan. Para procesar el comprobante, usá el detalle.

XML firmado

curl "https://testing.hostfactura.com.uy/api/v1/cfe/recibidos/$CFE_ID/xml" \
  -H "Authorization: Bearer $API_KEY" -o comprobante.xml

Devuelve el comprobante firmado por el emisor, tal como llegó por intercambio (o como lo importaste), sin reformatear: application/xml; charset=utf-8, como adjunto <rutEmisor>-<serie>-<numero>.xml. Como no se toca, la firma digital del emisor se puede verificar.

Es la forma de obtener el XML de un comprobante recibido: DGI no se lo entrega al receptor por otra vía.

Encontrar un comprobante a partir del QR de DGI

El QR impreso en todo comprobante electrónico es una URL de consulta de DGI con este formato:

https://www.efactura.dgi.gub.uy/consultaQR/cfe?{rutEmisor},{tipo},{serie},{numero},{montoTotal},{fechaFirma},{hash}

Posición	Dato	Ejemplo
1	RUT del emisor	214567890018
2	Tipo de CFE	111
3	Serie	A
4	Número	4521
5	Monto total	12200.00
6	Fecha de firma (DD/MM/YYYY)	01/10/2026
7	Hash de la firma (codificado para URL)	aB3dE9fG...%3D

Para encontrarlo en Host Factura:

1. Tomá lo que va después del ? y separalo por comas.

2. Buscá con los cuatro primeros datos como filtros del listado:

   curl "https://testing.hostfactura.com.uy/api/v1/cfe/recibidos?rutEmisor=214567890018&tipo=111&serie=A&numero=4521" \
     -H "Authorization: Bearer $API_KEY"

3. Comprobá que es el mismo comprobante:

   • el total de la respuesta tiene que coincidir con el monto del QR (comparalos como números);
   • el codigoSeguridad del detalle tiene que ser igual a los 6 primeros caracteres del hash, después de decodificarlo de la URL.

No uses la fecha del QR para filtrar: es la fecha de firma, que puede no coincidir con la fecha de emisión (fechaEmision).

Si el listado viene vacío, el comprobante no llegó a Host Factura: ver De dónde salen los comprobantes recibidos.

Con webhooks

En vez de consultar el listado cada tanto, podés suscribirte a los webhooks cfe_recibido.creado (llegó un comprobante) y cfe_recibido.actualizado (cambió su estado ante DGI o tu aceptación comercial). El cfeRecibidoId del evento es el {id} de estas operaciones:

curl "https://testing.hostfactura.com.uy/api/v1/cfe/recibidos/$CFE_RECIBIDO_ID/xml" \
  -H "Authorization: Bearer $API_KEY" -o comprobante.xml

Errores

Estado	Código	Qué pasó
403	API_ALCANCE_INSUFICIENTE	La credencial no tiene recibidos:leer (va en error.requerido). Editá la credencial; no reintentes
403	API_FEATURE_DISABLED	La empresa no tiene la API habilitada
404	CFE_RECIBIDO_NO_ENCONTRADO	El comprobante no existe o es de otra empresa (las dos situaciones responden igual)
404	CFE_RECIBIDO_SIN_XML	El comprobante existe pero no tiene el XML guardado (xmlDisponible: false): no hay PDF, datos de impresión ni XML
422	VALIDATION_ERROR	El id no es un UUID, un filtro es inválido o desconocido, o formato no es a4 ni ticket. El detalle va en error.details

Qué vale legalmente

Según la normativa de DGI sobre documentación electrónica:

• La representación impresa (el PDF) se puede imprimir tantas veces como haga falta. No es un original único: su autenticidad se verifica con el QR y el código de seguridad, consultando a DGI.
• Si tu empresa es receptora electrónica, el documento con validez es el CFE en formato XML firmado por el emisor, no su representación impresa. Por eso conviene que guardes el XML de cada comprobante que recibís.

Esto es una guía práctica, no asesoramiento legal: ante una duda concreta, consultá con tu contador o con DGI.