Formato de documentos

Para emitir con Zarela envias documentos JSON con estructura DGII/XSD. Zarela transforma automaticamente tu JSON a XML, firma con tu certificado y valida contra el XSD oficial antes de enviar a la DGII.

Especificaciones de la DGII

Aunque envias JSON, la estructura debe seguir el esquema definido por la DGII para los XML. Consulta el Formato Comprobante Fiscal Electronico (e-CF) V1.0 para la descripcion de cada campo.

Proceso de transformacion JSON a XML

Zarela maneja toda la cadena automaticamente:

En tu sistema (cliente)

• Envio de JSON: tu sistema envia el documento con estructura { "ECF": ... }.
• Respuesta inmediata: recibes el documentId, el encf reservado y el estado encolado.
• Consulta posterior: consultas el estado final cuando lo necesites (batch).

En Zarela

• Recepcion y normalizacion del JSON.
• Validacion del eNCF enviado por tu POS: formato, tipo, duplicados y rangos anulados.
• Transformacion a XML segun el orden del XSD.
• Firma electronica XMLDSig (RSA-SHA256) con tu certificado.
• Validacion XSD del XML firmado.
• Generacion de RI/PDF y codigos de seguridad/QR.
• Envio asincrono a la DGII (e-CF extendido o RFCE segun corresponda).
• Gestion de estado tras la respuesta de la DGII.

En la DGII

• Recepcion del XML firmado.
• Procesamiento y validacion fiscal; respuesta con TrackID y estado.

Estructura JSON DGII/XSD

Ejemplo minimo de una factura de credito fiscal (E31):

{
  "ECF": {
    "Encabezado": {
      "Version": "1.0",
      "IdDoc": {
        "TipoeCF": 31,
        "eNCF": "E310000000001",
        "FechaVencimientoSecuencia": "31-12-2028",
        "IndicadorEnvioDiferido": 1,
        "IndicadorMontoGravado": 0,
        "TipoIngresos": "01",
        "TipoPago": 1
      },
      "Emisor": {
        "RNCEmisor": "132327179",
        "RazonSocialEmisor": "EMPRESA DEMO SRL",
        "DireccionEmisor": "Santo Domingo",
        "Municipio": "010101",
        "Provincia": "010000",
        "FechaEmision": "03-06-2026"
      },
      "Comprador": {
        "RNCComprador": "130701601",
        "RazonSocialComprador": "CLIENTE SRL"
      },
      "Totales": {
        "MontoExento": "150000.00",
        "MontoTotal": "150000.00"
      }
    },
    "DetallesItems": {
      "Item": [
        {
          "NumeroLinea": 1,
          "IndicadorFacturacion": 4,
          "NombreItem": "Producto exento",
          "IndicadorBienoServicio": 1,
          "CantidadItem": 1,
          "UnidadMedida": 1,
          "PrecioUnitarioItem": "150000.00",
          "MontoItem": "150000.00"
        }
      ]
    }
  }
}

eNCF requerido para emitir

Tu POS/ERP debe asignar el eNCF e incluirlo en el JSON de emision. Zarela no genera la secuencia durante este POST: valida su formato, tipo, unicidad y que no este anulado antes de convertir y firmar el XML. En validate=true puedes omitirlo y Zarela usara un valor temporal solo para la validacion.

Campo clave: IndicadorFacturacion

Valor	Significado
1	Gravado ITBIS 18%
2	Gravado ITBIS 16%
3	Gravado tasa 0%
4	Exento

Documentos que modifican otros (E33 / E34)

Las notas de debito (E33) y credito (E34) requieren la seccion InformacionReferencia con el NCFModificado, la fecha y el CodigoModificacion. El campo RazonModificacion se valida y se recorta a 90 caracteres. Ver Tipos de e-CF.

Contrato simplificado (opcional)

Para integraciones pequenas, Zarela acepta tambien un contrato canonico mas compacto. Zarela lo expande al JSON DGII completo, calcula totales e impuestos y mapea los indicadores fiscales.

{
  "type": "E31",
  "issueDate": "2026-06-03T10:30:00-04:00",
  "issuer": {
    "rnc": "132327179",
    "legalName": "EMPRESA DEMO SRL",
    "province": "010000",
    "municipality": "010101"
  },
  "buyer": { "rnc": "130701601", "name": "CLIENTE SRL" },
  "paymentType": "credit",
  "dueDate": "2026-07-03T10:30:00-04:00",
  "lines": [
    {
      "name": "Producto gravado",
      "quantity": 2,
      "unitPrice": 1000,
      "itbisRate": 18,
      "itemKind": "product"
    }
  ]
}

Campo	Notas
type	E31..E47.
encf	Opcional; si se omite, Zarela reserva del rango activo.
paymentType	cash o credit.
lines[].itbisRate	0, 16 o 18.
zeroTaxMode	exempt (IndicadorFacturacion 4) o taxedZero (IndicadorFacturacion 3).
reference	Para E33/E34: { encf, date, modificationCode, reason }.

El simplificado no sustituye al DGII/XSD

El contrato simplificado es un helper. Para casos fiscales complejos (multiples tasas, retenciones, exportaciones, paginacion) usa el JSON DGII/XSD completo.

Respuesta de emision

Al emitir (sin validate), recibes una respuesta inmediata 202:

{
  "ok": true,
  "mode": "queued",
  "result": {
    "documentId": "6f89c3d2-5f83-4607-9b50-99527cc40e5a",
    "encf": "E310000000010",
    "status": "queued_for_signing",
    "asyncStatusRequired": true
  }
}

Campo	Descripcion
documentId	Identificador interno de Zarela para rastrear la transaccion.
encf	Numero de comprobante fiscal electronico reservado.
status	Estado inicial; tipicamente queued_for_signing.
asyncStatusRequired	Indica que debes consultar el estado final por batch.

Consideraciones importantes

• Estructura correcta: respeta el esquema DGII aunque envies JSON.
• Formato de valores: cuida fechas (DD-MM-YYYY en campos DGII), montos y codigos.
• Procesamiento asincrono: espera unos segundos antes de consultar el estado final.
• Reintentos: conserva el JSON asociado a cada eNCF y reenvia exactamente ambos ante un timeout.
• Provincia y municipio: usa los codigos de la Tabla III de la DGII.

Siguiente paso

Revisa los ejemplos por tipo de e-CF y luego el envio de documentos.