Saltar al contenido principal

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.

La regla de oro

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 409 ENCF_NOT_IN_REGISTERED_RANGE (o ENCF_RANGE_DISABLED si 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_REGISTERED en warnings: 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.

TiposFechaVencimientoSecuencia
31, 33, 41, 43, 44, 45, 46 y 47Obligatoria.
32 y 34No 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.code SEQUENCE_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.code SEQUENCE_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.code SEQUENCE_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.code SEQUENCE_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:

ValorSignificado
0No facturable, por ejemplo la venta de un bono de regalo. Suma en MontoNoFacturable, no en la base ni en MontoTotal.
1Gravado con ITBIS al 18 %
2Gravado con ITBIS al 16 %
3Gravado a tasa 0 %
4Exento

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, nunca 1,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 como 0: la API responde 422 en ese campo con details.code DECIMAL_FORMAT_INVALID. Solo MontoNoFacturable, MontoPeriodo y SaldoAnterior admiten signo.
  • Hasta 2 decimales en montos, impuestos y CantidadItem, y hasta 4 en PrecioUnitarioItem. El redondeo es el de la DGII: si el tercer decimal es 5 o más, sube el segundo.
  • MontoItem es cantidad × precio unitario − descuento + recargo.
  • Con IndicadorMontoGravado en 1 los 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. Con 0 los precios no incluyen el ITBIS. Los montos de DescuentosORecargos van siempre sin ITBIS.
  • Un descuento global de la Norma General 10-07 (IndicadorNorma1007 en 1) no se resta de MontoGravadoI1: se refleja en ValorPagar. Con él, IndicadorMontoGravado debe ser 1 (si no, 422 con details.code NORMA_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 en Totales.ImpuestosAdicionales.
  • ITBIS1, ITBIS2 e ITBIS3 declaran la tasa: 18, 16 y 0. Otro valor se emite con el aviso ITBIS_RATE_MISMATCH en warnings: 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 hay MontoGravadoI1 o MontoGravadoI2 mayor que cero, TotalITBIS1 o TotalITBIS2 es 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 responde 422 en ese campo con details.code TOTAL_ITBIS_REQUIRED. En la nota de crédito a más de 30 días va en 0.00 (ver Notas de débito y crédito). TotalITBIS va siempre que haya un TotalITBIS1, TotalITBIS2 o TotalITBIS3, también en 0.00 cuando todo es tasa 0 %.
  • DescuentoMonto y RecargoMonto son la suma de sus subdescuentos y subrecargos; uno en porcentaje vale precio unitario × porcentaje × cantidad. MontoPeriodo es MontoTotal + MontoNoFacturable, y ValorPagar es MontoTotal − 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 en warnings con details.code SQUARING_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 respondiendo 422.

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 006 a 039, el e-CF lleva MontoImpuestoSelectivoConsumoEspecifico, salvo en ítems a granel (unidad de medida 18). Sin él la DGII rechaza la factura, así que la API responde 422 con details.code ISC_SPECIFIC_AMOUNT_REQUIRED.
  • ZarelaFact recalcula cada monto con la fórmula de la DGII: monto de los ítems × tasa en 001 a 005 (entre 1.18 con IndicadorMontoGravado en 1, 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 aviso SQUARING_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 TasaImpuestoAdicional sea la vigente en FechaEmision: usa la tasa que envías.
  • El contrato simplificado no tiene impuestos adicionales: emite esos comprobantes con el formato JSON DGII.

Comprador​

  • RNCComprador lleva 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 RNCComprador o, si es extranjero, con IdentificadorExtranjero. Las notas 33 y 34 que modifican esa factura, también.
  • RNCComprador e IdentificadorExtranjero no 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:

  • MontoGravadoI1 con la base y ITBIS1 18, como cualquier nota gravada. Los ítems siguen con IndicadorFacturacion 1.
  • TotalITBIS1 y TotalITBIS en 0.00. No los omitas: sin TotalITBIS1 la DGII rechaza la nota y el eNCF queda usado, así que la API responde 422 TOTAL_ITBIS_REQUIRED.
  • MontoTotal sin 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 (o reference.date) no es la fecha de emisión del comprobante modificado (REFERENCED_DATE_MISMATCH). De esa fecha depende IndicadorNotaCredito.
  • 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 dice lastError y 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​

  • TotalPaginas es la cantidad de páginas de la sección Paginacion: envía los dos o ninguno. ZarelaFact no ata el XML a las páginas del PDF: el contrato simplificado nunca declara Paginacion ni TotalPaginas, aunque el PDF ocupe varias páginas. Si la envías en el JSON DGII, TotalPaginas es mayor que 1, PaginaNo va en orden desde 1 y cada página tiene 0 < NoLineaDesde ≤ NoLineaHasta, con líneas que existen y sin repetir las de una página anterior; si no, 422 con details.code PAGINATION_INVALID. Si las páginas dejan líneas sin cubrir, la respuesta trae el aviso PAGINATION_LINES_NOT_COVERED.
  • FechaLimitePago anterior a FechaEmision se emite con el aviso PAYMENT_DUE_DATE_BEFORE_ISSUE en warnings. La DGII lo deja Aceptado Condicional (1104): revisa la fecha límite de pago.
  • Una venta a crédito (TipoPago 2) lleva FechaLimitePago en todos los tipos que la tienen salvo el 47, donde es opcional. Sin ella, la API responde 422 con details.code PAYMENT_DUE_DATE_REQUIRED.

Fechas, ubicación y firma​

  • Las fechas van en DD-MM-AAAA, por ejemplo FechaEmision, y deben existir en el calendario: una fecha como 31-02-2026 en FechaEmision, FechaEntrega, FechaOrdenCompra, FechaDesde, FechaHasta, FechaEmbarque, FechaElaboracion o FechaVencimientoItem responde 422 en ese campo con details.code DATE_INVALID.
  • Provincia y municipio usan los códigos de la Tabla III de la DGII, por ejemplo 010000 y 010101.
  • FechaHoraFirma puedes 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 responde 422 en ECF.FechaHoraFirma con details.code SIGNATURE_DATE_IN_FUTURE (o SIGNATURE_DATE_INVALID si 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" }
]
}
CampoNotas
typeE31 a E47.
issueDateObligatoria 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.
issuerOpcional. 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.
encfEl eNCF que asignó tu sistema. Solo puede faltar al validar con ?validate=true.
signatureDateOpcional: 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.
sequenceExpirationDateObligatoria 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.
pricesIncludeTaxtrue 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.
paymentTypeObligatorio 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.
dueDateFecha 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.
paymentTermsTérmino de pago, hasta 15 letras, números o espacios (por ejemplo 30 dias). No existe en el 34 ni en el 43.
incomeTypeTipoIngresos, 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[].itbisRate0, 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[].indicadorFacturacionDe 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[].descriptionDescripción ampliada del ítem (DescripcionItem), hasta 1000 caracteres. El PDF imprime hasta 200 bajo el nombre; el XML la lleva completa.
lines[].quantityMayor que cero, hasta 2 decimales.
lines[].unitPriceHasta 4 decimales. Con pricesIncludeTax incluye el ITBIS.
lines[].unitMeasureCódigo de la Tabla IV de la DGII, de 1 a 62 (por ejemplo 43 = Unidad). El PDF la imprime en palabras.
lines[].itemKindObligatorio: good (bien) o service (servicio). En el 47 cada línea es un servicio y puedes omitirlo.
lines[].discountAmount o discountPercentDescuento de la línea, uno de los dos. No existe en el 43 ni en el 47.
lines[].retentionSolo 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 globalDiscountPercentDescuento 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 globalSurchargePercentRecargo 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 transportVer Datos opcionales del XML.
currency y exchangeRateMoneda de los montos y su tasa de cambio a pesos. Ver Otra moneda.
deferredSendtrue solo si la DGII te autorizó el envío diferido. Ver Envío diferido en el contrato simplificado.
referencePara 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 responde 422 antes de registrar el documento y el eNCF sigue libre.
  • Las propiedades que no existen se rechazan con 422 y details.code UNKNOWN_FIELD, como en el resto de la API: una errata como itbis_rate no 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 422 con 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 es 422 con 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.rnc o buyer.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:

CampoCálculoEn el ejemplo
MontoGravadoI1, I2, I3Suma de los MontoItem de la tasa dividida entre 1.18, 1.16 o 1, menos descuentos y más recargos globales118 ÷ 1.18 = 100.00
TotalITBIS1, 2, 3Base de la tasa × 18 %, 16 % o 0 %100.00 × 18 % = 18.00
MontoExentoSuma de los ítems exentos, sin dividir—
MontoTotalBases + exento + ITBIS118.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, MontoTotal puede 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: MontoTotal es 100.01. Es el total que espera la DGII; cobra el que muestra el comprobante.
  • El descuento de una línea (discountAmount o discountPercent) 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 responde 422 con details.code GLOBAL_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, true responde 422.
  • 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.

CampoNodo del XMLFormatoNo existe en
purchaseOrderNumberComprador/NumeroOrdenCompraHasta 20 caracteres41, 43 y 47
purchaseOrderDateComprador/FechaOrdenCompraFecha DD-MM-AAAA o AAAA-MM-DD41, 43 y 47
internalInvoiceNumberEmisor/NumeroFacturaInternaHasta 20 caracteres—
internalOrderNumberEmisor/NumeroPedidoInternoSolo dígitos, hasta 20—
sellerCodeEmisor/CodigoVendedorHasta 60 caracteres41, 43 y 47
buyer.contactComprador/ContactoCompradorHasta 80 caracteres43 y 47
buyer.emailComprador/CorreoCompradorCorreo de hasta 80 caracteres; el XSD no admite _43 y 47
buyer.internalCodeComprador/CodigoInternoCompradorHasta 20 caracteres43 y 47
delivery.dateComprador/FechaEntregaFecha DD-MM-AAAA o AAAA-MM-DD41, 43 y 47
delivery.contactComprador/ContactoEntregaHasta 100 caracteres41, 43 y 47
delivery.addressComprador/DireccionEntregaHasta 100 caracteres41, 43 y 47
transport.driverTransporte/ConductorHasta 20 caracteres41, 43 y 47
transport.documentTransporte/DocumentoTransporteSolo dígitos, hasta 2041, 43 y 47
transport.vehicleNumberTransporte/FichaHasta 10 caracteres41, 43 y 47
transport.plateTransporte/PlacaHasta 7 caracteres41, 43 y 47
transport.routeTransporte/RutaTransporteHasta 20 caracteres41, 43 y 47
transport.zoneTransporte/ZonaTransporteHasta 20 caracteres41, 43 y 47
transport.deliveryNoteNumberTransporte/NumeroAlbaranHasta 20 caracteres41, 43 y 47
lines[].descriptionItem/DescripcionItemHasta 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.

Para casos complejos usa el formato DGII

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​

DocumentoPara qué sirve
Formato e-CF v1.0Describe cada campo del comprobante.
Formato Resumen de Factura de Consumo v1.0El resumen (RFCE) de las facturas de consumo menores a RD$250,000. ZarelaFact lo genera por ti.
Formato Anulación de e-NCF v1.0La anulación de secuencias (ANECF).
Formato Aprobación Comercial v1.0La aceptación o el rechazo comercial (ACECF).
Formato Acuse de Recibo v1.0El 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.