Saltearse al contenido
Host Admin

Emite un CFE

POST
/v1/cfe/emitir

Emite un Comprobante Fiscal Electrónico (CFE) y lo envía a DGI.

Este es el endpoint recomendado para integraciones nuevas: el cuerpo es un JSON estructurado y Host Factura se encarga de armar el XML, firmarlo, asignar CAE, manejar la numeración y enviarlo a DGI.

Tipos de CFE soportados

Ver la sección “Tipos de Comprobante Fiscal Electrónico (CFE) soportados” en la introducción para la tabla completa con los 24 tipos (códigos 101 a 153).

Los más usados son:

CódigoDescripciónReceptor
101e-TicketOpcional (consumidor final)
102Nota de Crédito de e-TicketHeredado de la referencia
103Nota de Débito de e-TicketHeredado de la referencia
111e-FacturaObligatorio
112Nota de Crédito de e-FacturaHeredado de la referencia
113Nota de Débito de e-FacturaHeredado de la referencia
121-123e-Factura Exportación y sus NotasObligatorio + exportacionInfo
124e-Remito ExportaciónObligatorio + remitoInfo
181e-RemitoObligatorio + remitoInfo
182e-ResguardoObligatorio + códigos de retención

Ítems

Cada elemento de items[] puede ser:

  • De catálogo: solo { id, quantity }. Los datos del producto se toman del catálogo de la cuenta.
  • Ad-hoc: { name, quantity, price, billingIndex, description?, unit?, code? }. billingIndex es obligatorio: 1=Exento, 2=10%, 3=22%, 4=Otras.

Emisión de Notas de Crédito y Notas de Débito

Las Notas se usan para modificar el monto de un Comprobante Fiscal Electrónico previamente emitido. No hay que volver a enviar los datos del receptor ni la fecha original — todo eso se hereda automáticamente del CFE referenciado.

Notas de Crédito (102, 112, 122, 132, 142, 152): reducen el monto del comprobante original. Casos típicos:

  • Devolución de mercadería por parte del cliente.
  • Error de facturación (monto mal cargado, ítem facturado por error).
  • Descuento aplicado posteriormente.
  • Bonificación comercial.

Notas de Débito (103, 113, 123, 133, 143, 153): aumentan el monto del comprobante original. Casos típicos:

  • Intereses por mora.
  • Cargos adicionales no facturados originalmente (flete, envasado, etc.).
  • Ajustes de precio por diferencias detectadas posteriormente.

Reglas de correspondencia entre el tipo de la Nota y el del CFE referenciado:

Tipo de NotaPuede referenciar
102 (Nota de Crédito de e-Ticket) / 103 (Nota de Débito de e-Ticket)e-Ticket (101)
112 (Nota de Crédito de e-Factura) / 113 (Nota de Débito de e-Factura)e-Factura (111)
122 / 123 (Notas de e-Factura Exportación)e-Factura Exportación (121)
132 / 133 (Notas de e-Ticket por Cuenta Ajena)e-Ticket por Cuenta Ajena (131)
142 / 143 (Notas de e-Factura por Cuenta Ajena)e-Factura por Cuenta Ajena (141)
152 / 153 (Notas de e-Boleta de Entrada)e-Boleta de Entrada (151)

Cómo emitirla: enviá el tipo correspondiente y referenciaId con el UUID del CFE original. Los items[] representan las líneas que se están acreditando/debitando — no son los ítems originales.

CFE de Cobranza (e-Recibo)

Para documentar el cobro de una venta a crédito (o un adelanto de precios), emití un e-Ticket (101) o e-Factura (111) con esCobranza: true (A-C20 IndCobPropia=1). Reglas:

  • Todas las líneas deben ser no facturables: billingIndex 6 (no facturable) o 7 (no facturable negativo). La operación ya se gravó al emitir la factura original, así que la cobranza no vuelve a generar IVA.
  • La representación impresa lleva la leyenda “Cobranza” (requisito DGI).
  • referenciaId (opcional) apunta a la factura a crédito cobrada y arma la Referencia (Zona F).
  • Admite cobros parciales: el monto cobrado es el de las líneas.
  • Documentar la cobranza es opcional según DGI; la forma de pago de la factura original es solo informativa y no obliga a emitir un recibo posterior.

Moneda extranjera

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

Pre-requisitos de la cuenta

Para que la emisión funcione, la cuenta debe tener: certificado de facturación electrónica vigente, CAE vigente para el tipo+serie+sucursal, y datos básicos de empresa cargados. Si falta algo, recibirás 409 CERTIFICADO_NO_VIGENTE, 409 NO_CAE_VIGENTE u otro error específico, antes de consumir numeración. Mientras la empresa tramita el certificado podés probar tus comprobantes con POST /v1/cfe/validar-cfe.

Metadatos personalizados

El campo opcional metadata adjunta datos propios del negocio (no fiscales) al CFE: número de transacción de pago, método de pago, referencia externa, etc. Las claves deben corresponder a campos ya definidos para la cuenta desde el panel web (Configuración → Campos personalizados); no existe un endpoint público para crearlos ni listarlos. Claves desconocidas o valores fuera de tipo devuelven 422 METADATA_INVALIDA (detalle en error.details). Se devuelven de vuelta en data.metadata, tanto en esta respuesta como en GET /v1/cfe/info/{id}. No soportado en POST /v1/cfe/emitir-xml. Editar los metadatos de un CFE ya emitido solo es posible desde el panel web, no por esta API. Guía completa: Metadatos personalizados.

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

Sección titulada «Autorizaciones »

Parámetros

Sección titulada « Parámetros »

Parámetros de header

Sección titulada «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.

Idempotency-Key
string
>= 8 characters <= 128 characters /^[A-Za-z0-9._:~-]{8,128}$/
Ejemplo
venta-000123

Clave de idempotencia de la emisión (8 a 128 caracteres de A-Za-z0-9._:~-). Muy recomendada: sin ella, reintentar tras un timeout puede emitir el mismo comprobante dos veces en DGI.

Usá una clave por comprobante (por ejemplo, el id de tu venta) y repetila en cada reintento, con el mismo cuerpo:

  • Emisión terminada: el reintento devuelve el mismo CFE con meta.reusada: true, sin volver a emitir.
  • Emisión todavía en curso: 409 CFE_IDEMPOTENCY_EN_CURSO; reintentá en unos segundos.
  • Error antes de llegar a DGI (validación, CAE, rechazo explícito de DGI): la clave se libera y podés corregir y reintentar con la MISMA clave.
  • El envío a DGI no se confirmó (timeout o corte): 409 CFE_EMISION_INCIERTA. No reintentes con otra clave: revisá el listado de emitidos o contactá a soporte.

La misma clave con otro cuerpo u otro endpoint devuelve 409 CFE_IDEMPOTENCY_KEY_CONFLICTO; una clave con formato inválido, 400 CFE_IDEMPOTENCY_KEY_INVALIDA. Si no se puede registrar la clave, 503 CFE_IDEMPOTENCIA_NO_DISPONIBLE y no se emite. La ventana es de 24 horas (7 días para una emisión incierta).

Cuerpo de la solicitud

Sección titulada «Cuerpo de la solicitud »

Datos del CFE a emitir

object
clienteId
string format: uuid
cliente
object
tipoDocumento
Any of:
number
documento
string
razonSocial
string
denominacion
string
direccion
string
ciudad
string
estado
string
pais
string
email
string
items
required
Array<object>
>= 1 items
object
id
string format: uuid
name
string
quantity
required
number
price
number
billingIndex
integer
unit
string
description
string
code
string
codeType
string
kind
string
tipo
required
integer
moneda
required
string
Allowed values: UYU USD ARS BRL EUR
cambio
number
adenda
string
formaPago
Any of:
number
Allowed values: 1
fchVenc

A-C12 Fecha de vencimiento del pago (AAAA-MM-DD). Pensada para ventas a crédito (formaPago=2).

string
fchValor

A-C5.1 FchValor (AAAA-MM-DD) — fecha valor, EXCLUSIVA del e-Resguardo (182): la usan los organismos del Estado cuando la fecha en que se hace efectiva la retención difiere de la fecha contable de emisión. Debe caer en el MISMO MES que fchEmis (DGI exige que coincida el AAAAMM) y su año no puede pasar de 2050. En cualquier otro tipo devuelve 422.

string
esCobranza

Emite un CFE de Cobranza (e-Recibo, A-C20 IndCobPropia=1): solo e-Ticket (101) o e-Factura (111), con todas las líneas no facturables (billingIndex 6 o 7) y la leyenda “Cobranza” en la representación impresa. Opcionalmente, referenciaId apunta a la factura a crédito cobrada (Referencia Zona F).

boolean
referenciaId
string format: uuid
referencias
Array<object>
<= 40 items
object
referenciaId
required
string format: uuid
monto
required
number
exportacionInfo
object
clausulaVenta
required
string
modalidadVenta
required
integer
viaTransporte
required
integer
remitoInfo
object
tipoTraslado
required
integer
>= 1 <= 2
propiedadMercaderia
integer
clauVenta
string
modVenta
integer
viaTransp
integer
tipoTraslado
integer
>= 1 <= 2
propiedadMercaderia
integer
compraId

CompraID — estandar DGI para el nº de orden de compra / ID de pago del RECEPTOR. Viaja en el bloque Receptor del XML. Hasta 50 caracteres. No lo admite el e-Resguardo (182).

string
<= 50 characters
mandante

Venta por cuenta ajena (131/132/133 y 141/142/143): datos del mandante, es decir, por cuenta de quién se vende. Van en la zona K (Complemento Fiscal) del CFE; el RUC emisor de esa zona es siempre el de tu cuenta. Obligatorio en esos tipos, notas incluidas, y prohibido en el resto (422).

object
tipoDocumento
required

K-C2 TipoDocMdte — tipo de documento del mandante: 1=NIE, 2=RUC, 3=CI, 4=Otros, 5=Pasaporte, 6=DNI (Argentina, Brasil, Chile o Paraguay), 7=NIFE.

integer
>= 1 <= 7
pais
required

K-C3 Pais — código ISO 3166-1 alfa-2 del país emisor del documento (ej. UY).

string
>= 2 characters <= 2 characters
documento
required

K-C4 DocMdte — número de documento del mandante (hasta 20 caracteres). Si es RUC o CI uruguayos se valida el dígito verificador.

string
<= 20 characters
razonSocial
required

K-C5 NombreMdte — nombre o razón social del mandante (hasta 150 caracteres).

string
<= 150 characters
metadata

Metadatos personalizados de la cuenta (campos NO fiscales definidos desde el panel web, Configuración → Campos personalizados). Las claves deben coincidir con las definidas para la cuenta; valores fuera de tipo/formato son rechazados con 422 METADATA_INVALIDA. Cada valor es un texto, un número, un booleano, una lista de textos o null (que borra el valor del campo). No soportado en POST /v1/cfe/emitir-xml.

object
key
additional properties
Any of:
string
retenciones
Array<object>
>= 1 items <= 5 items
object
codigo
required

B-C20 CodRet — código de la tabla de Retención/Percepción de DGI, formato FFFF-LLL (ej. “2183-010”). Consultable en GET /cfe/retenciones. Los códigos del formulario 2181 son CRÉDITOS FISCALES (A-C127): su importe suma a mntTotCredFisc (A-C125.1), NO a mntTotRetenido (A-C125).

string
tasa

B-C21 Tasa (%) aplicada. Opcional.

number
<= 100
monto
required

B-C22 MntSujetoaRet — base imponible sobre la que se retiene. Debe ser mayor a 0.

number
valor
required

B-C23 ValRetPerc — importe retenido/percibido.

number
infoAdicional

B-C22.1 InfoAdicionalRet — leyenda normativa de la línea (hasta 150 caracteres). Cuando se envía, la representación impresa del e-Resguardo la imprime debajo del concepto: DGI lo exige (Formato CFE v25).

string
<= 150 characters
lineasResguardo
Array<object>
>= 1 items <= 200 items
object
ajuste

Marca la línea como AJUSTE (B-C4 IndFact=9): sus importes RESTAN del agregado por código (A-C128) y por lo tanto de mntTotRetenido/mntTotCredFisc. Exige referenciaId apuntando al e-Resguardo que se ajusta.

boolean
retenciones
required

Tabla de Retención/Percepción de esta línea de detalle (Item_Resg admite hasta 5).

Array<object>
>= 1 items <= 5 items
object
codigo
required

B-C20 CodRet — código de la tabla de Retención/Percepción de DGI, formato FFFF-LLL (ej. “2183-010”). Consultable en GET /cfe/retenciones. Los códigos del formulario 2181 son CRÉDITOS FISCALES (A-C127): su importe suma a mntTotCredFisc (A-C125.1), NO a mntTotRetenido (A-C125).

string
tasa

B-C21 Tasa (%) aplicada. Opcional.

number
<= 100
monto
required

B-C22 MntSujetoaRet — base imponible sobre la que se retiene. Debe ser mayor a 0.

number
valor
required

B-C23 ValRetPerc — importe retenido/percibido.

number
infoAdicional

B-C22.1 InfoAdicionalRet — leyenda normativa de la línea (hasta 150 caracteres). Cuando se envía, la representación impresa del e-Resguardo la imprime debajo del concepto: DGI lo exige (Formato CFE v25).

string
<= 150 characters
mntTotRetenido

A-C125 MntTotRetenido — total RETENIDO del e-Resguardo. Solo los códigos que NO son del formulario 2181: los 2181xxx son créditos fiscales y van a A-C125.1 mntTotCredFisc. Si se omite, se deriva de la suma (con signo: las líneas de ajuste restan) de los importes no-2181; si se envía, debe coincidir con esa suma. Puede ser 0 (resguardo que solo documenta créditos fiscales) o negativo (resguardo de ajuste).

number
Ejemplos

e-Ticket a consumidor final (sin datos de receptor)

Caso típico de POS: venta de bajo monto a consumidor final, sin RUT ni datos del cliente. Para tipo 101 (e-Ticket), si el monto neto en UI no supera el tope (~10.000 UI), el receptor es opcional.

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

Respuestas

Sección titulada « Respuestas »

200

Sección titulada «200 »

CFE emitido. Verificá el campo data.estado (aceptado/pendiente/rechazado/observado).

object
data
required
object
id
required
string format: uuid
tipo
required
integer
tipoDescripcion
required
string
serie
required
string
nullable
numero
required
integer
nullable
rutEmisor
required
string
nullable
moneda
required
string
tipoCambio
required
number
nullable
subtotal
required
number
iva
required
number
total
required
number
adenda
required
string
compraId
required

CompraID — identificador de compra del receptor (nº de orden de compra o de pago) declarado al emitir

string
nullable
retenciones
required

E-Resguardo (182): tabla de Retencion/Percepcion declarada al emitir. null en el resto de los tipos

Array<object>
nullable
object
codigo
required
string
descripcion
required

Descripcion oficial del codigo en la tabla DGI

string
nullable
tasa
required
number
nullable
monto
required

B-C22 MntSujetoaRet — base imponible

number
nullable
valor
required

B-C23 ValRetPerc — importe retenido/percibido

number
nullable
infoAdicional
required
string
nullable
esCreditoFiscal
required

true para los codigos del formulario 2181: suman a mntTotCredFisc, no a mntTotRetenido

boolean
ajuste
required

B-C4 IndFact=9: la linea RESTA del agregado. valor se mantiene positivo, igual que en el XML

boolean
mntTotRetenido
required

A-C125 — total retenido (solo codigos que NO son del formulario 2181). Es el total del e-Resguardo

number
nullable
mntTotCredFisc
required

A-C125.1 — total de creditos fiscales (solo codigos 2181xxx)

number
nullable
anulado
required
boolean
estado
required
string
Allowed values: pendiente aceptado rechazado observado
estadoDgi
required
string
nullable
fechaEstadoDgi
required
string
nullable
motivoRechazo
required
string
nullable
codigoRespuesta
required
string
codigoSucursalDgi
required
number
nullable
clienteId
required

Cliente del catalogo, si el CFE se emitio contra uno

string
nullable
cliente
required
object
tipoDocumento
required

Tipo de documento como texto: RUC, CI, Pasaporte, …

string
documento
required
string
denominacion
required
string
direccion
required
string
nullable
ciudad
required
string
nullable
departamento
required
string
nullable
pais
required
string
cuentaId
required
string format: uuid
sucursalId
required
string format: uuid
nullable
puntoEmisionId
required
string format: uuid
nullable
referenciaId
required
string format: uuid
nullable
uuidReferencia
required
string format: uuid
sobreId
required
string format: uuid
nullable
reporteDiarioId
required
string format: uuid
nullable
cfeRecurrenteId
required
string format: uuid
nullable
origen
required

Canal por el que se emitio (trazabilidad del integrador)

string
nullable
requestId
required

requestId de la llamada que lo emitio, para correlacionar logs

string
nullable
fechaCreacion
required
string
fechaActualizacion
required
string
metadata
required

Metadatos personalizados capturados en la emisión. {} si la cuenta no tiene campos configurados o no se enviaron valores.

object
key
additional properties
Any of:
string
Ejemplos

CFE emitido y aceptado por DGI

{
  "data": {
    "id": "8a7b6c5d-4e3f-2a1b-9c8d-7e6f5a4b3c2d",
    "tipo": 111,
    "tipoDescripcion": "e-Factura",
    "serie": "A",
    "numero": 1234,
    "rutEmisor": "210000000000",
    "moneda": "UYU",
    "tipoCambio": 1,
    "subtotal": 12500,
    "iva": 2750,
    "total": 15250,
    "adenda": "Forma de pago: transferencia BROU 001-1234567-89",
    "compraId": "OC-2026-00845",
    "retenciones": null,
    "mntTotRetenido": null,
    "mntTotCredFisc": null,
    "anulado": false,
    "estado": "aceptado",
    "estadoDgi": "A",
    "fechaEstadoDgi": "2026-05-17T13:42:11.000Z",
    "motivoRechazo": null,
    "codigoRespuesta": "00",
    "codigoSucursalDgi": 1,
    "clienteId": null,
    "cliente": {
      "tipoDocumento": "RUC",
      "documento": "219999830019",
      "denominacion": "EMPRESA EJEMPLO S.A.",
      "direccion": null,
      "ciudad": null,
      "departamento": null,
      "pais": "UY"
    },
    "cuentaId": "1d2e3f4a-5b6c-7d8e-9f0a-1b2c3d4e5f6a",
    "sucursalId": null,
    "puntoEmisionId": null,
    "referenciaId": null,
    "uuidReferencia": "9b8a7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "sobreId": "2a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d",
    "reporteDiarioId": null,
    "cfeRecurrenteId": null,
    "origen": "api_v1",
    "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c",
    "fechaCreacion": "2026-05-17T13:42:10.000Z",
    "fechaActualizacion": "2026-05-17T13:42:11.000Z",
    "metadata": {}
  }
}

400

Sección titulada «400 »

Datos inválidos. El cuerpo no pasa la validación, o el CFE no es construible.

Códigos posibles:

  • CLIENT_CI_INVALID — Cédula uruguaya con dígito verificador incorrecto.
  • NOTA_REFERENCE_UNDEFINED — Es una Nota de Crédito o Nota de Débito y falta referenciaId.
  • EXPORTACION_INFO_REQUIRED — Es CFE de exportación y falta exportacionInfo.
  • REMITO_INFO_REQUIRED — Es e-Remito y falta remitoInfo.
  • ITEM_INVALIDO — Un ítem no tiene nombre o unidad.
  • PUNTO_EMISION_REQUERIDO — Sucursal con múltiples puntos sin x-point-id.
  • SUCURSAL_INVALIDA — x-branch-id no pertenece a la cuenta.
  • CFE_IDEMPOTENCY_KEY_INVALIDA — la cabecera Idempotency-Key no tiene el formato válido.
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

Cédula uruguaya con dígito verificador inválido

{
  "error": {
    "code": "CLIENT_CI_INVALID",
    "message": "La cédula uruguaya del cliente no es válida (dígito verificador incorrecto)"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

401

Sección titulada «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"
}

403

Sección titulada «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:

CodeQué pasóCómo se corrige
API_FEATURE_DISABLEDLa cuenta no tiene la API habilitada en su planPedir la habilitación a soporte o al proveedor
API_ALCANCE_INSUFICIENTELa credencial no tiene el alcance de la operación (va en error.requerido)Editar la credencial en Integraciones → API
API_ALCANCE_NO_DISPONIBLELa 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.detailsPedir la habilitación a soporte o al proveedor
API_ACCESS_BRANCH_MISMATCHx-branch-id distinto de la sucursal fijada en la credencialQuitar la cabecera o usar otra credencial
API_CUENTA_FUERA_DE_CARTERAx-cuenta-id apunta a una cuenta que no es de la carteraRevisar 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"
}

404

Sección titulada «404 »

Recurso referenciado no existe.

  • CLIENTE_NO_ENCONTRADO — clienteId no existe en la cuenta.
  • CFE_REFERENCIA_NO_EXISTE — referenciaId no existe (al emitir una Nota de Crédito o Nota de Débito).
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

Cliente referenciado no existe

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

409

Sección titulada «409 »

Conflicto con el estado actual (certificado o CAE). No consume numeración: corregí la configuración de la empresa y reintentá.

  • CERTIFICADO_NO_VIGENTE — La empresa no tiene un certificado de facturación electrónica vigente y en uso.
  • NO_CAE_VIGENTE — No hay CAE activo para el tipo solicitado.
  • CAE_RANGE_EXHAUSTED — Se agotó el rango de numeración del CAE.
  • SUCURSAL_INACTIVA — La sucursal resuelta está deshabilitada.

Con Idempotency-Key:

  • CFE_IDEMPOTENCY_EN_CURSO — la emisión con esa clave todavía está en curso; reintentá con la misma clave.
  • CFE_EMISION_INCIERTA — el envío a DGI de esa clave no se confirmó. No reintentes con otra clave.
  • CFE_IDEMPOTENCY_KEY_CONFLICTO — la clave ya se usó con otro cuerpo u otro endpoint.
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

La empresa no tiene certificado de facturación electrónica vigente

{
  "error": {
    "code": "CERTIFICADO_NO_VIGENTE",
    "message": "No es posible emitir el comprobante: la empresa no tiene un certificado de facturación electrónica vigente."
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

422

Sección titulada «422 »

Metadatos personalizados inválidos (metadata).

  • METADATA_INVALIDA — una o más claves no están definidas para la cuenta, o el valor no cumple el tipo/formato configurado. El detalle campo por campo va en error.details.
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

Metadatos personalizados inválidos

{
  "error": {
    "code": "METADATA_INVALIDA",
    "message": "Metadatos inválidos: metodo_pago: valor no permitido; nro_transaccion: requerido",
    "details": [
      "metodo_pago: valor no permitido",
      "nro_transaccion: requerido"
    ]
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

429

Sección titulada «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

Sección titulada «Headers »
Retry-After
integer
Ejemplo
42

Segundos hasta que se libera la ventana de rate limit

503

Sección titulada «503 »

No se pudo registrar la Idempotency-Key (CFE_IDEMPOTENCIA_NO_DISPONIBLE). El comprobante no se emitió. Reintentá con la misma clave (cabecera Retry-After).

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

Almacén de idempotencia no disponible

{
  "error": {
    "code": "CFE_IDEMPOTENCIA_NO_DISPONIBLE",
    "message": "No se pudo registrar la Idempotency-Key y el comprobante NO se emitió. Reintentá en unos segundos con la misma clave."
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}