Lista los CFE recibidos de proveedores

GET

/v1/cfe/recibidos

Producción
Homologación / pruebas

Listado paginado de los CFE que la empresa recibió (intercambio por webservice, correo o importación), del más reciente al más antiguo según cuándo llegaron.

Disponible para toda empresa, aunque no emita comprobantes (por ejemplo, una institución que sólo recibe facturas de sus proveedores). Los recibidos son de la empresa, no de una sucursal: una credencial fijada a una sucursal ve todos.

Filtros

Todos opcionales y combinables (AND). Un parámetro desconocido es un 422.

rutEmisor — RUT del proveedor, exacto.
tipo, serie, numero — identificación del comprobante.
fechaEmisionDesde / fechaEmisionHasta — fecha de emisión del CFE (YYYY-MM-DD, inclusive).
recibidoDesde / recibidoHasta — fecha en que llegó a Host Factura (YYYY-MM-DD, inclusive, hora de Uruguay).
estado — estado frente a DGI: pendiente, aceptado, rechazado, observado (el mismo valor que data[].estado).
estadoDgi — el valor crudo P/A/R/O (el mismo de data[].estadoDgi y de los webhooks).
estadoComercial — tu aceptación comercial: pendiente, aceptado, rechazado.

Paginación

pagina (desde 1) y porPagina (por defecto 20, máximo 200). La metadata viaja en meta.paginacion.

El listado no trae el XML ni las líneas: xmlDisponible indica si hay XML guardado, y el detalle completo está en GET /v1/cfe/recibidos/{id}.

El id es el mismo cfeRecibidoId que llega en los webhooks cfe_recibido.creado y cfe_recibido.actualizado: con el webhook te enterás de que llegó un comprobante y con GET /v1/cfe/recibidos/{id} traés su detalle.

Alcance requerido: recibidos:leer. Si la credencial no lo tiene, la respuesta es 403 API_ALCANCE_INSUFICIENTE con la lista en error.requerido. Las credenciales creadas antes del modelo de alcances (alcances: null) conservan acceso total.

Autorizaciones

BearerAuth

Parámetros

Parámetros de query

pagina

Página, desde 1. Por defecto 1

integer

>= 1

Ejemplo

Página, desde 1. Por defecto 1

porPagina

Filas por página (máx. 200). Por defecto 20

integer

>= 1 <= 200

Ejemplo

Filas por página (máx. 200). Por defecto 20

rutEmisor

RUT del emisor (proveedor), exacto

string

Ejemplo

214567890018

RUT del emisor (proveedor), exacto

tipo

TipoCFE numérico (101, 111, 112, 181, …)

integer

nullable

Ejemplo

TipoCFE numérico (101, 111, 112, 181, …)

serie

Serie del CFE

string

Ejemplo

Serie del CFE

numero

Número del CFE

integer

Ejemplo

Número del CFE

fechaEmisionDesde

Fecha de emisión desde (YYYY-MM-DD, inclusive)

string

Ejemplo

2026-10-01

Fecha de emisión desde (YYYY-MM-DD, inclusive)

fechaEmisionHasta

Fecha de emisión hasta (YYYY-MM-DD, inclusive)

string

Ejemplo

2026-10-31

Fecha de emisión hasta (YYYY-MM-DD, inclusive)

recibidoDesde

Recibido desde (YYYY-MM-DD, inclusive)

string

Ejemplo

2026-10-01

Recibido desde (YYYY-MM-DD, inclusive)

recibidoHasta

Recibido hasta (YYYY-MM-DD, inclusive)

string

Ejemplo

2026-10-31

Recibido hasta (YYYY-MM-DD, inclusive)

estado

Estado unificado frente a DGI

string

Allowed values: pendiente aceptado rechazado observado

Estado unificado frente a DGI

estadoDgi

Estado DGI crudo: P (pendiente), A (aceptado), R (rechazado), O (observado)

string

Allowed values: P A R O

Estado DGI crudo: P (pendiente), A (aceptado), R (rechazado), O (observado)

estadoComercial

Aceptación comercial de la empresa receptora

string

Allowed values: pendiente aceptado rechazado

Aceptación comercial de la empresa receptora

orden

Orden por fecha de recepción. Por defecto desc

string

Allowed values: asc desc

Orden por fecha de recepción. Por defecto desc

Parámetros de header

x-cuenta-id

string format: uuid

Ejemplo

0199d1b0-0000-7000-8000-000000000000

Sólo para credenciales de cuenta proveedora (revendedor). UUID de la subcuenta de la cartera sobre la que se quiere operar: la cuenta efectiva del request pasa a ser esa.

Una credencial que no es de proveedor, o una subcuenta que no está en su cartera, recibe 403 API_CUENTA_FUERA_DE_CARTERA. Sin la cabecera, la cuenta es siempre la de la credencial.

Respuestas

200

CFE recibidos de la empresa

object

Ejemplos

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

401

No autenticado. La API_KEY no fue enviada, no es válida o la credencial está desactivada.

Códigos posibles: API_AUTH_HEADER_MISSING, API_AUTH_HEADER_INVALID, API_ACCESS_INVALID.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español. No parsearlo: puede cambiar

string

details

Any of:

object

requerido

Sólo en 403 API_ALCANCE_INSUFICIENTE: alcances que habilitan la operación

Array<string>

Allowed values: cfe:emitir cfe:leer recibidos:leer consultas clientes:leer clientes:escribir pagos:leer pagos:cobrar pagos:tarjetas pagos:suscripciones pagos:configurar webhooks:gestionar

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

Falta header Authorization

{
  "error": {
    "code": "API_AUTH_HEADER_MISSING",
    "message": "Se esperaba la cabecera Authorization con esquema Bearer"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

Secret key inválida o revocada

{
  "error": {
    "code": "API_ACCESS_INVALID",
    "message": "Acceso no autorizado"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

403

Acceso prohibido. La credencial es válida pero algo del contexto lo impide. Las cinco causas se corrigen de forma distinta y ninguna se arregla reintentando:

Code	Qué pasó	Cómo se corrige
`API_FEATURE_DISABLED`	La cuenta no tiene la API habilitada en su plan	Pedir la habilitación a soporte o al proveedor
`API_ALCANCE_INSUFICIENTE`	La credencial no tiene el alcance de la operación (va en `error.requerido`)	Editar la credencial en Integraciones → API
`API_ALCANCE_NO_DISPONIBLE`	La credencial tiene el alcance pero la cuenta no lo admite: sin cobros habilitados (`pagos:`), sin facturación (`cfe:`) o no es cuenta proveedora (`webhooks:gestionar`). Va en `error.details`	Pedir la habilitación a soporte o al proveedor
`API_ACCESS_BRANCH_MISMATCH`	`x-branch-id` distinto de la sucursal fijada en la credencial	Quitar la cabecera o usar otra credencial
`API_CUENTA_FUERA_DE_CARTERA`	`x-cuenta-id` apunta a una cuenta que no es de la cartera	Revisar el UUID de la subcuenta

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español. No parsearlo: puede cambiar

string

details

Any of:

object

requerido

Sólo en 403 API_ALCANCE_INSUFICIENTE: alcances que habilitan la operación

Array<string>

Allowed values: cfe:emitir cfe:leer recibidos:leer consultas clientes:leer clientes:escribir pagos:leer pagos:cobrar pagos:tarjetas pagos:suscripciones pagos:configurar webhooks:gestionar

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

Falta el 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"
}

La cuenta no admite el alcance

{
  "error": {
    "code": "API_ALCANCE_NO_DISPONIBLE",
    "message": "Disponible sólo para cuentas proveedoras. La credencial tiene el permiso, pero la cuenta no puede usarlo.",
    "details": {
      "alcances": [
        "webhooks:gestionar"
      ],
      "motivo": "SOLO_REVENDEDOR"
    }
  },
  "requestId": "3f6b1c2e-9a4d-4f80-bc11-7e2d5a8f0c31"
}

La cuenta no tiene la API habilitada

{
  "error": {
    "code": "API_FEATURE_DISABLED",
    "message": "El plan de esta cuenta no tiene habilitado el acceso a la API"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

Header x-branch-id distinto al fijo del ApiAccess

{
  "error": {
    "code": "API_ACCESS_BRANCH_MISMATCH",
    "message": "El ApiAccess está fijado a otra sucursal y no coincide con x-branch-id"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

x-cuenta-id fuera de la cartera

{
  "error": {
    "code": "API_CUENTA_FUERA_DE_CARTERA",
    "message": "La cuenta indicada en 'x-cuenta-id' no pertenece a la cartera de esta credencial"
  },
  "requestId": "3f6b1c2e-9a4d-4f80-bc11-7e2d5a8f0c31"
}

422

Query inválida (VALIDATION_ERROR): parámetro desconocido, fecha mal formada o rango invertido.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español. No parsearlo: puede cambiar

string

details

Any of:

object

requerido

Sólo en 403 API_ALCANCE_INSUFICIENTE: alcances que habilitan la operación

Array<string>

Allowed values: cfe:emitir cfe:leer recibidos:leer consultas clientes:leer clientes:escribir pagos:leer pagos:cobrar pagos:tarjetas pagos:suscripciones pagos:configurar webhooks:gestionar

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

Rango de fechas invertido

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "La petición no pasó la validación",
    "details": [
      {
        "campo": "fechaEmisionHasta",
        "codigo": "custom",
        "mensaje": "fechaEmisionHasta no puede ser anterior a fechaEmisionDesde"
      }
    ]
  },
  "requestId": "2f1e0d9c-8b7a-4f6e-9d5c-4b3a2f1e0d9c"
}

429

Rate limit excedido. Esperá los segundos del header Retry-After. La cuota va por credencial: 60 req/min en cuentas estándar, 600 en cuentas proveedor.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español. No parsearlo: puede cambiar

string

details

Any of:

object

requerido

Sólo en 403 API_ALCANCE_INSUFICIENTE: alcances que habilitan la operación

Array<string>

Allowed values: cfe:emitir cfe:leer recibidos:leer consultas clientes:leer clientes:escribir pagos:leer pagos:cobrar pagos:tarjetas pagos:suscripciones pagos:configurar webhooks:gestionar

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

Excediste el rate limit

{
  "error": {
    "code": "API_RATE_LIMITED",
    "message": "Se superó el límite de requests para esta API key"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

Headers

Retry-After

integer

Ejemplo

Segundos hasta que se libera la ventana de rate limit