Mapeo JSON → e-CF — Easy-IMS Gateway

1. Qué hace 2. Dos clases de JSON 3. Paso a paso 4. Ejemplos canónicos 5. Campos que la DGII revisa 6. Tipos E31–E47 7. Errores y qué hacer

1. Qué hace este proceso

Un sistema de facturación (EasyIMS u otro, p. ej. AdingSoft) entrega cada factura como JSON. El gateway lo convierte al formato canónico, arma el XML del e-CF, lo valida contra el XSD de la DGII, lo firma con el certificado registrado de la empresa y, si usted marca 📤 Enviar a la DGII, lo envía y muestra la respuesta (Aceptado / Rechazado y el motivo). Sin esa casilla todo es una prueba: no se envía nada.

2. Dos clases de JSON

Clase	Qué es	Qué elegir en «Plantilla JSON / formato»
Canónico	El formato propio del gateway: el mismo que envía EasyIMS (`tipo_ecf`, `emisor`, `comprador`, `lineas`, `totales`…).	Canónico — formato EasyIMS (sin mapeo), o la plantilla CANONICO.
De un tercero	El JSON tal como lo produce otro sistema (AdingSoft: `ncf`, `invoicedetail`, `Tax`…).	Su plantilla (p. ej. ADINGSOFT): dice qué campo suyo va a cada campo canónico.

⚠️ Si pega el JSON de un tercero con «Canónico» elegido, el XSD falla (p. ej. «Missing child element RNCComprador / Item»): ese JSON no tiene los nombres canónicos. Elija su plantilla.

3. Paso a paso en el Mapeo JSON

Empresa: la que emite (firma con su certificado registrado en el gateway). Solo empresas en modo de prueba (TESTECF, CERTECF o simulador): si la empresa está en PRODUCCIÓN, todos los campos quedan bloqueados 🔒 y el gateway rechaza firmar o enviar desde aquí. Los comprobantes reales salen del sistema de la empresa.
Plantilla JSON / formato: según la clase de JSON (punto 2).
Sustituir con los datos de la empresa (recomendado): pone a la empresa como emisor (RNC, razón social, dirección), propone el próximo e-NCF y el vencimiento de la secuencia. El cliente, las líneas y los totales quedan como vienen en el JSON. Revise ambos campos antes de procesar.
Pegue el JSON de entrada (o elija una muestra de la plantilla).
Firmar con: «El certificado registrado de la empresa elegida».
Marque 📤 Enviar a la DGII solo cuando quiera enviarlo de verdad, y pulse ▶ Procesar.
Siga los 6 pasos de arriba: 1 Leer · 2 Mapear · 3 Generar XML · 4 Validar XSD · 5 Firmar · 6 Enviar. Uno en rojo dice qué falló; la caja «Salida» trae el detalle y la respuesta de la DGII.

4. Ejemplos canónicos (plantilla CANONICO)

En 🧩 Plantillas JSON elija CANONICO en la lista de incluidas y pulse Importar incluida (una sola vez). Trae un ejemplo válido (pasa el XSD) de cada tipo:

Muestra	Montos de las líneas	IndicadorMontoGravado
`canonico_E31` … `canonico_E47`	Sin ITBIS (el ITBIS va aparte)	0
`canonico_E31T`, `E32T`, `E33T`, `E34T`, `E41T`, `E45T`	Con ITBIS incluido	1

Para usar uno: ábralo en la plantilla, cópielo, en el Mapeo JSON elija Canónico, péguelo, marque Sustituir y procese. Los datos son ficticios: para enviarlo a la DGII ponga un RNC de comprador real, y en 33/34 el e-NCF de un comprobante aceptado en modified_reference.ncf_modificado.

5. Los campos que la DGII revisa (y que más rechazos causan)

Campo	Regla
e-NCF	Un número por comprobante. EasyIMS y el Mapeo JSON comparten la numeración de cada empresa: el gateway registra todo lo que se envía y EasyIMS salta los números ya usados desde el Mapeo JSON. Use el sugerido.
Vencimiento de la secuencia (`fecha_vencimiento_secuencia`)	La fecha que la DGII autorizó para esa secuencia en ese ambiente. En TESTECF/CERTECF es 31-12-2028. Una fecha distinta da «Fecha de vencimiento de secuencia inválida». El Mapeo JSON nunca propone una fecha que la DGII ya rechazó. No aplica a 32 y 34.
IndicadorMontoGravado	Dice cómo leer los montos del XML: 0 = sin ITBIS, 1 = con ITBIS incluido. No depende de cómo el negocio fijó el precio. Ejemplo: 3,177.97 + ITBIS 572.03 = 3,750 → las líneas dicen 3,177.97 → 0. Si el JSON no lo trae, el gateway lo deduce de los montos (líneas + ITBIS = total → 0; líneas = total → 1). Obligatorio en 31/32/33/34/41/45; los demás tipos no lo llevan.
Tipo de pago	1 = contado, 2 = crédito (necesita fecha límite de pago), 3 = gratuito. En TESTECF la DGII ha rechazado el 2 aun con la fecha: si da problema, pruebe con 1.
Comprador	31, 41, 44 y 45 exigen el RNC del comprador. Use un RNC real.
Firma	La hace el certificado registrado en el gateway para el RNC de la empresa. Su titular debe estar delegado como Firmante de esa empresa en la Oficina Virtual de la DGII; si no, «no está delegado».

6. Tipos de comprobante

Tipo	Para qué	Notas
E31	Crédito Fiscal	Comprador con RNC.
E32	Consumo	Consumidor final; sin vencimiento de secuencia.
E33	Nota de Débito	Referencia al comprobante que modifica (código 3 = corrige montos).
E34	Nota de Crédito	Referencia al comprobante + `indicador_nota_credito`; sin vencimiento.
E41	Compras	El «comprador» es el proveedor informal; puede llevar retenciones.
E43	Gastos Menores	Sin comprador.
E44	Regímenes Especiales	Zonas francas y similares; venta exenta.
E45	Gubernamental	Entidades del Estado.
E46	Exportaciones	Tasa 0%, datos de embarque, transporte y otra moneda.
E47	Pagos al Exterior	Proveedor extranjero (identificador extranjero); retención de ISR.

7. Mensajes de la DGII y qué hacer

Mensaje	Qué hacer
Fecha de vencimiento de secuencia inválida	Ponga la fecha autorizada (TESTECF/CERTECF: 31-12-2028) en «Vence secuencia».
El campo IndicadorMontoGravado … no es válido	Falta o no cuadra con los montos: 0 si las líneas van sin ITBIS, 1 si lo incluyen.
El RNC del certificado no está delegado…	El titular del certificado debe ser Firmante de la empresa en la OFV, o asigne el RNC al certificado correcto en «Certificados».
El e-NCF … ya fue enviado	Use el siguiente número sugerido.
XSD: Missing child element …	El JSON no tiene la forma que espera la plantilla elegida (punto 2).

1. What it does 2. Two kinds of JSON 3. Step by step 4. Canonical examples 5. Fields DGII checks 6. Types E31–E47 7. Errors and what to do

1. What this process does

A billing system (EasyIMS or another one, e.g. AdingSoft) hands over each invoice as JSON. The gateway turns it into the canonical format, builds the e-CF XML, validates it against DGII's XSD, signs it with the company's registered certificate and, if you tick 📤 Enviar a la DGII (send to DGII), sends it and shows DGII's answer (Accepted / Rejected and the reason). Without that box everything is a test: nothing is sent.

2. Two kinds of JSON

Kind	What it is	What to choose in «Plantilla JSON / formato»
Canonical	The gateway's own format: the same one EasyIMS sends (`tipo_ecf`, `emisor`, `comprador`, `lineas`, `totales`…).	Canónico — formato EasyIMS (sin mapeo), or the CANONICO template.
Third-party	The JSON exactly as another system produces it (AdingSoft: `ncf`, `invoicedetail`, `Tax`…).	Its template (e.g. ADINGSOFT): it says which of their fields goes into each canonical field.

⚠️ If you paste a third-party JSON with «Canónico» selected, the XSD fails (e.g. «Missing child element RNCComprador / Item»): that JSON doesn't use the canonical names. Choose its template.

3. Step by step on the Mapeo JSON page

Empresa (company): the issuer (it signs with its certificate registered in the gateway). Only companies in a test mode (TESTECF, CERTECF or simulator): if the company is in PRODUCTION, every field is locked 🔒 and the gateway refuses to sign or send from here. Real documents come from the company's own system.
Plantilla JSON / formato (template / format): according to the kind of JSON (point 2).
Sustituir con los datos de la empresa (replace with the company's data, recommended): makes the company the issuer (RNC, legal name, address) and suggests the next e-NCF and the sequence expiry. The customer, lines and totals stay as they come in the JSON. Check both fields before processing.
Paste the input JSON (or pick one of the template's samples).
Firmar con (sign with): «El certificado registrado de la empresa elegida» (the chosen company's registered certificate).
Tick 📤 Enviar a la DGII only when you really want to send it, then press ▶ Procesar.
Follow the 6 steps at the top: 1 Read · 2 Map · 3 Build XML · 4 Validate XSD · 5 Sign · 6 Send. A red one tells you what failed; the «Salida» (output) panel has the details and DGII's answer.

4. Canonical examples (CANONICO template)

In 🧩 Plantillas JSON pick CANONICO in the built-in list and press Importar incluida (only once). It brings a valid example (passes the XSD) of every type:

Sample	Line amounts	IndicadorMontoGravado
`canonico_E31` … `canonico_E47`	Without ITBIS (ITBIS goes separately)	0
`canonico_E31T`, `E32T`, `E33T`, `E34T`, `E41T`, `E45T`	ITBIS included	1

To use one: open it in the template, copy it, choose Canónico on the Mapeo JSON page, paste it, tick Sustituir and process. The data is fictitious: to send it to DGII use a real buyer RNC, and for 33/34 put the e-NCF of an accepted document in modified_reference.ncf_modificado.

5. The fields DGII checks (and that cause most rejections)

Field	Rule
e-NCF	One number per document. EasyIMS and the Mapeo JSON page share each company's numbering: the gateway records everything sent and EasyIMS skips numbers already used from the Mapeo JSON page. Use the suggested one.
Sequence expiry (`fecha_vencimiento_secuencia`)	The date DGII authorized for that sequence in that environment. In TESTECF/CERTECF it is 31-12-2028. Any other date gives «Fecha de vencimiento de secuencia inválida». The Mapeo JSON page never suggests a date DGII already rejected. Not used by 32 and 34.
IndicadorMontoGravado	Tells DGII how to read the amounts in the XML: 0 = without ITBIS, 1 = ITBIS included. It does not depend on how the business set its price. Example: 3,177.97 + ITBIS 572.03 = 3,750 → the lines say 3,177.97 → 0. If the JSON doesn't bring it, the gateway works it out from the amounts (lines + ITBIS = total → 0; lines = total → 1). Required for 31/32/33/34/41/45; the other types don't carry it.
Payment type (`tipo_pago`)	1 = cash, 2 = credit (needs a payment due date), 3 = free. In TESTECF DGII has rejected 2 even with the date: if it causes trouble, try 1.
Buyer	31, 41, 44 and 45 require the buyer's RNC. Use a real RNC.
Signature	Made with the certificate registered in the gateway for the company's RNC. Its holder must be delegated as Firmante (signer) of that company in DGII's Oficina Virtual; otherwise «no está delegado».

6. Document types

Type	Used for	Notes
E31	Tax credit invoice (Crédito Fiscal)	Buyer with RNC.
E32	Consumer invoice (Consumo)	Final consumer; no sequence expiry.
E33	Debit note	Reference to the document it modifies (code 3 = corrects amounts).
E34	Credit note	Reference to the document + `indicador_nota_credito`; no sequence expiry.
E41	Purchases (Compras)	The «buyer» is the informal supplier; may carry withholdings.
E43	Minor expenses (Gastos Menores)	No buyer.
E44	Special regimes	Free zones and similar; exempt sale.
E45	Government	State entities.
E46	Exports	0% rate, shipping, transport and foreign-currency data.
E47	Payments abroad	Foreign supplier (foreign identifier); ISR withholding.

7. DGII messages and what to do

Message	What to do
Fecha de vencimiento de secuencia inválida	Put the authorized date (TESTECF/CERTECF: 31-12-2028) in «Vence secuencia».
El campo IndicadorMontoGravado … no es válido	Missing or not matching the amounts: 0 if the lines are without ITBIS, 1 if they include it.
El RNC del certificado no está delegado…	The certificate holder must be the company's Firmante in the OFV, or assign the RNC to the right certificate in «Certificados».
El e-NCF … ya fue enviado	Use the next suggested number.
XSD: Missing child element …	The JSON doesn't have the shape the chosen template expects (point 2).

① Entrada

② Mapa Ajustar a la pantalla

③ Salida