Saltar al contenido principal

Sandbox: prueba sin certificado

En resumen
  1. Envía el JSON de tu comprobante a POST https://api.zarelafact.com/Sandbox/documentos-ecf, con tu clave de TesteCF. Si eres Partner, envíalo a POST https://api.zarelafact.com/partner/v1/sandbox/documents con tu X-PARTNER-KEY.
  2. No necesitas certificado. ZarelaFact no firma, no envía nada a la DGII y no crea un e-CF. Simula el veredicto que daría la DGII (accepted, accepted_conditional o rejected) y te dice el motivo de cada aviso o error.
  3. El documento se conserva 30 días, con su XML y su PDF marcados SIN VALIDEZ FISCAL. No cuenta en tu plan.

Qué es y qué no es​

El Sandbox simula. Sirve para saber, antes de tener tu certificado, si un JSON pasaría las reglas de la DGII y por qué no pasaría. Nada de lo que hace llega a la DGII ni tiene validez fiscal.

SandboxTesteCFeCF
Quién respondeZarelaFact, con una simulaciónLa DGII, en su ambiente de pruebasLa DGII, en producción
Certificado .p12No hace faltaSí, firma con élSí, firma con él
Llega a la DGIINoSíSí
Validez fiscalNinguna: SIN VALIDEZ FISCALNingunaSí
Cuenta en tu planNoNoSí
Clave de cuenta directazrl_test_zrl_test_zrl_live_
Ruta de cuenta directa/Sandbox/documentos-ecf/TesteCF/documentos-ecf/eCF/documentos-ecf

Usa cada uno para algo distinto:

  • Sandbox: mientras armas la integración, para ver el veredicto y los motivos de cada JSON sin certificado.
  • TesteCF (el ambiente de pruebas de la DGII): cuando necesitas la respuesta real de la DGII, con su TrackID y sus estados. Necesita el .p12 de la empresa.
  • ?validate=true: para revisar la forma y los cálculos de un JSON sin guardar nada. Ver Validar sin emitir.

El Sandbox aplica las reglas de producción, las del ambiente eCF. En tu cuenta directa ZarelaFact completa los marcadores de tu cuenta ({{RNC}}, {{FECHA_EMISION}}…) y el emisor igual que al emitir; los de tu cliente los reemplazas tú.

Un e-NCF que ya usaste en el Sandbox se rechaza con el código DGII 1209. Para repetir una prueba, usa otro número.

Desde el portal​

El portal tiene el mismo Sandbox que la API: lo que envías por una aparece en la otra. En el menú, abre Sandbox. Lo ven las cuentas directas y las Partner. Un Partner tiene un solo Sandbox para todos sus clientes: su lista y sus envíos son de todo el Partner.

Probar un JSON. Pega tu e-CF completo en la tarjeta Probar un JSON y pulsa Enviar al Sandbox. El veredicto aparece ahí mismo, con sus motivos. Si el texto no es JSON, el portal te dice qué revisar antes de enviarlo.

Lo que has probado. Es la lista de tus documentos, del más reciente al más antiguo. Busca por e-NCF, comprador o RNC, o filtra por Tipo y por Veredicto. La columna Veredicto usa estas etiquetas:

  • Aceptado*: la DGII lo aceptaría.
  • Condicional*: la DGII lo aceptaría como Aceptado condicional.
  • Rechazado: la DGII lo rechazaría.

El asterisco remite a la nota que aparece bajo la lista: «*Simulado en el Sandbox: sin validez fiscal.»

El detalle. El ícono del ojo abre el veredicto de esa fila. Los motivos se agrupan así:

  • Motivo del rechazo: lo que haría que la DGII rechace el documento.
  • Quedaría Aceptado Condicional por: los descuadres o datos que lo dejarían como Aceptado condicional.
  • Además: avisos que solo informan. No cambian el veredicto.

Cada motivo muestra su campo de tu JSON, su código de ZarelaFact y su código DGII, si lo tiene.

PDF y XML. Cada fila y el detalle tienen los botones PDF y XML. El PDF lleva la leyenda SIN VALIDEZ FISCAL. El XML va sin firma y con un comentario de Sandbox. Si ZarelaFact no pudo armar el e-CF con tu JSON, no hay PDF ni XML: el detalle lo dice y deshabilita los botones.

Quién puede enviar. En tu cuenta directa, pueden enviar JSON los roles owner, admin, developer y operator. El rol viewer solo ve lo probado, y el formulario aparece deshabilitado. En un Partner, los roles son owner, developer y viewer: solo owner y developer envían.

Por API directa​

Usa la clave de TesteCF. Las claves que creas en el portal pueden validar y consultar, así que sirven para el Sandbox.

RutaPermisoQué hace
POST /Sandbox/documentos-ecfecf:validateRecibe el JSON y responde el veredicto. Un rechazo también responde 201.
GET /Sandbox/documentos-ecfecf:readLista tus documentos, del más reciente al más antiguo.
GET /Sandbox/documentos-ecf/{id}ecf:readUn documento, con sus motivos.
GET /Sandbox/documentos-ecf/{id}/xmlecf:readSu XML, sin firma y con un comentario de Sandbox.
GET /Sandbox/documentos-ecf/{id}/pdfecf:readSu representación impresa, con la leyenda SIN VALIDEZ FISCAL.

Los Ejemplos JSON por tipo de e-CF funcionan aquí después de reemplazar los marcadores de tu cliente ({{RNC_COMPRADOR}}, {{RAZON_SOCIAL_COMPRADOR}}…; ver Cómo usar estos ejemplos). Cambia el eNCF en cada prueba (por ejemplo E310009000001), porque un e-NCF ya usado se rechaza:

curl -sS -X POST "https://api.zarelafact.com/Sandbox/documentos-ecf" \
-H "X-API-KEY: $ZARELA_TEST_KEY" \
-H "Content-Type: application/json" \
--data @factura-e31.json

Lista los documentos rechazados:

curl -sS "https://api.zarelafact.com/Sandbox/documentos-ecf?verdict=rejected&limit=10" \
-H "X-API-KEY: $ZARELA_TEST_KEY"

Descarga el XML de uno. Cambia {id} por el document.id que devolvió el POST:

curl -sS -o sandbox.xml \
-H "X-API-KEY: $ZARELA_TEST_KEY" \
"https://api.zarelafact.com/Sandbox/documentos-ecf/{id}/xml"

La lista acepta limit (de 1 a 100, 25 por defecto), offset, verdict (uno o varios, separados por comas o repitiendo el parámetro), documentType (por ejemplo E31) y search. La búsqueda mira el e-NCF, el RNC y el nombre del comprador, sin distinguir mayúsculas. Un verdict o un documentType que no existe responde 400.

Por API Partner​

Tu cuenta Partner tiene un solo Sandbox. Lo comparten tus credenciales de prueba y de producción, y todos tus clientes. No hace falta una Cuenta fiscal ni un certificado, y el RNC del emisor puede ser cualquiera.

RutaPermisoQué hace
POST /partner/v1/sandbox/documentsdocuments:validateIgual que la cuenta directa.
GET /partner/v1/sandbox/documentsdocuments:readLista los documentos de todo tu Partner.
GET /partner/v1/sandbox/documents/{id}documents:readUn documento.
GET /partner/v1/sandbox/documents/{id}/xmldocuments:readSu XML.
GET /partner/v1/sandbox/documents/{id}/pdfdocuments:readSu representación impresa.

Cuatro reglas de esta ruta:

  • Envía el JSON DGII con ECF en la raíz, o envuelto en document como en la emisión Partner: las dos formas se aceptan igual. El contrato simplificado también admite document.
  • No se resuelven marcadores como {{RNC}} ni se completa el emisor. Envía los datos completos.
  • Un e-NCF se rechaza con el código DGII 1209 solo si ya lo usaste en tu Sandbox con el mismo RNC emisor.
  • Todos tus clientes comparten el Sandbox. Su lista reúne los documentos de todos.

Respuesta​

Un POST responde 201 con el documento guardado. Este ejemplo muestra un rechazo por un e-NCF repetido:

{
"ok": true,
"environment": "Sandbox",
"document": {
"id": "7c1e0b5a-3d2f-4f7e-9a8b-2d6c1f0e9a41",
"sandbox": true,
"encf": "E310009000001",
"documentType": "E31",
"buyer": { "rnc": "{{RNC_COMPRADOR}}", "name": "{{RAZON_SOCIAL_COMPRADOR}}" },
"totals": { "total": "1180.00", "itbis": "180.00" },
"status": "rejected",
"verdict": {
"status": "rejected",
"reasons": [
{
"code": "SANDBOX_ENCF_ALREADY_USED",
"dgiiCode": "1209",
"field": "ECF.Encabezado.IdDoc.eNCF",
"message": "Este e-NCF ya se usó en tu Sandbox: la DGII lo rechaza (1209 «secuencia ya utilizada»)",
"severity": "error",
"effect": "rejects"
}
],
"disclaimer": "Simulación de ZarelaFact: sin validez fiscal. La DGII real también revisa tu certificado, la delegación del firmante y que el e-NCF esté autorizado y sin usar."
},
"trackId": "sandbox-7c1e0b5a-3d2f-4f7e-9a8b-2d6c1f0e9a41",
"createdAt": "2026-10-09T14:32:05.120Z",
"links": {
"xml": "/Sandbox/documentos-ecf/7c1e0b5a-3d2f-4f7e-9a8b-2d6c1f0e9a41/xml",
"pdf": "/Sandbox/documentos-ecf/7c1e0b5a-3d2f-4f7e-9a8b-2d6c1f0e9a41/pdf"
}
},
"correlationId": "2d9f4a7c-6b1e-4f0a-9c3d-8e5b7a1f2c64"
}
CampoQué es
document.idId del documento en el Sandbox. Sirve para consultarlo, y para su XML y su PDF.
document.encf, documentType, buyer, totalsLo que leímos de tu JSON. Los montos van con dos decimales, o null si el JSON no trae el monto.
document.statusIgual que verdict.status.
document.verdict.reasonsUn motivo por cada aviso o error. Ver la tabla siguiente.
document.verdict.disclaimerRecuerda que el veredicto es una simulación.
document.trackIdsandbox- seguido del id. No es un TrackID de la DGII.
document.linksRutas del XML y del PDF. Antepón https://api.zarelafact.com.
correlationIdId de la solicitud, para soporte.

Cada motivo (verdict.reasons[]) trae estos campos:

CampoQué es
codeCódigo de ZarelaFact del aviso o del error, por ejemplo SQUARING_ABOVE_DGII_TOLERANCE. null si no tiene.
dgiiCodeEl código que devolvería la DGII, si el Sandbox lo simula (por ejemplo 1209). null si no simula uno.
fieldCampo de tu JSON al que se refiere.
messageQué pasa, en español.
severityCómo lo marca la prevalidación: error o warning.
effectLo que hace en el veredicto: rejects rechaza, conditional lo deja Aceptado condicional e info solo informa.

severity no decide el veredicto; decide effect. Por ejemplo, una nota sobre un e-NCF que nunca se emitió en tu Sandbox es un warning con effect rejects. Un error de estructura (el XSD oficial) llega como un motivo por cada campo que no cumple, con code XSD_INVALID y el valor que enviaste dentro del message.

Dentro del Sandbox, los avisos de descuadre y de FechaLimitePago dicen «en producción se emitiría y la DGII lo dejaría Aceptado Condicional». En el Sandbox no se emite nada: el texto solo dice lo que pasaría en producción.

Veredictos​

verdict.statusQué simulaQué haces
acceptedLa DGII lo aceptaría. Puede traer avisos con effect info, que no cambian nada.Nada.
accepted_conditionalLa DGII lo aceptaría como Aceptado condicional, por un descuadre o un dato que la DGII marca así.Revisa el motivo. Si el dato es tuyo, corrígelo.
rejectedLa DGII lo rechazaría.Corrige el campo del motivo y envía otro JSON.

Todo veredicto del Sandbox es una simulación de ZarelaFact, no la respuesta de la DGII. Por eso el disclaimer, el XML y el PDF dicen que no tienen validez fiscal. Un rechazo también se guarda: es la respuesta del Sandbox, no un error de la API.

Códigos DGII que simula​

Código DGIIMotivoVeredicto
2394MontoItem no cuadra con cantidad × precio unitario, descuento y recargo.Aceptado condicional
1934MontoGravadoI1, MontoGravadoI2 o MontoGravadoI3 no cuadran con el detalle.Aceptado condicional
1924MontoGravadoTotal no cuadra con el detalle.Aceptado condicional
11014TotalITBIS, TotalITBIS1, TotalITBIS2 o TotalITBIS3 no cuadran, también en la nota de crédito a más de 30 días sin ITBIS (LATE_CREDIT_NOTE_WITHOUT_ITBIS).Aceptado condicional
11105MontoTotal no cuadra con el detalle.Aceptado condicional
11374Un total en otra moneda (los que terminan en OtraMoneda) no cuadra.Aceptado condicional
1385El RNC del comprador no aparece en el padrón de la DGII.Aceptado condicional
1104FechaLimitePago es anterior a FechaEmision.Aceptado condicional
614Una nota modifica un e-NCF que no aparece entre tus documentos del Sandbox.Rechazado
1209El e-NCF ya se usó en tu Sandbox.Rechazado
nullErrores de estructura: XSD, campos obligatorios, formatos y los demás errores de la prevalidación.Rechazado

Un descuadre cuenta solo si supera la tolerancia de la DGII: RD$1 por línea en cada MontoItem, y RD$1 por cada línea del detalle en los totales. ZarelaFact aplica la tolerancia oficial (Informe Técnico e-CF v1.0, §12: RD$1 por línea). En TesteCF, la DGII fue más tolerante: el Sandbox puede avisar de un descuadre que la DGII todavía acepta sin observación. Es a propósito: es más seguro avisar de más.

Los avisos con effect info no cambian el veredicto, aunque no tengan código DGII. Por ejemplo, ITBIS_RATE_MISMATCH avisa cuando ITBIS1 no es 18 y el documento sigue como accepted.

Otros errores, como una nota sobre un e-NCF que tu Sandbox rechazó (REFERENCED_ENCF_NOT_ACCEPTED) o un comprador distinto del de la factura que modifica (REFERENCED_BUYER_MISMATCH), rechazan con dgiiCode null.

Lo que no puede revisar​

El Sandbox responde lo que se puede saber sin la DGII. Estas cosas solo las revisa la DGII, así que un documento que pasa el Sandbox puede rechazarse allí:

  • Tu certificado y la delegación del firmante. El Sandbox no tiene tu .p12. La DGII rechaza los e-CF firmados con un certificado que no tiene delegado el rol Firmante Autorizado en la Oficina Virtual. En TesteCF, ese caso responde con el código 4: «El RNC del certificado no está delegado…». Ver Por qué un documento no avanza.
  • Que el e-NCF esté autorizado y vigente. El Sandbox no compara el e-NCF con los rangos que la DGII te asignó. Solo revisa las fechas que trae tu JSON. La DGII sí revisa el rango y su vigencia: un e-NCF fuera de los rangos autorizados responde 135 «Número de secuencia no autorizada», y una FechaVencimientoSecuencia que no es la del rango responde 145 «Fecha de vencimiento de secuencia inválida». En TesteCF, la DGII espera 31-12-2028.
  • Que el e-NCF no se haya usado fuera del Sandbox. El Sandbox solo ve lo que enviaste allí. Un e-NCF que usaste en TesteCF o en producción se acepta aquí, y la DGII lo rechaza con el código 1209 («secuencia ya utilizada»).
  • El estado real de la DGII. El Sandbox no la consulta. Responde aunque la DGII esté caída.

TesteCF devolvió estos códigos el 8 de octubre de 2026. Por eso el veredicto es una predicción: la DGII tiene la última palabra. Para la respuesta real, usa TesteCF.

Retención y límites​

  • Retención: 30 días, automática. Un documento del Sandbox se conserva 30 días desde su envío. ZarelaFact borra cada día los que tienen más de 30 días. No tienes que hacer nada.
  • Límite diario: 1,000 documentos en 24 horas. Cuenta los válidos y los rechazados. En un Partner, el límite es de todo el Partner. Si llegas al límite, la API responde 429 SANDBOX_DAILY_LIMIT y no guarda nada.
  • Sin webhooks. El veredicto llega en la respuesta del POST. No hay estados que consultar después ni eventos de webhook.
  • Sin plan ni cobros. No cuenta para tu plan y no genera cargos.
  • Sin efectos fiscales. No llama a la DGII y no usa ni reserva e-NCF fuera del Sandbox.
  • Tamaño. El cuerpo de cada envío puede pesar hasta 1 MB.
  • Caracteres. Un texto con un carácter nulo (NUL) o con un sustituto UTF-16 suelto se rechaza con 400 SANDBOX_TEXT_UNSUPPORTED, porque la base no lo guarda.

Errores​

Los errores tienen la misma forma que en el resto de la API. Guarda el correlationId para soporte:

{
"ok": false,
"correlationId": "5e0c2b9a-41d7-4f3e-8a6b-0c9d2e7f1a53",
"error": {
"code": "DOCUMENT_NOT_FOUND",
"message": "Documento no encontrado"
}
}
RespuestaCódigoCuándoQué hacer
400INVALID_JSONEl cuerpo está vacío, no es JSON válido o no es un objeto.Envía el JSON del documento.
400BODY_TOO_LARGEEl cuerpo pasa de 1 MB.Envía un documento más pequeño.
400SANDBOX_TEXT_UNSUPPORTEDUn texto trae un carácter nulo o un sustituto UTF-16 suelto.Quita el carácter y reenvía.
400INVALID_SANDBOX_DOCUMENTS_QUERYEn la lista, verdict o documentType no son válidos.Usa accepted, accepted_conditional o rejected, y un tipo de e-CF como E31.
401INVALID_API_KEY o MISSING_API_KEYFalta la clave, es inválida o es de otro ambiente. Una clave zrl_cert_ o zrl_live_ responde 401 aquí.Usa tu clave de TesteCF.
401MISSING_PARTNER_KEY o INVALID_PARTNER_KEYFalta la X-PARTNER-KEY o no es válida.Revisa la credencial de tu backend.
403INSUFFICIENT_SCOPELa clave no tiene ecf:validate para enviar o ecf:read para consultar.Usa una clave con ese permiso.
403INSUFFICIENT_PARTNER_SCOPELa credencial no tiene documents:validate o documents:read.Pide una credencial con ese permiso.
404DOCUMENT_NOT_FOUNDEl id no existe, no es un UUID o es de otra cuenta.Revisa el id que devolvió el POST.
409SANDBOX_DOCUMENT_NOT_PRINTABLEPides el XML o el PDF de un documento cuyo JSON no se pudo convertir en e-CF. Ese documento no tiene XML ni PDF.Corrige el JSON según sus motivos y envía otro.
422SANDBOX_RENDER_FAILED o RI_GENERATION_FAILEDNo se pudo generar el XML o el PDF de un documento que sí tiene e-CF.Reintenta más tarde. Si sigue, escribe a soporte con el correlationId.
429RATE_LIMIT_EXCEEDEDMás de 1,000 solicitudes por minuto con la misma clave.Espera los segundos de Retry-After.
429SANDBOX_DAILY_LIMITLímite diario por cuenta: 1,000 documentos en 24 horas, válidos o rechazados. No se guarda nada.Espera. Solo cuentan los documentos de las últimas 24 horas.
503SERVICE_UNAVAILABLEUn problema temporal nuestro. Tu clave no tiene nada que ver.Espera los segundos de Retry-After y reintenta.

Siguiente: Ejemplos JSON por tipo de e-CF.