Modo passthrough: enviar el XML e-CF ya construido¶

Si su sistema ya genera el XML e-CF, puede enviarlo tal cual en vez del JSON canónico. Esta API lo valida, lo firma con el certificado del emisor, lo valida contra el XSD oficial y lo transmite a la DGII, con el mismo seguimiento de estado que la vía JSON.

No tocamos su XML. Lo único que se le añade es la firma digital.

Cómo se activa¶

El mismo endpoint, cambiando el Content-Type:

POST /api/v1/documents/31
Authorization: Bearer {su-token}
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<ECF><Encabezado><Emisor><RNCEmisor>133802074</RNCEmisor>…</Emisor>…</Encabezado><DetallesItems>…</DetallesItems><FechaHoraFirma>…</FechaHoraFirma></ECF>

Es el mismo recurso en otra representación: application/json → JSON canónico, application/xml (o text/xml) → passthrough.

La empresa se identifica con el <RNCEmisor> del propio XML: no hace falta ninguna cabecera ni parámetro aparte. La API lee ese nodo y comprueba que su token esté habilitado para esa empresa (tokens-y-permisos.md). Si el XML no se puede leer, o no trae RNCEmisor, responde 422 con un mensaje que lo explica («No se pudo leer el RNC de la empresa.» / «Falta indicar la empresa.», con el porqué en data.detalle; nunca un 500) y no se crea nada.

Envíelo SIN firmar¶

La firma la aplica esta API con el certificado del emisor. Un XML que ya venga firmado se rechaza: no podemos re-firmar el documento de otro, y la firma del integrador no serviría porque el certificado tiene que corresponder al emisor.

Qué se valida antes de aceptarlo¶

En las dos vías el e-NCF lo trae usted: la numeración la lleva su sistema (numeracion.md). Y como en passthrough además el XML es suyo, se comprueba de forma explícita:

Comprobación	Por qué
XML bien formado y raíz `<ECF>`	Lo mínimo para poder procesarlo
`TipoeCF` = tipo de la ruta	Evita emitir un 32 por la ruta del 31
`RNCEmisor` = RNC de una empresa habilitada para su token	No se firma el comprobante de otro RNC. La DGII lo rechazaría por "firmante no autorizado"
El XML no viene firmado	Ver arriba
`eNCF` con estructura `E` + tipo + 10 dígitos	Formato de la norma
`FechaVencimientoSecuencia` presente (tipos 31, 33, 41, 43, 44, 45, 46 y 47) y no vencida	La DGII valida el e-NCF contra su autorización y su vencimiento
Si registró su autorización: el e-NCF cae dentro de un rango activo y la fecha es la de esa autorización	Cazar un número fuera de rango antes de gastarlo
El e-NCF no pertenece a un rango anulado	"No pudiéndose utilizar posteriormente secuencias que sí hayan podido ser anuladas"
`IdDoc/IndicadorMontoGravado` presente si hay ítems gravados (tipos 31, 32, 33, 34, 41 y 45)	La DGII lo exige cuando algún ítem lleva ITBIS (`IndicadorFacturacion` 1, 2 o 3) y rechaza el comprobante sin él. El esquema XSD lo deja opcional, así que no basta con que su XML valide contra el XSD

Cualquiera de ellas devuelve 422 con el motivo concreto, sin crear nada. Como el comprobante es un e-CF, la respuesta lleva el bloque document (estado rejected_validation) con los motivos en document.errors:

{
  "status": "error",
  "message": "El XML e-CF no se pudo recibir.",
  "document": {
    "status_code": 2,
    "status": "rejected_validation",
    "status_description": "El e-CF no superó las validaciones previas al envío y no se transmitió a la DGII: su e-NCF no llegó a usarse ante ella.",
    "errors": [
      "El TipoeCF del XML (31) no corresponde al tipo de la ruta (32).",
      "El e-NCF indicado (E310000000012) no tiene la estructura E+tipo+10 dígitos del tipo 32."
    ]
  }
}

Que el e-NCF ya exista no es un error de validación: se responde según el estado del documento que ya lo tiene (200, 202 o 409, con "duplicate": true), igual que en la vía JSON. Vea el detalle.

La fecha de emisión es la del XML¶

En la vía JSON sellamos la fecha al recibir el comprobante. En passthrough manda la FechaEmision que usted declara: es la que la DGII va a ver y con la que recalcula sus reglas (por ejemplo la de los 30 días de la nota de crédito). Asegúrese de que sea la real.

Factura de consumo por debajo de RD$250.000¶

También en passthrough se transmite como resumen (RFCE), igual que en la vía JSON: se firma y conserva su e-CF completo, y del XML que envió se extraen los datos del resumen para remitirlo al servicio que corresponde. No tiene que construir el RFCE usted.

Respuesta¶

Idéntica a la de la vía JSON (la forma de las respuestas): 202 con el document_id, el e-NCF, el identificador y el estado interno, en un document (el message es «XML e-CF recibido y encolado para firma y envío a la DGII.»). El track_id viene null en ese 202 (la transmisión ocurre después, en segundo plano) y, a partir de ahí, el ciclo es el mismo — transmisión y sondeo del TrackID cuando lo hay (el resumen RFCE de una factura de consumo no lo tiene nunca), representación impresa y consulta por GET /api/v1/documents/{identificador} (cómo se arma: su RNC, que es el <RNCEmisor> del XML, seguido del <eNCF>). Cuándo aparece el track_id, en estados.md.

Referencias¶

Campos comunes · Estados · README