Saltearse al contenido
Host Admin

Emite un CFE a partir de un XML pre-armado (formato DGI nativo)

POST
/v1/cfe/emitir-xml

Endpoint para proveedores de facturación electrónica con integración previa a DGI.

Pensado específicamente para proveedores y empresas que ya operaban contra los servicios SOAP de DGI de forma directa y quieren migrar a Host Factura sin reescribir su armador de XML. El cliente envía el contenido del CFE como si fuera a DGI directo, y Host Factura se encarga exclusivamente de la firma, asignación de CAE, numeración y envío del sobre.

⚠️ Responsabilidad de mantener el armador actualizado

DGI actualiza periódicamente los formatos de CFE (nuevos campos obligatorios, cambios en validaciones, modificaciones en los XSD). Cuando esto ocurre:

  • Host Factura actualiza las validaciones XSD del sobre de su lado tan pronto como DGI publica el cambio, y rechaza los CFE que no cumplan con el formato vigente devolviendo 400 XML_EXTERNO_INVALIDO con el detalle del error reportado por DGI.
  • Tu sistema debe mantener su armador de XML al día con los formatos publicados por DGI. Si tu armador queda desactualizado respecto al esquema vigente, tus emisiones empezarán a fallar incluso cuando antes funcionaban.

Recomendamos suscribirte a las comunicaciones de DGI sobre cambios en e-Factura (circulares, actualizaciones de los documentos Formato_CFE_vXX y Formato_Sobre_vXX) y planificar una validación de tu armador cada vez que DGI publique una nueva versión.

⚠️ Validación de montos a cargo del cliente

Host Factura no recalcula los totales ni valida la consistencia interna de los montos. Confiamos en que los valores de Totales (subtotal, IVA por tasa, total) y los MontoItem del detalle son correctos.

Tu sistema es responsable de garantizar que:

  • MntNetoIVATasaBasica, MntNetoIVATasaMin y MntNetoIVAOtra se calculen correctamente según la tasa aplicada a cada ítem (IndFact).
  • IVATasaBasica (22%) e IVATasaMin (10%) coincidan con la aplicación correcta sobre los netos.
  • MntTotal sea exactamente la suma de los netos, IVA, percepciones y descuentos.
  • Los redondeos respeten las reglas que exige DGI (típicamente 2 decimales, redondeo bancario).
  • En CFE en moneda extranjera, TpoCambio esté presente y el equivalente en pesos sea consistente.

Si los montos no cierran, DGI rechaza el CFE con el código de error correspondiente y la emisión queda persistida con estado: rechazado y motivoRechazo con el detalle.

A quién está dirigido

  • Proveedores de facturación electrónica que ya tenían un flujo productivo emitiendo CFE directamente contra los servicios SOAP de DGI, con su propio motor de armado de XML.
  • Empresas con desarrollos legacy que invirtieron tiempo en armar el XML según el formato DGI y no quieren rehacer el mapeo a un payload JSON estructurado.
  • Implementaciones que necesitan campos avanzados de DGI (IndCompraME en Boleta de Entrada, IndAgenteResp, etc.) que el payload JSON del endpoint estándar no expone con el mismo grado de detalle.

Cuándo NO usar este endpoint

  • Estás arrancando una integración desde cero → usá POST /v1/cfe/emitir (mucho más simple, Host Factura calcula totales, IVA, redondeos por vos).
  • Querés usar el catálogo de productos/clientes de Host Factura → usá el payload JSON.
  • No tenés un armador XML ya construido → la curva de aprendizaje del formato DGI es alta; preferí JSON.

Responsabilidades

Tu sistema (proveedor):

  • Arma el XML del CFE siguiendo el formato oficial DGI (XSDs CFE.xsd, CFEType.xsd).
  • Calcula totales, IVA, retenciones, redondeos.
  • Provee los datos del Emisor, Receptor, Detalle, Totales, Adenda.
  • Si emite Notas de Crédito o Notas de Débito, incluye el nodo Referencia con los datos del comprobante referenciado.

Host Factura:

  • Asigna serie y número desde el CAE vigente, en transacción con lock (sin colisiones).
  • Inyecta el nodo CAEData con los datos del CAE asignado.
  • Firma el XML con xmldsig usando el certificado de facturación electrónica de la cuenta.
  • Arma el sobre, lo valida contra el XSD oficial y lo envía vía SOAP a DGI.
  • Persiste el CFE emitido y devuelve el resultado en la respuesta.

Elementos que Host Factura inyecta (NO los envíes en tu XML)

ElementoUbicaciónCómo se asigna
IdDoc.SerieDentro del nodo del CFETomado del CAE vigente para el tipo+sucursal
IdDoc.NroDentro del nodo del CFEPróximo número secuencial del CAE (padding a 7 dígitos)
CAEDataDentro del nodo del CFEDatos del CAE asignado (CAE_ID, DNro, HNro, FecVenc)
SignatureNivel raíz <CFE>Firma XML DSig con el certificado digital (CVA) de la cuenta

Si tu XML incluye alguno de estos elementos, respondemos con 400 XML_EXTERNO_CAMPO_PROHIBIDO. Esto es defensivo: evitamos que un proveedor pegue por error el XML completo (con CAE y firma ya inyectados) y termine duplicando datos o firmando dos veces.

Estructura del XML esperado

Aceptamos el envoltorio <CFE xmlns="http://cfe.dgi.gub.uy" version="1.0"> o directamente el nodo interno pelado (<eTck>...).

Estructura mínima (válida para cualquier tipo):

<CFE xmlns="http://cfe.dgi.gub.uy" version="1.0">
  <eTck>  <!-- nodo según TipoCFE; ver mapeo abajo -->
    <Encabezado>
      <IdDoc>
        <TipoCFE>101</TipoCFE>     <!-- obligatorio, numérico -->
        <FchEmis>2026-05-17</FchEmis>
        <FmaPago>1</FmaPago>       <!-- 1=contado, 2=crédito -->
      </IdDoc>
      <Emisor>...</Emisor>
      <Receptor>...</Receptor>     <!-- obligatorio en e-Factura y otros -->
      <Totales>...</Totales>
    </Encabezado>
    <Detalle>
      <Item>...</Item>
    </Detalle>
    <Referencia>...</Referencia>   <!-- obligatorio en Notas de Crédito y Notas de Débito -->
  </eTck>
</CFE>

Mapeo TipoCFE → Nodo XML

El nombre del nodo interno debe corresponder al TipoCFE declarado.

TipoCFEDescripciónNodo XML
101e-TicketeTck
102Nota de Crédito de e-TicketeTck
103Nota de Débito de e-TicketeTck
111e-FacturaeFact
112Nota de Crédito de e-FacturaeFact
113Nota de Débito de e-FacturaeFact
121e-Factura ExportacióneFact_Exp
122Nota de Crédito de e-Factura ExportacióneFact_Exp
123Nota de Débito de e-Factura ExportacióneFact_Exp
124e-Remito ExportacióneRem_Exp
131-133e-Ticket por Cuenta Ajena y sus NotaseTck
141-143e-Factura por Cuenta Ajena y sus NotaseFact
151-153e-Boleta de Entrada y sus NotaseBoleta
181e-RemitoeRem
182e-ResguardoeResg

Emisión de Notas de Crédito y Notas de Débito vía XML

Cuando emitís una Nota de Crédito (tipos 102, 112, 122, 132, 142, 152) o una Nota de Débito (tipos 103, 113, 123, 133, 143, 153), tu XML debe incluir el nodo Referencia dentro del cuerpo del CFE con los datos del comprobante que estás referenciando. Host Factura no completa ese nodo automáticamente en este endpoint (a diferencia del endpoint JSON, donde alcanza con enviar referenciaId).

Estructura del nodo Referencia (resumen — ver XSDs DGI para el detalle):

<Referencia>
  <NroLinRef>1</NroLinRef>
  <TpoDocRef>111</TpoDocRef>     <!-- tipo del CFE referenciado -->
  <Serie>A</Serie>
  <NroCFERef>0001234</NroCFERef>
  <FechaCFEref>2026-05-15</FechaCFEref>
</Referencia>

Importante: el campo FechaCFEref debe ser exactamente la FchEmis del CFE original, no la fecha de creación interna. Si difieren, DGI rechaza con código de error E12.

Numeración

El número se asigna dentro de una transacción, que serializa la asignación. Mantiene consistencia entre llamadas concurrentes y respecto del endpoint JSON: ambos endpoints consumen del mismo CAE secuencialmente, sin colisiones de numeración.

Alcance de sucursal

  • Si tu solicitud se resuelve a una sucursal (por cabecera x-branch-id o por ApiAccess fijado a una sucursal), Host Factura sobrescribe el valor de Emisor.CdgDGISucur con el dgiCode de esa sucursal, incluso si tu XML declaraba otro valor. Esto garantiza coherencia entre el alcance del ApiAccess y el código de sucursal declarado a DGI.
  • Si no hay sucursal resuelta, se respeta el CdgDGISucur que viene en tu XML (típicamente el código de casa central).

Cómo valida Host Factura tu XML

Después de inyectar IdDoc.Serie, IdDoc.Nro, CAEData y la firma digital, Host Factura ejecuta estas validaciones antes de enviar el sobre a DGI:

  1. Validación XSD del sobre completo contra los esquemas oficiales DGI vigentes. Si el sobre no es válido, respondemos con 400 XML_EXTERNO_INVALIDO y el detalle del error de schema. Esto cubre estructura, tipos de datos, cardinalidades y restricciones declaradas en los XSD.
  2. Verificación de firma digital sobre el CFE armado (que Host Factura mismo agrega, por lo que esto solo falla si hay un problema con el certificado digital de la cuenta).
  3. Envío a DGI del sobre firmado. DGI realiza una segunda capa de validaciones (consistencia de montos, cuadre de IVA, validez de la referencia para Notas de Crédito y Notas de Débito, etc.). Si DGI rechaza el sobre, persistimos el CFE con estado: rechazado y el motivoRechazo correspondiente.

Host Factura no valida la consistencia matemática de los montos — esa responsabilidad es tuya (ver sección “Validación de montos a cargo del cliente” arriba). Tampoco modifica los datos de tu XML más allá de los campos listados en la tabla de elementos inyectados.

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 required

Sección titulada «Cuerpo de la solicitud required »

Cuerpo con el XML del CFE en formato DGI nativo (sin CAE, sin firma, sin Serie/Nro)

object
xml
required
string
>= 1 characters
email
boolean
copias
Array<string>
<= 10 items
Ejemplos

XML de e-Ticket (tipo 101)

CFE armado por el cliente al formato DGI nativo. El nodo eTck corresponde al tipo 101. NO incluye CAEData, Signature, IdDoc.Serie ni IdDoc.Nro — los inyecta Host Factura.

{
  "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<CFE xmlns=\"http://cfe.dgi.gub.uy\" version=\"1.0\">\n  <eTck>\n    <Encabezado>\n      <IdDoc>\n        <TipoCFE>101</TipoCFE>\n        <FchEmis>2026-05-17</FchEmis>\n        <FmaPago>1</FmaPago>\n      </IdDoc>\n      <Emisor>\n        <RUCEmisor>210000000000</RUCEmisor>\n        <RznSoc>MI EMPRESA S.A.</RznSoc>\n        <NomComercial>Mi Empresa</NomComercial>\n        <CdgDGISucur>1</CdgDGISucur>\n        <DomFiscal>18 de Julio 1234</DomFiscal>\n        <Ciudad>Montevideo</Ciudad>\n        <Departamento>Montevideo</Departamento>\n      </Emisor>\n      <Totales>\n        <TpoMoneda>UYU</TpoMoneda>\n        <MntNetoIVATasaBasica>200</MntNetoIVATasaBasica>\n        <IVATasaBasica>22</IVATasaBasica>\n        <MntTotal>244</MntTotal>\n        <CantLinDet>1</CantLinDet>\n        <MntPagar>244</MntPagar>\n      </Totales>\n    </Encabezado>\n    <Detalle>\n      <Item>\n        <NroLinDet>1</NroLinDet>\n        <IndFact>3</IndFact>\n        <NomItem>Café americano</NomItem>\n        <Cantidad>2.000</Cantidad>\n        <UniMed>UN</UniMed>\n        <PrecioUnitario>100.00</PrecioUnitario>\n        <MontoItem>200.00</MontoItem>\n      </Item>\n    </Detalle>\n  </eTck>\n</CFE>"
}

Respuestas

Sección titulada « Respuestas »

200

Sección titulada «200 »

CFE emitido con éxito. Misma estructura de respuesta que POST /v1/cfe/emitir.

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 »

XML inválido o con campos prohibidos.

CódigoCuándo
XML_EXTERNO_INVALIDOEl XML no parsea, falta IdDoc, TipoCFE no es numérico, el nodo inner no coincide con el tipo, o el sobre construido falla validación XSD
XML_EXTERNO_TIPO_NO_SOPORTADOEl TipoCFE declarado no está en el mapa de tipos soportados
XML_EXTERNO_CAMPO_PROHIBIDOIncluiste CAEData, Signature, IdDoc.Serie o IdDoc.Nro
CFE_IDEMPOTENCY_KEY_INVALIDALa 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

XML mal formado o sin IdDoc

{
  "error": {
    "code": "XML_EXTERNO_INVALIDO",
    "message": "El CFE debe contener un nodo IdDoc"
  },
  "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"
}

409

Sección titulada «409 »

Sin certificado o sin CAE disponible para firmar y numerar.

Mismas causas que POST /v1/cfe/emitir: CERTIFICADO_NO_VIGENTE, NO_CAE_VIGENTE, CAE_RANGE_EXHAUSTED.

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

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

502

Sección titulada «502 »

DGI rechazó el sobre o no respondió correctamente. El payload incluye el motivo reportado por DGI. Reintentá tras corregir el XML; los reintentos no consumen número.

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

Sobre rechazado por DGI

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "DGI rechazó el envío (código 89): Sobre con estructura no válida"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

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