Datos de la representación impresa de un CFE (JSON)

GET

/v1/cfe/representacion-impresa/{id}

Producción
Homologación / pruebas

Devuelve los datos con los que Host Factura arma el PDF del comprobante: emisor, receptor, líneas, totales, leyendas normativas, contenido del QR de DGI, referencias y adenda. Es el mismo objeto con el que se arma el PDF.

Cuándo usarlo en vez de `GET /v1/cfe/pdf/{id}`

Cuando querés tu propia plantilla (tu membrete, tu tamaño de papel, tu impresora de tique) sin tener que derivar de la normativa de DGI qué leyendas corresponden a cada tipo de CFE ni cómo se arma el contenido del QR. Eso es exactamente lo que este endpoint ya resolvió.

Claves principales

Parametros (QR como imagen PNG en data-URL, CodSeg = código de seguridad, leyenda de verificación, logo), Emisor, Receptor, IdDoc (tipo, serie, número, fechas en DD/MM/YYYY), CaeData, Totales (nombres de DGI), Detalle, Referencias, Adenda, MediosPago, esRemito, esResguardo y, cuando corresponden, Retenciones (e-Resguardo) y CamposAdicionales. Los importes que vienen del XML llegan como texto.

⚠️ La estructura no es un contrato estable campo a campo: sigue al renderizador, que cambia cuando cambia el Manual de Representación Impresa de DGI. Leé los campos que necesitás y tolerá los que aparezcan.

Alcance requerido: cfe: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

Identificador único del recurso (UUID v4)

string format: uuid

Identificador único del recurso (UUID v4)

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.

x-branch-id

string format: uuid

Sucursal contra la que operar, cuando la credencial es global. Si la credencial está fijada a una sucursal y esta cabecera indica otra, la respuesta es 403 API_ACCESS_BRANCH_MISMATCH. Sin la cabecera se asume la casa central.

x-point-id

string format: uuid

Punto de emisión dentro de la sucursal resuelta. Obligatorio cuando la sucursal tiene 2 o más puntos activos (400 PUNTO_EMISION_REQUERIDO si falta); con uno solo se selecciona automáticamente.

Respuestas

200

Datos de la representación impresa (ejemplo recortado: paramQR y logo son data-URLs base64)

object

Ejemplos

{
  "data": {
    "Parametros": {
      "paramQR": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…",
      "CodSeg": "aB3dE9",
      "LeyendaVerificacion": "Puede verificar comprobante en www.dgi.gub.uy",
      "MostrarTipoCambio": false,
      "Nota": false,
      "pagina": "1",
      "totalPaginas": "1",
      "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…",
      "logoSize": 256,
      "paramHeader": "#F3F3F3",
      "paramDecimals": "00",
      "paramLetter": "#000000",
      "logoLeft": "0",
      "logoTop": "0",
      "AdendaSeparada": false
    },
    "Receptor": {
      "TipoDocRecep": "RUC",
      "DocRecep": "219999990019",
      "RznSocRecep": "CLIENTE S.R.L.",
      "DirRecep": "Rivera 2000",
      "CiudadRecep": "Montevideo",
      "DepartamentoRecep": "Montevideo",
      "CP": "",
      "Item": "1",
      "CompraID": "OC-2026-118",
      "PaisRecep": "Uruguay",
      "DeptoRecep": "Montevideo",
      "DocRecepExt": "",
      "CodPaisRecep": "UY",
      "InfoAdicionalEmisor": "",
      "DomicilioUnificado": "Rivera 2000, Montevideo, Montevideo, Uruguay"
    },
    "Emisor": {
      "RUCEmisor": "212345670019",
      "NomComercial": "Ejemplo",
      "RznSoc": "EJEMPLO S.A.",
      "DomFiscal": "18 de Julio 1234",
      "Ciudad": "Montevideo",
      "Departamento": "Montevideo",
      "CorreoEmisor": "facturacion@ejemplo.com.uy",
      "TelEmisor": "2900 0000",
      "InfoAdicionalEmisor": "",
      "GiroEmis": "",
      "LeyendaEmisor": ""
    },
    "IdDoc": {
      "TipoCFE": "e-Factura",
      "Serie": "A",
      "Nro": 1042,
      "FchEmis": "12/09/2026",
      "FmaPago": "Crédito",
      "ClauVenta": "AS",
      "FchVenc": "12/10/2026"
    },
    "CaeData": {
      "CAE_ID": "90230001234",
      "DNro": "1",
      "HNro": "10000",
      "FecVenc": "31/12/2027"
    },
    "Totales": {
      "TpoMoneda": "UYU",
      "MntNoGrv": "0",
      "MntNetoIvaTasaMin": "0",
      "MntNetoIVATasaBasica": "1000",
      "IVATasaMin": "10",
      "IVATasaBasica": "22",
      "MntIVATasaMin": "0",
      "MntIVATasaBasica": "220",
      "MntTotal": "1220",
      "CantLinDet": "1",
      "MntPagar": "1220",
      "Subtotal": 1000
    },
    "Referencias": [],
    "Detalle": [
      {
        "NroLinDet": 1,
        "NomItem": "Servicio mensual",
        "Cantidad": "1",
        "UniMed": "N/A",
        "IndFact": "3",
        "PrecioUnitario": "1000",
        "MontoItem": "1000",
        "DscItem": "Mantenimiento setiembre",
        "isNegativo": false
      }
    ],
    "Adenda": "",
    "esRemito": false,
    "esResguardo": false,
    "MediosPago": [
      {
        "GlosaMP": "Crédito",
        "ValorPago": 1220
      }
    ]
  }
}

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

404

CFE no encontrado o pertenece a otra cuenta

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

CFE no encontrado

{
  "error": {
    "code": "CFE_EMITIDO_NO_ENCONTRADO",
    "message": "CFE no encontrado (uuid)"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

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

Datos de la representación impresa de un CFE (JSON)

Cuándo usarlo en vez de GET /v1/cfe/pdf/{id}

Claves principales

Autorizaciones

Parámetros

Parámetros de path

Parámetros de header

Ejemplo

Respuestas

200

Ejemplos

401

Ejemplos

403

Ejemplos

404

Ejemplos

429

Ejemplos

Headers

Ejemplo

Cuándo usarlo en vez de `GET /v1/cfe/pdf/{id}`