Sandbox: prueba sin certificado
- 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 aPOST https://api.zarelafact.com/partner/v1/sandbox/documentscon tuX-PARTNER-KEY. - 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_conditionalorejected) y te dice el motivo de cada aviso o error. - 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.
| Sandbox | TesteCF | eCF | |
|---|---|---|---|
| Quién responde | ZarelaFact, con una simulación | La DGII, en su ambiente de pruebas | La DGII, en producción |
Certificado .p12 | No hace falta | Sí, firma con él | Sí, firma con él |
| Llega a la DGII | No | Sí | Sí |
| Validez fiscal | Ninguna: SIN VALIDEZ FISCAL | Ninguna | Sí |
| Cuenta en tu plan | No | No | Sí |
| Clave de cuenta directa | zrl_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
.p12de 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.
| Ruta | Permiso | Qué hace |
|---|---|---|
POST /Sandbox/documentos-ecf | ecf:validate | Recibe el JSON y responde el veredicto. Un rechazo también responde 201. |
GET /Sandbox/documentos-ecf | ecf:read | Lista tus documentos, del más reciente al más antiguo. |
GET /Sandbox/documentos-ecf/{id} | ecf:read | Un documento, con sus motivos. |
GET /Sandbox/documentos-ecf/{id}/xml | ecf:read | Su XML, sin firma y con un comentario de Sandbox. |
GET /Sandbox/documentos-ecf/{id}/pdf | ecf:read | Su 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.
| Ruta | Permiso | Qué hace |
|---|---|---|
POST /partner/v1/sandbox/documents | documents:validate | Igual que la cuenta directa. |
GET /partner/v1/sandbox/documents | documents:read | Lista los documentos de todo tu Partner. |
GET /partner/v1/sandbox/documents/{id} | documents:read | Un documento. |
GET /partner/v1/sandbox/documents/{id}/xml | documents:read | Su XML. |
GET /partner/v1/sandbox/documents/{id}/pdf | documents:read | Su representación impresa. |
Cuatro reglas de esta ruta:
- Envía el JSON DGII con
ECFen la raíz, o envuelto endocumentcomo en la emisión Partner: las dos formas se aceptan igual. El contrato simplificado también admitedocument. - 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"
}
| Campo | Qué es |
|---|---|
document.id | Id del documento en el Sandbox. Sirve para consultarlo, y para su XML y su PDF. |
document.encf, documentType, buyer, totals | Lo que leímos de tu JSON. Los montos van con dos decimales, o null si el JSON no trae el monto. |
document.status | Igual que verdict.status. |
document.verdict.reasons | Un motivo por cada aviso o error. Ver la tabla siguiente. |
document.verdict.disclaimer | Recuerda que el veredicto es una simulación. |
document.trackId | sandbox- seguido del id. No es un TrackID de la DGII. |
document.links | Rutas del XML y del PDF. Antepón https://api.zarelafact.com. |
correlationId | Id de la solicitud, para soporte. |
Cada motivo (verdict.reasons[]) trae estos campos:
| Campo | Qué es |
|---|---|
code | Código de ZarelaFact del aviso o del error, por ejemplo SQUARING_ABOVE_DGII_TOLERANCE. null si no tiene. |
dgiiCode | El código que devolvería la DGII, si el Sandbox lo simula (por ejemplo 1209). null si no simula uno. |
field | Campo de tu JSON al que se refiere. |
message | Qué pasa, en español. |
severity | Cómo lo marca la prevalidación: error o warning. |
effect | Lo 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.status | Qué simula | Qué haces |
|---|---|---|
accepted | La DGII lo aceptaría. Puede traer avisos con effect info, que no cambian nada. | Nada. |
accepted_conditional | La 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. |
rejected | La 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 DGII | Motivo | Veredicto |
|---|---|---|
2394 | MontoItem no cuadra con cantidad × precio unitario, descuento y recargo. | Aceptado condicional |
1934 | MontoGravadoI1, MontoGravadoI2 o MontoGravadoI3 no cuadran con el detalle. | Aceptado condicional |
1924 | MontoGravadoTotal no cuadra con el detalle. | Aceptado condicional |
11014 | TotalITBIS, 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 |
11105 | MontoTotal no cuadra con el detalle. | Aceptado condicional |
11374 | Un total en otra moneda (los que terminan en OtraMoneda) no cuadra. | Aceptado condicional |
1385 | El RNC del comprador no aparece en el padrón de la DGII. | Aceptado condicional |
1104 | FechaLimitePago es anterior a FechaEmision. | Aceptado condicional |
614 | Una nota modifica un e-NCF que no aparece entre tus documentos del Sandbox. | Rechazado |
1209 | El e-NCF ya se usó en tu Sandbox. | Rechazado |
null | Errores 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
FechaVencimientoSecuenciaque 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_LIMITy 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"
}
}
| Respuesta | Código | Cuándo | Qué hacer |
|---|---|---|---|
400 | INVALID_JSON | El cuerpo está vacío, no es JSON válido o no es un objeto. | Envía el JSON del documento. |
400 | BODY_TOO_LARGE | El cuerpo pasa de 1 MB. | Envía un documento más pequeño. |
400 | SANDBOX_TEXT_UNSUPPORTED | Un texto trae un carácter nulo o un sustituto UTF-16 suelto. | Quita el carácter y reenvía. |
400 | INVALID_SANDBOX_DOCUMENTS_QUERY | En la lista, verdict o documentType no son válidos. | Usa accepted, accepted_conditional o rejected, y un tipo de e-CF como E31. |
401 | INVALID_API_KEY o MISSING_API_KEY | Falta 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. |
401 | MISSING_PARTNER_KEY o INVALID_PARTNER_KEY | Falta la X-PARTNER-KEY o no es válida. | Revisa la credencial de tu backend. |
403 | INSUFFICIENT_SCOPE | La clave no tiene ecf:validate para enviar o ecf:read para consultar. | Usa una clave con ese permiso. |
403 | INSUFFICIENT_PARTNER_SCOPE | La credencial no tiene documents:validate o documents:read. | Pide una credencial con ese permiso. |
404 | DOCUMENT_NOT_FOUND | El id no existe, no es un UUID o es de otra cuenta. | Revisa el id que devolvió el POST. |
409 | SANDBOX_DOCUMENT_NOT_PRINTABLE | Pides 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. |
422 | SANDBOX_RENDER_FAILED o RI_GENERATION_FAILED | No 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. |
429 | RATE_LIMIT_EXCEEDED | Más de 1,000 solicitudes por minuto con la misma clave. | Espera los segundos de Retry-After. |
429 | SANDBOX_DAILY_LIMIT | Lí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. |
503 | SERVICE_UNAVAILABLE | Un 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.