e-CF 31 — Factura de Crédito Fiscal Electrónica¶
El emisor.rnc del cuerpo dice de qué empresa es el comprobante y, a la vez, en nombre de quién se emite: la API
comprueba que su token esté habilitado para esa empresa (cómo funciona).
Es el comprobante de las ventas entre contribuyentes (B2B). Le permite al comprador sustentar crédito fiscal del ITBIS, por eso identificar al comprador es obligatorio.
Si vende a consumidor final, use la Factura de Consumo (32).
Particularidades¶
| Aspecto | Regla |
|---|---|
| Comprador | Obligatorio: rnc y razon_social. |
| Numeración | id_doc.e_ncf (E31 + 10 dígitos) y id_doc.fecha_vencimiento_secuencia (dd-MM-aaaa) obligatorios: la numeración la lleva su sistema. Ver numeracion.md. La fecha de vencimiento se imprime en la representación impresa. |
| Líneas de detalle | Máximo 1.000. |
referencia |
Opcional; sólo con código de modificación 4 (reemplazo por contingencia) o 5 (referencia a factura de consumo). |
| Retenciones | Admite total_itbis_retenido y total_isr_retencion. |
Ejemplo mínimo¶
El caso más simple que la API acepta: un ítem gravado al 18 %, pagado de contado.
{
"emisor": {
"rnc": "133802074"
},
"comprador": {
"rnc": "131880738",
"razon_social": "COMERCIO, SRL"
},
"id_doc": {
"e_ncf": "E310000000001",
"fecha_vencimiento_secuencia": "31-12-2028",
"indicador_monto_gravado": 0,
"tipo_ingresos": "01",
"tipo_pago": "1",
"formas_pago": [
{ "forma": "1", "monto": 1180.00 }
]
},
"items": [
{
"nombre": "Producto A",
"cantidad": 1,
"unidad_medida": "43",
"precio_unitario": 1000.00,
"monto": 1000.00,
"indicador_facturacion": 1,
"indicador_bien_servicio": "1"
}
],
"totales": {
"monto_gravado_total": 1000.00,
"itbis1": 18,
"total_itbis": 180.00,
"monto_total": 1180.00,
"monto_gravado_i1": 1000.00,
"total_itbis1": 180.00
}
}
Archivo: ejemplos/ecf-31-minimo.json
Ejemplo completo¶
Venta a crédito con varias líneas, un ítem exento, códigos de producto y desglose por tasa.
{
"emisor": {
"rnc": "133802074"
},
"comprador": {
"rnc": "131880738",
"razon_social": "COMERCIO, SRL",
"correo": "[email protected]",
"direccion": "Av. 27 de Febrero #45, Santo Domingo"
},
"id_doc": {
"e_ncf": "E310000000002",
"fecha_vencimiento_secuencia": "31-12-2028",
"indicador_monto_gravado": 0,
"tipo_ingresos": "01",
"tipo_pago": "2",
"fecha_limite_pago": "31-12-2030",
"termino_pago": "30 dias",
"formas_pago": [
{ "forma": "4", "monto": 118000.00 }
]
},
"items": [
{
"nombre": "Zapatos de cuero",
"descripcion": "Modelo ejecutivo, tallas surtidas",
"cantidad": 150,
"unidad_medida": "6",
"precio_unitario": 550.0000,
"monto": 82500.00,
"indicador_facturacion": 1,
"indicador_bien_servicio": "1",
"codigos": [
{ "tipo": "INTERNO", "codigo": "ZAP-001" }
]
},
{
"nombre": "Vestidos",
"cantidad": 200,
"unidad_medida": "34",
"precio_unitario": 800.0000,
"monto": 160000.00,
"indicador_facturacion": 1,
"indicador_bien_servicio": "1"
},
{
"nombre": "Servicio de instalacion",
"cantidad": 1,
"unidad_medida": "43",
"precio_unitario": 5000.0000,
"monto": 5000.00,
"indicador_facturacion": 4,
"indicador_bien_servicio": "2"
}
],
"totales": {
"monto_gravado_total": 242500.00,
"monto_gravado_i1": 242500.00,
"monto_exento": 5000.00,
"itbis1": 18,
"total_itbis": 43650.00,
"total_itbis1": 43650.00,
"monto_total": 291150.00
}
}
Archivo: ejemplos/ecf-31-completo.json
Observe cómo cuadra:
monto_gravado_total 242,500.00 (82,500 + 160,000; el exento no entra)
monto_exento 5,000.00
total_itbis 43,650.00 (242,500 × 18 %)
───────────
monto_total 291,150.00
Respuesta¶
{
"status": "success",
"message": "e-CF recibido y encolado para envío a la DGII.",
"document": {
"document_id": 1234,
"ecf_type_code": "31",
"e_ncf": "E310000000001",
"identificador": "133802074E310000000001",
"track_id": null,
"status_code": 1,
"status": "received",
"status_description": "El e-CF fue recibido, validado y encolado para su envío a la DGII."
}
}
El identificador es el RNC del emisor seguido del e-NCF: con él consulta el documento y, ya aceptado, recoge su XML
firmado y su PDF (cómo se arma).
TrackID. La respuesta
202siempre traetrack_id: null: la transmisión ocurre después, en segundo plano. Al transmitirse, este tipo completo recibe su TrackID y el documento pasa ain_process_dgii(dónde aparece el TrackID).
Errores frecuentes¶
Cada mensaje llega en un 422 dentro de document.errors (y, por campo, en document.detailed_errors); la forma completa está en Cómo responde la API.
| Mensaje | Causa |
|---|---|
| El campo RNC/Cédula del comprador es obligatorio. | El 31 siempre exige identificar al comprador. |
| El monto total (…) no cuadra: debe ser monto gravado + monto exento + total ITBIS + monto de impuesto adicional. | Revise la aritmética de totales. |
| El monto gravado total (…) no coincide con la suma de los ítems gravados (…). | Está incluyendo ítems exentos (indicador 4) o no facturables (0) en el gravado. |
| El e-NCF es obligatorio (id_doc.e_ncf): la numeración la lleva cada ERP o Facturador, no esta API… | Falta id_doc.e_ncf: lo numera su sistema y viaja con cada comprobante. |
| La secuencia del e-NCF … venció el … | La fecha de vencimiento de su autorización de la DGII ya pasó. |
| Falta la fecha de vencimiento de la secuencia (id_doc.fecha_vencimiento_secuencia)… | El 31 la lleva siempre. |
| El e-NCF … no está dentro de ninguna secuencia autorizada y activa registrada… | Sólo si registró su autorización: ese número cae fuera de ella. |
| Hay ítems gravados con ITBIS, así que el indicador de monto gravado (id_doc.indicador_monto_gravado) es obligatorio: 0 si los montos de las líneas no incluyen ITBIS, 1 si lo incluyen. | Falta id_doc.indicador_monto_gravado. La DGII lo exige cuando hay ítems gravados (Formato e-CF, campo 7) y, si no viene, rechaza el comprobante con el código 176. |
| El campo fecha límite de pago es obligatorio cuando tipo de pago es 2. | Una venta a crédito siempre declara su fecha_limite_pago. |
| La fecha límite de pago (…) no puede ser anterior a la fecha de emisión, que es la de hoy (…). | id_doc.fecha_limite_pago está en el pasado. Con tipo_pago 2 (crédito) es obligatoria y tiene que ser igual o posterior a hoy. |