Descarga el PDF de un CFE recibido

GET

/v1/cfe/recibidos/{id}/pdf

Producción
Homologación / pruebas

Devuelve la representación impresa en PDF del CFE recibido, generada por Host Factura a partir del XML firmado por el 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 del proveedor.

Formato

?formato=a4 (por defecto) — hoja A4.
?formato=ticket — rollo térmico ~80mm.
Content-Type: application/pdf (binario, sin el envoltorio JSON).
Content-Disposition: inline; filename="<rutEmisor>-<serie>-<numero>.pdf". El RUT del emisor va adelante para que no choque con tus propios comprobantes de igual serie y número.

Necesita el XML del comprobante: si no está guardado responde 404 CFE_RECIBIDO_SIN_XML.

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.

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 path

required

UUID del CFE recibido (el cfeRecibidoId de los webhooks cfe_recibido.*)

string format: uuid

UUID del CFE recibido (el cfeRecibidoId de los webhooks cfe_recibido.*)

Parámetros de query

formato

a4 (por defecto) o ticket (rollo ~80mm)

string

Allowed values: a4 ticket

Ejemplo

a4

a4 (por defecto) o ticket (rollo ~80mm)

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

PDF del CFE recibido

string format: binary

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 recibidos:leer (cfe:leer no alcanza)

{
  "error": {
    "code": "API_ALCANCE_INSUFICIENTE",
    "message": "La credencial de API no tiene ninguno de los alcances necesarios para esta operación (recibidos:leer)",
    "requerido": [
      "recibidos:leer"
    ]
  },
  "requestId": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
}

404

CFE_RECIBIDO_NO_ENCONTRADO: no existe o es de otra empresa (los dos casos responden igual). CFE_RECIBIDO_SIN_XML: existe pero no tiene el XML firmado guardado (xmlDisponible: false en el listado); sin XML no hay QR ni código de seguridad para armar el documento.

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

No existe o es de otra empresa

{
  "error": {
    "code": "CFE_RECIBIDO_NO_ENCONTRADO",
    "message": "CFE recibido no encontrado (3c1e9f62-8a4b-4d7e-b0c2-5f6a7b8c9d0e)"
  },
  "requestId": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
}

El CFE no tiene el XML guardado

{
  "error": {
    "code": "CFE_RECIBIDO_SIN_XML",
    "message": "El CFE recibido (3c1e9f62-8a4b-4d7e-b0c2-5f6a7b8c9d0e) no tiene el XML firmado guardado"
  },
  "requestId": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
}

422

El id no es un UUID o formato no es a4/ticket (VALIDATION_ERROR)

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

Id inválido

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "La petición no pasó la validación",
    "details": [
      {
        "campo": "id",
        "codigo": "invalid_format",
        "mensaje": "Invalid UUID"
      }
    ]
  },
  "requestId": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
}

Formato inválido

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "La petición no pasó la validación",
    "details": [
      {
        "campo": "formato",
        "codigo": "invalid_value",
        "mensaje": "Invalid option: expected one of \"a4\"|\"ticket\""
      }
    ]
  },
  "requestId": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
}

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