Formato JSON de e-CF
Envías cada comprobante como JSON. ZarelaFact lo ordena, lo valida contra el XSD oficial de su tipo, lo convierte a XML y lo firma por ti.
El JSON usa los mismos nombres de campo y la misma estructura que el XML de la DGII, dentro de un objeto ECF. Si sabes qué campo va en el XML, ya sabes cómo va en el JSON.
La descripción de cada campo está en el Formato del Comprobante Fiscal Electrónico (e-CF) v1.0 que publica la DGII.
Ejemplo
Factura de crédito fiscal (31) a crédito, con dos líneas gravadas al 18 % y un descuento del 5 % en la primera:
{
"ECF": {
"Encabezado": {
"Version": "1.0",
"IdDoc": {
"TipoeCF": 31,
"eNCF": "E310000000010",
"FechaVencimientoSecuencia": "31-12-2028",
"IndicadorMontoGravado": 0,
"TipoIngresos": "01",
"TipoPago": 2,
"FechaLimitePago": "31-10-2026"
},
"Emisor": {
"RNCEmisor": "{{RNC}}",
"RazonSocialEmisor": "{{RAZON_SOCIAL}}",
"DireccionEmisor": "{{DIRECCION_EMISOR}}",
"FechaEmision": "01-10-2026"
},
"Comprador": {
"RNCComprador": "{{RNC_COMPRADOR}}",
"RazonSocialComprador": "{{RAZON_SOCIAL_COMPRADOR}}"
},
"Totales": {
"MontoGravadoTotal": 3825.00,
"MontoGravadoI1": 3825.00,
"ITBIS1": 18,
"TotalITBIS": 688.50,
"TotalITBIS1": 688.50,
"MontoTotal": 4513.50
}
},
"DetallesItems": {
"Item": [
{
"NumeroLinea": 1,
"IndicadorFacturacion": 1,
"NombreItem": "Resma de papel carta",
"IndicadorBienoServicio": 1,
"CantidadItem": 10,
"UnidadMedida": 43,
"PrecioUnitarioItem": 350.00,
"DescuentoMonto": 175.00,
"TablaSubDescuento": {
"SubDescuento": [
{
"TipoSubDescuento": "%",
"SubDescuentoPorcentaje": 5.00,
"MontoSubDescuento": 175.00
}
]
},
"MontoItem": 3325.00
},
{
"NumeroLinea": 2,
"IndicadorFacturacion": 1,
"NombreItem": "Servicio de entrega",
"IndicadorBienoServicio": 2,
"CantidadItem": 1,
"UnidadMedida": 43,
"PrecioUnitarioItem": 500.00,
"MontoItem": 500.00
}
]
}
}
}
Para cada tipo de comprobante tienes un ejemplo completo en Ejemplos JSON por tipo. Los datos de tu cliente ({{RNC_COMPRADOR}}, {{RAZON_SOCIAL_COMPRADOR}}…) los reemplazas tú; ver Cómo usar estos ejemplos.
Los campos que más se equivocan
eNCF
- Lo asigna tu sistema, del rango que te autorizó la DGII, y lo guarda con la venta antes de llamar a la API. ZarelaFact no reserva números.
- Tiene 13 caracteres: la letra
E, el tipo en 2 dígitos y la secuencia en 10. Por ejemplo,E310000000010. - El tipo dentro del eNCF debe coincidir con
TipoeCF. - Cada ambiente tiene sus propias secuencias, y un eNCF anulado ya no se puede emitir.
- Si registraste en tu cuenta los rangos de eNCF de ese tipo, el eNCF debe caer en uno de ellos: si no, la API responde
409ENCF_NOT_IN_REGISTERED_RANGE(oENCF_RANGE_DISABLEDsi solo cae en un rango deshabilitado) y no registra el documento, al validar y al emitir. La DGII rechaza un eNCF que no autorizó, y en el resumen de una factura de consumo de menos de RD$250,000 lo acepta condicional. Un rango cerrado porque registraste el siguiente sigue valiendo. - Si no registraste ningún rango de ese tipo, el documento se emite y la respuesta trae el aviso
ENCF_RANGE_NOT_REGISTEREDenwarnings: ZarelaFact no puede comprobar la secuencia.
FechaVencimientoSecuencia
Es la fecha de vencimiento del rango de eNCF que te autorizó la DGII, en formato DD-MM-AAAA. ZarelaFact nunca la completa ni la inventa.
| Tipos | FechaVencimientoSecuencia |
|---|---|
| 31, 33, 41, 43, 44, 45, 46 y 47 | Obligatoria. |
| 32 y 34 | No existe en su XSD: no la envíes. |
Si falta, no es una fecha real (por ejemplo 31-02-2028) o la envías en un 32 o un 34, la API responde 422 con el campo ECF.Encabezado.IdDoc.FechaVencimientoSecuencia. En el 32 y el 34 el 422 trae details.code SEQUENCE_EXPIRATION_DATE_NOT_APPLICABLE.
También responde 422 en ese campo si:
- Es anterior a
FechaEmision: el eNCF ya estaba vencido el día de la venta y la DGII lo rechaza (details.codeSEQUENCE_EXPIRED_AT_ISSUE_DATE). El último día de vigencia todavía se puede emitir. - Registraste en tu cuenta el rango de eNCF que contiene ese número, con su vencimiento, y la fecha no es esa (
details.codeSEQUENCE_EXPIRATION_RANGE_MISMATCH). La DGII valida la fecha contra la que autorizó: corrige la de tu sistema o la del rango registrado. Si no registraste el rango, no se compara.
Y trae un aviso en warnings, sin bloquear la emisión, si:
- Es posterior al 31 de diciembre del año siguiente al de
FechaEmision(details.codeSEQUENCE_EXPIRATION_BEYOND_LEGAL_MAX): una secuencia vence a más tardar el 31 de diciembre del año siguiente a su autorización. Revisa que sea la fecha que te dio la DGII. - La secuencia estaba vigente al emitir pero ya venció el día del envío, por ejemplo en contingencia (
details.codeSEQUENCE_EXPIRED_AT_SEND_DATE): la DGII rechaza un eNCF vencido a la fecha de envío.
El PDF imprime la fecha de vencimiento en DD-MM-AAAA en todos los tipos menos el 32 y el 34: la DGII no la admite en la representación impresa de esos dos tipos.
IndicadorFacturacion
Va en cada ítem e indica cómo se trata el ITBIS:
| Valor | Significado |
|---|---|
0 | No facturable, por ejemplo la venta de un bono de regalo. Suma en MontoNoFacturable, no en la base ni en MontoTotal. |
1 | Gravado con ITBIS al 18 % |
2 | Gravado con ITBIS al 16 % |
3 | Gravado a tasa 0 % |
4 | Exento |
Los tipos 43, 44 y 47 solo admiten ítems exentos (4), y el 46 solo tasa 0 % (3).
Montos
- Punto como separador decimal y sin separador de miles:
1500.50, nunca1,500.50. Puede ir como texto ("1500.50") o como número JSON (1500.5). Un monto, cantidad, precio o tasa con coma o con texto no se corrige ni se toma como0: la API responde422en ese campo condetails.codeDECIMAL_FORMAT_INVALID. SoloMontoNoFacturable,MontoPeriodoySaldoAnterioradmiten signo. - Hasta 2 decimales en montos, impuestos y
CantidadItem, y hasta 4 enPrecioUnitarioItem. El redondeo es el de la DGII: si el tercer decimal es 5 o más, sube el segundo. MontoItemes cantidad × precio unitario − descuento + recargo.- Con
IndicadorMontoGravadoen1los precios incluyen el ITBIS: la base de cada tasa es la suma de sus ítems dividida entre 1.18 o 1.16, y a esa base se le restan los descuentos y se le suman los recargos globales. Con0los precios no incluyen el ITBIS. Los montos deDescuentosORecargosvan siempre sin ITBIS. - Un descuento global de la Norma General 10-07 (
IndicadorNorma1007en1) no se resta deMontoGravadoI1: se refleja enValorPagar. Con él,IndicadorMontoGravadodebe ser1(si no,422condetails.codeNORMA_1007_REQUIRES_ITBIS_INCLUDED) y la base de la tasa 18 % es la suma de esos ítems dividida entre 1.18 más las tasas de los impuestos adicionales 002 y 004 que lleve cada ítem (por ejemplo 1.30 con CDT 2 % y telecomunicaciones 10 %), declaradas enTotales.ImpuestosAdicionales. ITBIS1,ITBIS2eITBIS3declaran la tasa:18,16y0. Otro valor se emite con el avisoITBIS_RATE_MISMATCHenwarnings: la DGII lo acepta, pero la tasa debe coincidir con su indicador.- El ITBIS de cada tasa es su base por la tasa (
MontoGravadoI1× 18 %), sobre la base total y no línea a línea. Si hayMontoGravadoI1oMontoGravadoI2mayor que cero,TotalITBIS1oTotalITBIS2es obligatorio: sin él la DGII rechaza el e-CF («El campo TotalITBIS1 del área Totales de la sección Encabezado no es válido») y el eNCF queda usado, así que la API responde422en ese campo condetails.codeTOTAL_ITBIS_REQUIRED. En la nota de crédito a más de 30 días va en0.00(ver Notas de débito y crédito).TotalITBISva siempre que haya unTotalITBIS1,TotalITBIS2oTotalITBIS3, también en0.00cuando todo es tasa 0 %. DescuentoMontoyRecargoMontoson la suma de sus subdescuentos y subrecargos; uno en porcentaje vale precio unitario × porcentaje × cantidad.MontoPeriodoesMontoTotal+MontoNoFacturable, yValorPagaresMontoTotal−MontoAvancePago±SaldoAnterior(menos los descuentos de la Norma 10-07). Si no cuadran, el aviso es el mismo de la línea siguiente.- Los totales deben cuadrar con el detalle. La DGII admite RD$1 de diferencia por línea entre cantidad × precio y
MontoItem, y en los totales RD$1 por cada línea del detalle. Si la diferencia es mayor, la DGII no rechaza el comprobante: lo deja Aceptado Condicional. Por eso ZarelaFact lo emite igual y la respuesta trae un aviso enwarningscondetails.codeSQUARING_ABOVE_DGII_TOLERANCE, el campo y los montos declarado y esperado. Corrige tu cálculo: un Aceptado Condicional queda así en la DGII. Los errores de formato (decimales, separador de miles, campos obligatorios) siguen respondiendo422.
Otra moneda en el JSON DGII
Si el e-CF trae la sección OtraMoneda, TipoCambio es mayor que cero (si no, 422 con details.code EXCHANGE_RATE_INVALID). Sus totales se revisan contra la suma de sus partes y contra los totales en pesos divididos entre TipoCambio, con la tolerancia de la DGII: una diferencia mayor se emite con el aviso SQUARING_ABOVE_DGII_TOLERANCE. Los montos en otra moneda de cada ítem (OtraMonedaDetalle) no se comparan con TipoCambio.
Impuestos adicionales
Propina legal, CDT, seguros, telecomunicaciones, primera placa (códigos 001 a 005) e ISC de alcoholes y cigarrillos (006 a 039) van en TablaImpuestoAdicional de cada ítem y en Totales.ImpuestosAdicionales, con MontoImpuestoAdicional como su suma. El ISC (006 a 039) entra además en la base del ITBIS a tasa 1.
- Con códigos
006a039, el e-CF llevaMontoImpuestoSelectivoConsumoEspecifico, salvo en ítems a granel (unidad de medida18). Sin él la DGII rechaza la factura, así que la API responde422condetails.codeISC_SPECIFIC_AMOUNT_REQUIRED. - ZarelaFact recalcula cada monto con la fórmula de la DGII: monto de los ítems × tasa en
001a005(entre 1.18 conIndicadorMontoGravadoen1, con el descuento y el recargo global repartidos por línea); tasa × grados de alcohol × cantidad de referencia × subcantidad × cantidad en el ISC específico de alcoholes; y el ad valorem desde el precio unitario de referencia. Si un monto no cuadra por encima de la tolerancia de la DGII, se emite con el avisoSQUARING_ABOVE_DGII_TOLERANCE. Si al ítem le faltan datos para la fórmula (grados, cantidad de referencia, subcantidad o precio de referencia), ese monto no se recalcula. - La tasa del ISC específico cambia cada trimestre. ZarelaFact no comprueba que
TasaImpuestoAdicionalsea la vigente enFechaEmision: usa la tasa que envías. - El contrato simplificado no tiene impuestos adicionales: emite esos comprobantes con el formato JSON DGII.
Comprador
RNCCompradorlleva 9 dígitos (RNC) u 11 (cédula), sin guiones. ZarelaFact no lo rechaza por su dígito verificador; si no aparece o no está activo en el padrón de la DGII, la respuesta trae un aviso que no bloquea.- Una factura de consumo (32) de RD$250,000 o más identifica al comprador con
RNCCompradoro, si es extranjero, conIdentificadorExtranjero. Las notas 33 y 34 que modifican esa factura, también. RNCCompradoreIdentificadorExtranjerono van juntos: con identificador extranjero, omite el RNC.
Notas de débito y crédito
En las notas 33 y 34, InformacionReferencia.CodigoModificacion solo admite 1 (anula), 2 (corrige texto) o 3 (corrige montos), y la nota de débito (33) solo el 3: con otro código la API responde 422. El 5 (referencia a una factura de consumo, solo desde una factura de crédito fiscal 31) es de los demás tipos.
En los demás tipos, InformacionReferencia solo va en la factura de crédito fiscal (31) con el código 5: NCFModificado es el eNCF de la factura de consumo (E32…) que referencias. En otro tipo, o con otro código, la API responde 422.
El código 4 (reemplazo de un comprobante de papel emitido en contingencia) no se admite en ningún tipo. Ver Contingencia: sin comprobantes de papel.
FechaNCFModificado (o reference.date) es la fecha del comprobante modificado: si es posterior a la FechaEmision de la nota, la API responde 422 (REFERENCE_DATE_AFTER_ISSUE_DATE). En la nota de crédito, IndicadorNotaCredito es 0 hasta 30 días calendario entre esas dos fechas y 1 si son más; con el contrato simplificado lo calcula ZarelaFact y en el JSON DGII, si no coincide con las fechas, la API responde 422 (CREDIT_NOTE_INDICATOR_MISMATCH).
Nota de crédito a más de 30 días: sin ITBIS
Con IndicadorNotaCredito 1 la nota va sin ITBIS. Después de 30 días, «la restitución al cliente conllevará únicamente el precio pagado sin incluir el ITBIS» y la venta conserva su ITBIS: la nota no lo rebaja. Lo dicen el Informe Técnico e-CF v1.0 (§10, versión del 16-10-2026), el Reglamento 293-11 (arts. 8 y 28), el párrafo del art. 338 del Código Tributario y las consultas de la Gerencia Legal de la DGII del 03-05-2024 y del 12-11-2025. Como emisor electrónico no envías el formato 607: lo que declara el e-CF es lo que registra la DGII.
En Totales la nota lleva:
MontoGravadoI1con la base yITBIS118, como cualquier nota gravada. Los ítems siguen conIndicadorFacturacion1.TotalITBIS1yTotalITBISen0.00. No los omitas: sinTotalITBIS1la DGII rechaza la nota y el eNCF queda usado, así que la API responde422TOTAL_ITBIS_REQUIRED.MontoTotalsin ITBIS: el precio que devuelves.
Con TotalITBIS1 en 0.00, la DGII deja la nota Aceptado Condicional con el mensaje «El campo TotalITBIS1 del área Totales de la sección Encabezado no coincide con la multiplicación de los campos de Monto Gravado 1 y ITBIS Tasa 1». Es un e-CF válido: la DGII prevé ese estado para un monto que no cuadra con su fórmula (Informe Técnico §12) y dice que «tiene validez para fines tributarios». La respuesta de ZarelaFact trae el aviso LATE_CREDIT_NOTE_WITHOUT_ITBIS en warnings.
"IdDoc": { "TipoeCF": 34, "eNCF": "E340000000002", "IndicadorNotaCredito": "1", "IndicadorMontoGravado": 0, "TipoIngresos": "01", "TipoPago": 1 },
"Totales": {
"MontoGravadoTotal": 4957.88, "MontoGravadoI1": 4957.88, "ITBIS1": 18,
"TotalITBIS": 0.00, "TotalITBIS1": 0.00, "MontoTotal": 4957.88
},
"DetallesItems": { "Item": [{ "NumeroLinea": 1, "IndicadorFacturacion": 1, "NombreItem": "Devolución de mercancía", "IndicadorBienoServicio": 1, "CantidadItem": 1, "UnidadMedida": 43, "PrecioUnitarioItem": 4957.88, "MontoItem": 4957.88 }] },
"InformacionReferencia": { "NCFModificado": "B0100000123", "FechaNCFModificado": "01-09-2026", "CodigoModificacion": "3" }
El contrato simplificado la emite así sin que hagas nada: calcula el indicador con reference.date y pone el ITBIS en 0.00. Con precios con ITBIS incluido (pricesIncludeTax), la base es el precio sin el ITBIS incluido. En otra moneda, TotalITBIS1OtraMoneda y TotalITBISOtraMoneda también van en 0.00. El PDF imprime 0.00 de ITBIS en cada línea y en los totales.
En el JSON DGII también se admite la nota con el ITBIS calculado (TotalITBIS1 = MontoGravadoI1 × 18 % y MontoTotal con ITBIS): la DGII la acepta sin observaciones y ZarelaFact la emite sin aviso. Recomendamos la forma sin ITBIS porque es la que la DGII indica por escrito. La DGII no ha publicado cómo llenar los Totales de esta nota; si quieres una respuesta vinculante para tu caso, haz una consulta técnica a la DGII.
NCFModificado (o reference.encf) tiene una de las estructuras oficiales: un NCF serie B de 11 posiciones (B0100000001), un eNCF de 13 (E310000000001) o un NCF serie A o P de 19 (A010010010100000001). Otra longitud responde 422.
La nota se emite sobre un comprobante que la DGII aceptó. Si NCFModificado (o reference.encf) es un eNCF que emitiste con ZarelaFact en el mismo ambiente y quedó rechazado por la DGII o anulado, la API responde 422 con details.code REFERENCED_ENCF_NOT_ACCEPTED y no registra la nota: la DGII la rechazaría («El eNCF modificado no ha sido emitido») y el eNCF de la nota quedaría usado. Un NCF de papel, o un eNCF que ZarelaFact no emitió, no se revisa.
Si el comprobante modificado es un eCF de tu cuenta en el mismo ambiente, la API también responde 422, al validar y al emitir, si:
- La nota es para otro comprador (
REFERENCED_BUYER_MISMATCH): las notas solo se emiten al mismo comprador del comprobante que modifican. FechaNCFModificado(oreference.date) no es la fecha de emisión del comprobante modificado (REFERENCED_DATE_MISMATCH). De esa fecha dependeIndicadorNotaCredito.- En una nota de crédito, su monto más el de las notas de crédito anteriores de ese comprobante supera su
MontoTotal(CREDIT_NOTES_EXCEED_ORIGINAL). No cuentan las notas rechazadas por la DGII o canceladas.
Y si una nota de crédito con CodigoModificacion 1 (anulación total) no cubre lo que queda del total de ese comprobante, la nota se emite con el aviso CREDIT_NOTE_CODE1_PARTIAL en warnings: si es parcial, usa el código 3. En la nota a más de 30 días sin ITBIS, lo que queda se cuenta sin el ITBIS del comprobante.
Contingencia: sin comprobantes de papel
ZarelaFact no emite e-CF que reemplazan comprobantes de papel (serie B) usados durante una contingencia: con CodigoModificacion 4 (o reference.modificationCode 4 en el contrato simplificado) la API responde 422 con details.code CONTINGENCY_PAPER_REPLACEMENT_UNSUPPORTED, en cualquier tipo y en los dos contratos, y no registra el documento.
No necesitas pasar a papel cuando la DGII no responde. Emite el e-CF igual:
- El documento queda en contingencia electrónica (
contingency) y ZarelaFact lo envía y lo reintenta solo hasta que la DGII vuelve. No lo reenvíes. - Su representación impresa lleva la leyenda de contingencia.
- Si el envío falla de forma definitiva, el documento pasa a
transmission_failed: corrige la causa que dicelastErrory reenvíalo desde el portal (sale el mismo XML firmado), o anula su eNCF con una ANECF. Un Partner no puede reenviarlo: anula su eNCF y emite con uno nuevo.
Ver Contingencia.
Retenciones
En los tipos 41 y 47, TotalITBISRetenido y TotalISRRetencion son la suma de MontoITBISRetenido y MontoISRRetenido de las líneas. En el 47 cada ítem es un servicio (IndicadorBienoServicio 2) con su MontoISRRetenido. En el 41, un ítem exento con retención lleva MontoITBISRetenido en 0, y el ISR retenido (MontoISRRetenido mayor que cero) solo va en servicios (IndicadorBienoServicio 2): en un bien la API responde 422 con details.code ISR_RETENTION_REQUIRES_SERVICE. El ITBIS retenido de una línea no puede ser mayor que el ITBIS de esa línea (422 con details.code ITBIS_RETENTION_EXCEEDS_LINE_ITBIS); retener solo una parte sí se admite. La percepción (IndicadorAgenteRetencionoPercepcion 2, TotalITBISPercepcion, TotalISRPercepcion) no está vigente según la DGII: se emite con el aviso PERCEPTION_REGIME_NOT_IN_FORCE.
En el 41 los dos totales van siempre, en 0.00 si ninguna línea retiene ese impuesto. Sin TotalITBISRetenido la DGII rechaza el comprobante (código 11160), también cuando solo retienes ISR. En el formato JSON DGII, la API responde 422 si falta TotalITBISRetenido y agrega un aviso en warnings si falta TotalISRRetencion. Con el contrato simplificado, ZarelaFact los calcula.
Envío diferido
Envía IndicadorEnvioDiferido en 1 solo si la DGII te autorizó el envío diferido (Decreto 587-24, art. 39), por ejemplo para ventas con dispositivos portátiles sin conexión. Con el indicador, el PDF lleva la leyenda «e-CF emitido en modalidad Envío Diferido, podrá ser consultado para su validez fiscal, a partir de las veinticuatro (24) horas.»
La DGII comprueba que el contribuyente esté autorizado, así que ZarelaFact también: la autorización (número y fecha que te dio la DGII) tiene que estar registrada en tu cuenta. Escríbenos con esos datos y la registramos. Sin ella, un documento con IndicadorEnvioDiferido en 1 (o deferredSend: true) responde 422 con details.code DEFERRED_SEND_NOT_AUTHORIZED y no se registra.
Paginación y fechas de pago
TotalPaginases la cantidad de páginas de la secciónPaginacion: envía los dos o ninguno. ZarelaFact no ata el XML a las páginas del PDF: el contrato simplificado nunca declaraPaginacionniTotalPaginas, aunque el PDF ocupe varias páginas. Si la envías en el JSON DGII,TotalPaginases mayor que 1,PaginaNova en orden desde 1 y cada página tiene0 < NoLineaDesde ≤ NoLineaHasta, con líneas que existen y sin repetir las de una página anterior; si no,422condetails.codePAGINATION_INVALID. Si las páginas dejan líneas sin cubrir, la respuesta trae el avisoPAGINATION_LINES_NOT_COVERED.FechaLimitePagoanterior aFechaEmisionse emite con el avisoPAYMENT_DUE_DATE_BEFORE_ISSUEenwarnings. La DGII lo deja Aceptado Condicional (1104): revisa la fecha límite de pago.- Una venta a crédito (
TipoPago2) llevaFechaLimitePagoen todos los tipos que la tienen salvo el 47, donde es opcional. Sin ella, la API responde422condetails.codePAYMENT_DUE_DATE_REQUIRED.
Fechas, ubicación y firma
- Las fechas van en
DD-MM-AAAA, por ejemploFechaEmision, y deben existir en el calendario: una fecha como31-02-2026enFechaEmision,FechaEntrega,FechaOrdenCompra,FechaDesde,FechaHasta,FechaEmbarque,FechaElaboracionoFechaVencimientoItemresponde422en ese campo condetails.codeDATE_INVALID. - Provincia y municipio usan los códigos de la Tabla III de la DGII, por ejemplo
010000y010101. FechaHoraFirmapuedes omitirla: ZarelaFact la completa. Si la envías, es la hora real de la República Dominicana (GMT-4) y no puede ser posterior a la hora actual (se admiten 2 minutos de diferencia de reloj): la DGII rechaza un e-CF firmado en el futuro, y la API responde422enECF.FechaHoraFirmacondetails.codeSIGNATURE_DATE_IN_FUTURE(oSIGNATURE_DATE_INVALIDsi no es una fecha y hora real).
Emisor
RNCEmisor debe ser el RNC de tu cuenta. ZarelaFact firma con tu certificado y responde 422 si el documento viene a nombre de otro RNC.
Si envías TablaTelefonoEmisor, va en el XML firmado: hasta 3 TelefonoEmisor con el formato 809-555-1234. Un teléfono con otro formato, o más de 3, responde 422 con details.code ISSUER_PHONE_INVALID. ZarelaFact no agrega el teléfono de tu perfil y el PDF no lo imprime.
Marcadores
Para probar rápido puedes escribir marcadores en lugar de los datos de tu cuenta: ZarelaFact cambia {{RNC}}, {{RAZON_SOCIAL}}, {{NOMBRE_COMERCIAL}}, {{FECHA_EMISION}} y {{FECHA_LIMITE_PAGO}} al recibir el documento. Los ejemplos por tipo los usan.
Los datos de tu cliente no los completa ZarelaFact: {{RNC_COMPRADOR}}, {{RAZON_SOCIAL_COMPRADOR}}, {{ID_EXTRANJERO_COMPRADOR}} y los demás marcadores del ejemplo por tipo los reemplazas tú. En el contrato simplificado también están {{CONTACTO_COMPRADOR}}, {{CORREO_COMPRADOR}}, {{CONTACTO_ENTREGA}}, {{DIRECCION_ENTREGA}} y {{NOMBRE_CONDUCTOR}}. Si alguno queda, la API responde 422 con UNRESOLVED_PLACEHOLDER. {{DIRECCION_EMISOR}} lo toma tu perfil si ya tiene la dirección de tu empresa.
Contrato simplificado (opcional)
Si tu sistema es sencillo, puedes enviar un JSON más corto y ZarelaFact lo expande al formato de la DGII: calcula totales e impuestos y arma las secciones. Los datos fiscales los decides tú: ZarelaFact no asume la fecha, la forma de pago, el tipo de ingreso, la tasa de ITBIS ni si cada línea es bien o servicio.
{
"type": "E31",
"encf": "E310000000011",
"sequenceExpirationDate": "31-12-2028",
"issueDate": "2026-10-01T10:30:00-04:00",
"issuer": {
"rnc": "{{RNC}}",
"legalName": "{{RAZON_SOCIAL}}",
"address": "{{DIRECCION_EMISOR}}",
"province": "010000",
"municipality": "010101"
},
"buyer": { "rnc": "{{RNC_COMPRADOR}}", "name": "{{RAZON_SOCIAL_COMPRADOR}}" },
"paymentType": "credit",
"dueDate": "2026-10-31T10:30:00-04:00",
"incomeType": "01",
"lines": [
{ "name": "Servicio de soporte", "quantity": 2, "unitPrice": 1000, "itbisRate": 18, "itemKind": "service" }
]
}
| Campo | Notas |
|---|---|
type | E31 a E47. |
issueDate | Obligatoria en todos los tipos: fecha de emisión, como fecha o fecha-hora ISO (2026-10-01T10:30:00-04:00) o DD-MM-AAAA. |
issuer | Opcional. Lo que falte (razón social, dirección y los códigos de provincia y municipio de la Tabla III de la DGII) se completa con los datos de tu empresa en el portal, igual al validar que al emitir. Si lo envías, el RNC debe ser el de tu cuenta. La dirección es obligatoria: si tu perfil no la tiene, envía issuer.address; ZarelaFact nunca la rellena con un texto genérico y, sin ella, responde 422 en issuer.address. issuer.branch (Sucursal) solo va en el e-CF si lo envías: ZarelaFact no pone una sucursal por omisión. issuer.phone (un texto o una lista de hasta 3, con el formato 809-555-1234) va en el e-CF como TablaTelefonoEmisor; con otro formato responde 422 con details.code ISSUER_PHONE_INVALID. El teléfono de tu perfil no se agrega. |
encf | El eNCF que asignó tu sistema. Solo puede faltar al validar con ?validate=true. |
signatureDate | Opcional: fecha y hora de la firma (FechaHoraFirma). Sin ella ZarelaFact usa la hora de la firma. Si la envías, no puede ser posterior a la hora actual de RD (margen de 2 minutos): si no, 422 en signatureDate con details.code SIGNATURE_DATE_IN_FUTURE. |
sequenceExpirationDate | Obligatoria en los mismos tipos que FechaVencimientoSecuencia. Acepta DD-MM-AAAA o AAAA-MM-DD. En el 32 y el 34 no existe: si la envías, no se incluye en el XML ni en el PDF y la respuesta trae un aviso en warnings con details.code SEQUENCE_EXPIRATION_DATE_NOT_APPLICABLE. |
buyer | { "rnc", "foreignId", "name", "address", "contact", "email", "internalCode" }. rnc admite guiones y espacios (001-1234567-8): ZarelaFact lo envía solo con dígitos y comprueba que tenga 9 u 11, sin rechazarlo por el dígito verificador. foreignId identifica a un comprador extranjero; con él no se envía el RNC, y no existe en los tipos 31, 41 y 45. El 43 no lleva comprador. contact, email e internalCode son datos opcionales del XML. |
pricesIncludeTax | true si los precios de las líneas incluyen el ITBIS. Ver Precios con ITBIS incluido. Sin el campo, o en false, los precios no lo incluyen. |
paymentType | Obligatorio en todos los tipos (todos llevan TipoPago): cash (contado), card (contado con tarjeta: TipoPago 1 y FormaPago 3), credit (crédito) o free (entrega gratuita, TipoPago 3). En el 34 y el 43, que no tienen forma de pago, card queda como contado y la respuesta trae un aviso. |
dueDate | Fecha límite de pago: solo con credit y obligatoria con credit (salvo en el 47, donde es opcional; sin ella, 422 con details.code PAYMENT_DUE_DATE_REQUIRED). Si es anterior a issueDate, se emite con el aviso PAYMENT_DUE_DATE_BEFORE_ISSUE (la DGII lo deja Aceptado Condicional). No existe en el 43. |
paymentTerms | Término de pago, hasta 15 letras, números o espacios (por ejemplo 30 dias). No existe en el 34 ni en el 43. |
incomeType | TipoIngresos, de 01 a 06 (01 = ingresos por operaciones). Obligatorio en los tipos que lo tienen (31, 32, 33, 34, 44, 45 y 46); no existe en el 41, el 43 ni el 47. |
lines[].itbisRate | 0, 16 o 18, como número. Cada línea lleva itbisRate o indicadorFacturacion (obligatorio, salvo en el 43, 44, 46 y 47, donde la DGII fija el indicador). Con zeroTaxMode eliges si la tasa 0 es exenta (exempt) o gravada a 0 % (taxedZero). |
lines[].indicadorFacturacion | De 1 a 4, en lugar de itbisRate o junto con ella. Si envías los dos, deben coincidir: 1 = 18, 2 = 16, 3 y 4 = 0. |
lines[].description | Descripción ampliada del ítem (DescripcionItem), hasta 1000 caracteres. El PDF imprime hasta 200 bajo el nombre; el XML la lleva completa. |
lines[].quantity | Mayor que cero, hasta 2 decimales. |
lines[].unitPrice | Hasta 4 decimales. Con pricesIncludeTax incluye el ITBIS. |
lines[].unitMeasure | Código de la Tabla IV de la DGII, de 1 a 62 (por ejemplo 43 = Unidad). El PDF la imprime en palabras. |
lines[].itemKind | Obligatorio: good (bien) o service (servicio). En el 47 cada línea es un servicio y puedes omitirlo. |
lines[].discountAmount o discountPercent | Descuento de la línea, uno de los dos. No existe en el 43 ni en el 47. |
lines[].retention | Solo en el 41 y el 47: { "itbisAmount", "isrAmount" }. En el 47, isrAmount es obligatorio en cada línea y los ítems son servicios. En el 41, isrAmount mayor que cero solo en líneas service, e itbisAmount no mayor que el ITBIS de la línea. agentIndicator 2 (percepción) se emite con el aviso PERCEPTION_REGIME_NOT_IN_FORCE. ZarelaFact suma las retenciones en TotalITBISRetenido y TotalISRRetencion; en el 41 los dos van siempre, en 0.00 si no se retiene ese impuesto. |
globalDiscountAmount o globalDiscountPercent | Descuento global, uno de los dos. Con ítems de distintas tasas se declara como porcentaje, una fila por tasa, sin cambiar el monto. No existe en el 43 ni en el 47. |
globalSurchargeAmount o globalSurchargePercent | Recargo global (TipoAjuste R), uno de los dos. Se suma a la base de cada tasa y se declara igual que el descuento: una fila por tasa, en porcentaje si hay varias tasas. El porcentaje se calcula sobre la suma de las líneas, igual que el del descuento. No existe en el 43 ni en el 47. No lo uses para la propina legal: es un impuesto adicional (código 001) y va en el formato DGII. |
purchaseOrderNumber, purchaseOrderDate, internalInvoiceNumber, internalOrderNumber, sellerCode, delivery y transport | Ver Datos opcionales del XML. |
currency y exchangeRate | Moneda de los montos y su tasa de cambio a pesos. Ver Otra moneda. |
deferredSend | true solo si la DGII te autorizó el envío diferido. Ver Envío diferido en el contrato simplificado. |
reference | Para las notas 33 y 34: { "encf", "date", "modificationCode", "reason" }. reason (RazonModificacion, el motivo de la nota) es obligatorio y admite hasta 90 caracteres: ZarelaFact no escribe uno por ti. En la nota de crédito modificationCode es obligatorio (1, 2 o 3); en la de débito solo vale 3 y se asume si lo omites. En los demás tipos la API responde 422; modificationCode 4 responde 422 con details.code CONTINGENCY_PAPER_REPLACEMENT_UNSUPPORTED (ver Contingencia: sin comprobantes de papel). |
Reglas del contrato simplificado:
- Se valida al emitir igual que con
?validate=true: estructura, cálculos, cuadre y XSD oficial. Si algo falla, la emisión responde422antes de registrar el documento y el eNCF sigue libre. - Las propiedades que no existen se rechazan con
422ydetails.codeUNKNOWN_FIELD, como en el resto de la API: una errata comoitbis_rateno cambia el comprobante sin avisar. - Nada se cambia en silencio. Una tasa inválida, un indicador que no coincide con la tasa, un código de unidad que no existe o un campo que el tipo no admite responden
422con el campo exacto. - Nada se asume. Si falta
issueDate,paymentType,incomeType(en los tipos que lo tienen), la tasa o el indicador de una línea,itemKind, la dirección del emisor o el motivo de una nota, la respuesta es422con el campo que falta. - Los textos respetan los largos del XSD (150 caracteres la razón social, 100 la dirección, 80 el nombre de cada línea) y no admiten caracteres de control ni textos de solo espacios.
- Una factura de consumo de RD$250,000 o más necesita
buyer.rncobuyer.foreignId, y también las notas 33 y 34 que la modifican.
Precios con ITBIS incluido
Si tu punto de venta guarda los precios con el ITBIS incluido, envía "pricesIncludeTax": true. ZarelaFact emite IndicadorMontoGravado en 1 y deja los precios y montos de las líneas tal como los enviaste:
{
"type": "E32",
"encf": "E320000000013",
"issueDate": "2026-10-01T10:30:00-04:00",
"issuer": {
"rnc": "{{RNC}}",
"legalName": "{{RAZON_SOCIAL}}",
"address": "{{DIRECCION_EMISOR}}",
"province": "010000",
"municipality": "010101"
},
"buyer": { "name": "CONSUMIDOR FINAL" },
"paymentType": "cash",
"incomeType": "01",
"pricesIncludeTax": true,
"lines": [
{ "name": "Refresco", "quantity": 1, "unitPrice": 118, "itbisRate": 18, "itemKind": "good" }
]
}
Los totales se calculan como los recalcula la DGII:
| Campo | C álculo | En el ejemplo |
|---|---|---|
MontoGravadoI1, I2, I3 | Suma de los MontoItem de la tasa dividida entre 1.18, 1.16 o 1, menos descuentos y más recargos globales | 118 ÷ 1.18 = 100.00 |
TotalITBIS1, 2, 3 | Base de la tasa × 18 %, 16 % o 0 % | 100.00 × 18 % = 18.00 |
MontoExento | Suma de los ítems exentos, sin dividir | — |
MontoTotal | Bases + exento + ITBIS | 118.00 |
- Cada división y cada ITBIS se redondea a 2 decimales con la regla de la DGII: si el tercer decimal es 5 o más, sube el segundo.
- Por ese redondeo,
MontoTotalpuede diferir en un centavo de la suma de tus precios. Por ejemplo, RD$100.00 con ITBIS da una base de 84.75 e ITBIS de 15.26:MontoTotales 100.01. Es el total que espera la DGII; cobra el que muestra el comprobante. - El descuento de una línea (
discountAmountodiscountPercent) también incluye el ITBIS. - El descuento y el recargo globales van en porcentaje (
globalDiscountPercent,globalSurchargePercent) y se aplican a la base sin ITBIS. Con un monto fijo, la API responde422condetails.codeGLOBAL_AMOUNT_WITH_PRICES_INCLUDE_TAX, porque no se puede saber si el monto incluye el ITBIS. - Existe en los tipos 31, 32, 33, 34, 41 y 45. En el 43, 44, 46 y 47, cuyo XSD no tiene
IndicadorMontoGravado,trueresponde422. - Si ninguna línea está gravada no se emite
IndicadorMontoGravado: no hay ITBIS que incluir. - El PDF imprime en cada línea el ITBIS incluido en su monto.
Datos opcionales del XML
Estos campos agregan al e-CF nodos opcionales del XSD de la DGII. Cada valor se valida con el largo y el formato que fija el XSD. Si el tipo no tiene ese nodo, la API responde 422 en el campo: nunca lo omite en silencio.
| Campo | Nodo del XML | Formato | No existe en |
|---|---|---|---|
purchaseOrderNumber | Comprador/NumeroOrdenCompra | Hasta 20 caracteres | 41, 43 y 47 |
purchaseOrderDate | Comprador/FechaOrdenCompra | Fecha DD-MM-AAAA o AAAA-MM-DD | 41, 43 y 47 |
internalInvoiceNumber | Emisor/NumeroFacturaInterna | Hasta 20 caracteres | — |
internalOrderNumber | Emisor/NumeroPedidoInterno | Solo dígitos, hasta 20 | — |
sellerCode | Emisor/CodigoVendedor | Hasta 60 caracteres | 41, 43 y 47 |
buyer.contact | Comprador/ContactoComprador | Hasta 80 caracteres | 43 y 47 |
buyer.email | Comprador/CorreoComprador | Correo de hasta 80 caracteres; el XSD no admite _ | 43 y 47 |
buyer.internalCode | Comprador/CodigoInternoComprador | Hasta 20 caracteres | 43 y 47 |
delivery.date | Comprador/FechaEntrega | Fecha DD-MM-AAAA o AAAA-MM-DD | 41, 43 y 47 |
delivery.contact | Comprador/ContactoEntrega | Hasta 100 caracteres | 41, 43 y 47 |
delivery.address | Comprador/DireccionEntrega | Hasta 100 caracteres | 41, 43 y 47 |
transport.driver | Transporte/Conductor | Hasta 20 caracteres | 41, 43 y 47 |
transport.document | Transporte/DocumentoTransporte | Solo dígitos, hasta 20 | 41, 43 y 47 |
transport.vehicleNumber | Transporte/Ficha | Hasta 10 caracteres | 41, 43 y 47 |
transport.plate | Transporte/Placa | Hasta 7 caracteres | 41, 43 y 47 |
transport.route | Transporte/RutaTransporte | Hasta 20 caracteres | 41, 43 y 47 |
transport.zone | Transporte/ZonaTransporte | Hasta 20 caracteres | 41, 43 y 47 |
transport.deliveryNoteNumber | Transporte/NumeroAlbaran | Hasta 20 caracteres | 41, 43 y 47 |
lines[].description | Item/DescripcionItem | Hasta 1000 caracteres | — |
Las fechas salen en el XML como DD-MM-AAAA y los textos sin espacios al inicio ni al final. En el 43, que no tiene comprador, buyer no se incluye y la respuesta trae un aviso.
{
"type": "E31",
"encf": "E310000000014",
"sequenceExpirationDate": "31-12-2028",
"issueDate": "2026-10-01T10:30:00-04:00",
"issuer": {
"rnc": "{{RNC}}",
"legalName": "{{RAZON_SOCIAL}}",
"address": "{{DIRECCION_EMISOR}}",
"province": "010000",
"municipality": "010101"
},
"buyer": {
"rnc": "{{RNC_COMPRADOR}}",
"name": "{{RAZON_SOCIAL_COMPRADOR}}",
"contact": "{{CONTACTO_COMPRADOR}}",
"email": "{{CORREO_COMPRADOR}}",
"internalCode": "CLI-10633440"
},
"paymentType": "credit",
"dueDate": "2026-10-31",
"incomeType": "01",
"purchaseOrderNumber": "OC-4500352238",
"purchaseOrderDate": "2026-09-28",
"internalInvoiceNumber": "FAC-2026-000123",
"sellerCode": "VEND-07",
"delivery": { "date": "2026-10-03", "contact": "{{CONTACTO_ENTREGA}}", "address": "{{DIRECCION_ENTREGA}}" },
"transport": { "driver": "{{NOMBRE_CONDUCTOR}}", "plate": "A639689", "deliveryNoteNumber": "3634258" },
"globalSurchargePercent": 5,
"lines": [
{
"name": "Resma de papel carta",
"description": "Papel bond 75 g, caja de 10 resmas",
"quantity": 10,
"unitPrice": 350,
"unitMeasure": 43,
"itbisRate": 18,
"itemKind": "good"
}
]
}
El número de orden de compra va en el comprador (NumeroOrdenCompra). La sección InformacionesAdicionales del XSD reúne datos de embarque y exportación (contenedor, pesos, bultos, puertos): para enviarla usa el formato DGII.
Otra moneda
Con currency (código de la Tabla II de la DGII, por ejemplo USD o EUR) los montos del documento están en esa moneda y exchangeRate es obligatorio: cuántos pesos vale una unidad, con hasta 4 decimales.
{
"type": "E31",
"encf": "E310000000012",
"sequenceExpirationDate": "31-12-2028",
"issueDate": "2026-10-01T10:30:00-04:00",
"issuer": {
"rnc": "{{RNC}}",
"legalName": "{{RAZON_SOCIAL}}",
"address": "{{DIRECCION_EMISOR}}",
"province": "010000",
"municipality": "010101"
},
"buyer": { "rnc": "{{RNC_COMPRADOR}}", "name": "{{RAZON_SOCIAL_COMPRADOR}}" },
"paymentType": "cash",
"incomeType": "01",
"currency": "USD",
"exchangeRate": 58.5,
"lines": [
{ "name": "Consultoría", "quantity": 10, "unitPrice": 120, "itbisRate": 18, "itemKind": "service" }
]
}
ZarelaFact convierte los montos a pesos, porque la DGII recibe el e-CF en pesos, y agrega las secciones OtraMoneda y OtraMonedaDetalle con los montos en la otra moneda (los totales en pesos divididos entre la tasa). Sin currency, o con DOP, los montos son pesos y exchangeRate no se admite.
Envío diferido en el contrato simplificado
IndicadorEnvioDiferido solo sale si tu cuenta tiene registrada la autorización de envío diferido de la DGII: entonces va en todos los documentos de los tipos que lo tienen, y "deferredSend": false lo quita de uno. Sin la autorización registrada, "deferredSend": true responde 422 con details.code DEFERRED_SEND_NOT_AUTHORIZED. No existe en los tipos 41, 43 y 47.
El contrato simplificado no genera impuestos adicionales (ISC, propina), recargos por línea, ítems no facturables, varias formas de pago, Paginacion, InformacionesAdicionales (embarque y exportación), ni los datos de exportación de Transporte (vía, países, transportista). Para esos casos, envía el JSON con la estructura de la DGII. Si el documento simplificado trae impuestos adicionales (ImpuestosAdicionales, additionalTaxes o lines[].TablaImpuestoAdicional), varias formas de pago (TablaFormasPago, payments o paymentType como lista), InformacionesAdicionales o Paginacion, la API no los omite: responde 422 en ese campo con details.code SIMPLIFIED_CONTRACT_UNSUPPORTED.
Documentación oficial de la DGII
| Documento | Para qué sirve |
|---|---|
| Formato e-CF v1.0 | Describe cada campo del comprobante. |
| Formato Resumen de Factura de Consumo v1.0 | El resumen (RFCE) de las facturas de consumo menores a RD$250,000. ZarelaFact lo genera por ti. |
| Formato Anulación de e-NCF v1.0 | La anulación de secuencias (ANECF). |
| Formato Aprobación Comercial v1.0 | La aceptación o el rechazo comercial (ACECF). |
| Formato Acuse de Recibo v1.0 | El acuse de recibo (ARECF). |
XSD oficiales: 31 · 32 · 33 · 34 · 41 · 43 · 44 · 45 · 46 · 47 · RFCE · ANECF · ACECF · ARECF.
Siguiente: Envío de e-CF.