Anulación de e-NCF
Cuando tu empresa deja de usar números de eNCF que la DGII le autorizó (porque cambió de sistema, se saltó secuencias o reservó un rango que nunca usó), debe anularlos con una Anulación de e-NCF (ANECF). ZarelaFact arma el ANECF con el formato de la DGII, lo valida contra su XSD, lo firma con tu certificado y lo envía.
Cuando la DGII la acepta, esos números ya no se pueden emitir. Anula solo secuencias que no hayan llegado a la DGII ni a tu comprador: ZarelaFact rechaza un rango con un eNCF que llegó o pudo llegar. Lo que ya llegó se corrige con una nota de crédito.
Las anulaciones se hacen en producción (eCF) y se prueban en TesteCF. En CerteCF no aplican y responden 400 ANECF_NOT_AVAILABLE_IN_CERTECF. No hace falta registrar rangos antes: la DGII comprueba que las secuencias sean de tu RNC.
Desde el portal
En Anulaciones, elige arriba pruebas (TesteCF) o producción y agrega uno o varios rangos, de uno o varios tipos. También puedes pegarlos desde Excel: dos columnas, desde y hasta. El tipo y la cantidad salen solos.
Cada rango se revisa al momento contra lo que ya emitiste y lo que ya anulaste. Si incluye e-CF que llegaron o pudieron llegar a la DGII, Empezar en… lo ajusta al siguiente número libre. Ver XML muestra el ANECF sin firmar y Revisar y anular lo envía después de confirmar. El historial queda debajo, con el XML y la respuesta de la DGII de cada envío.
Si la red falla y vuelves a enviar sin cambiar los rangos, ZarelaFact reconoce el reintento y no envía la anulación dos veces.
Por API
Requiere el permiso tenant:admin.
1. Prevalida
Arma el ANECF y lo valida contra el XSD, sin firmar ni enviar:
POST /{ambiente}/anulaciones-ecf/prevalidar
curl -X POST https://api.zarelafact.com/eCF/anulaciones-ecf/prevalidar \
-H 'X-API-KEY: zrl_live_...' \
-H 'Content-Type: application/json' \
-d '{
"cancellations": [
{ "ecfType": "E31", "sequences": [{ "from": "E310000000150", "to": "E310000000160" }] }
]
}'
2. Firma y envía
POST /{ambiente}/anulaciones-ecf
curl -X POST https://api.zarelafact.com/eCF/anulaciones-ecf \
-H 'X-API-KEY: zrl_live_...' \
-H 'Idempotency-Key: anecf-2026-10-e31-150-160' \
-H 'Content-Type: application/json' \
-d '{
"cancellations": [
{ "ecfType": "E31", "sequences": [{ "from": "E310000000150", "to": "E310000000160" }] },
{ "ecfType": "E32", "sequences": [{ "from": "E320000000020", "to": "E320000000020" }] }
]
}'
| Campo | Requerido | Qué es |
|---|---|---|
cancellations | Sí | Un bloque por tipo de e-CF (también se acepta ranges). |
cancellations[].ecfType | Sí | Tipo del bloque, de E31 a E47. Todos sus eNCF deben ser de ese tipo. |
cancellations[].sequences[].from | Sí | Primer eNCF del rango. |
cancellations[].sequences[].to | No | Último eNCF del rango. Si lo omites, se anula solo from. |
annulmentDate | No | Fecha de la anulación; por defecto, ahora. |
submit | No | false arma y firma sin enviar a la DGII. Por defecto true. |
ZarelaFact calcula el RNC emisor (el de tu cuenta), las cantidades por bloque y el total; no los envíes.
Idempotency-Key es obligatoria al enviar (sin ella, 428 IDEMPOTENCY_KEY_REQUIRED). Si no recibiste respuesta, repite con la misma clave y los mismos rangos: obtienes la misma anulación y no se envía dos veces. La misma clave con otros rangos responde 409 ANECF_IDEMPOTENCY_CONFLICT.
Qué se puede anular
La DGII permite anular los eNCF que no se enviaron ni a ella ni al comprador. Por eso:
- Se puede anular un eNCF que nunca usaste y también uno de un e-CF firmado que nunca salió hacia la DGII (por ejemplo, uno que se quedó en
signed). - Se puede anular el eNCF de un e-CF que la DGII rechazó con
secuenciaUtilizada: false(Decreto 587-24, art. 17 párr. III). El documento rechazado no cambia: quedarejectedcomo evidencia, y el eNCF anulado ya no se puede reenviar corregido. - No se puede anular un eNCF que llegó o pudo llegar a la DGII o al comprador. La respuesta es
ANECF_DOCUMENT_CONFLICTcon cada comprobante endetails.conflictsy sureason:
reason | Por qué |
|---|---|
document_already_submitted_or_dgii_validated | Se envió a la DGII, tiene TrackID o ya tiene respuesta de la DGII. |
document_in_contingency | Está en contingencia: se enviará a la DGII cuando vuelva. |
document_dgii_submission_uncertain | Un envío a la DGII empezó y no se confirmó. |
document_dgii_submission_in_progress | Se está enviando a la DGII en este momento. |
document_already_delivered_to_receiver | Se entregó, o pudo entregarse, al comprador. |
Cuando la DGII acepta la anulación, los comprobantes de tu cuenta dentro del rango que nunca llegaron a la DGII pasan a cancelled y sus envíos pendientes se detienen: un eNCF anulado ya no se envía. La respuesta los lista en coveredDocuments.cancelled (documentId, encf). Si alguno empezó a enviarse mientras tanto, va en coveredDocuments.skipped con su reason para que lo revises.
Respuesta
202 cuando la DGII la aceptó (200 con submit: false). Respuesta resumida:
{
"ok": true,
"annulmentId": "9b2c6f1e-7d3a-4c51-8e0f-2a6b1d9c4e77",
"totalAnnulled": 12,
"status": "accepted",
"annulment": { "id": "9b2c6f1e-7d3a-4c51-8e0f-2a6b1d9c4e77", "status": "accepted", "totalAnnulled": 12 },
"coveredDocuments": {
"cancelled": [{ "documentId": "5d1e7a2b-3c4f-4a6b-9c8d-0e1f2a3b4c5d", "encf": "E310000000152" }],
"skipped": []
}
}
Guarda el annulmentId: es la referencia para consultarla y la evidencia ante cualquier revisión.
status | Qué significa |
|---|---|
built | Armado, sin firmar ni enviar. |
signed | Firmado, sin enviar. |
accepted | La DGII aceptó la anulación (202). |
rejected | La DGII la rechazó (422, con sus mensajes en dgii.mensajes). Es definitivo: los rangos quedan libres y puedes corregir y enviar otra vez con otra Idempotency-Key. |
failed | Falló antes de llegar a la DGII. |
uncertain | Pudo llegar a la DGII, pero no se confirmó el resultado (502). También queda así si la DGII anuló solo una parte («anuladas correctamente. Con excepción…»). No la reenvíes. |
Errores
| Código | Causa |
|---|---|
400 ANECF_INVALID | Rangos mal formados, tipos que no coinciden o un rango invertido. Cada eNCF es E, el tipo y un secuencial de 10 dígitos decimales mayor que cero: la secuencia 0, letras, exponentes o espacios en el secuencial se rechazan. |
400 ANECF_NOT_AVAILABLE_IN_CERTECF | Se pidió en CerteCF; anula en eCF o prueba en TesteCF. |
400 CERTIFICATE_NOT_CONFIGURED | No hay certificado activo para firmar. |
400 ANECF_DOCUMENT_CONFLICT | El rango contiene un eNCF que llegó o pudo llegar a la DGII o al comprador; ver details.conflicts[].reason en Qué se puede anular. |
409 ANECF_DOCUMENT_CONFLICT | Lo mismo, detectado mientras se registraba la anulación (details.documentId). |
409 ANECF_RANGE_RESERVED | Se solapa con otra anulación en curso o aceptada. |
409 ANECF_IDEMPOTENCY_CONFLICT | La Idempotency-Key ya se usó con otros rangos. |
422 con status: "rejected" | La DGII rechazó la anulación. La respuesta es la anulación completa, con dgii.mensajes. |
428 IDEMPOTENCY_KEY_REQUIRED | Falta la Idempotency-Key al enviar. |
502 con status: "uncertain" | No se confirmó el resultado en la DGII. Ver Resultado incierto. |
Consulta una anulación
GET /{ambiente}/anulaciones-ecf/{annulmentId}
Devuelve { "ok": true, "annulment": { ... } } con su estado actual.
Resultado incierto
Si el estado es uncertain, no reenvíes la anulación. Cuando tengas una confirmación verificable del resultado en la DGII, regístrala:
POST /{ambiente}/anulaciones-ecf/{annulmentId}/reconciliar
{
"outcome": "accepted",
"evidence": {
"source": "dgii-status-query",
"reference": "track-o-referencia-dgii",
"observedAt": "2026-10-01T15:00:00-04:00",
"details": { "codigo": "0" }
}
}
outcome admite accepted o rejected. La reconciliación no reenvía nada y no se puede cambiar después. Con accepted, los comprobantes del rango que nunca llegaron a la DGII se cancelan igual que al aceptarse el envío, y la respuesta trae coveredDocuments. Si no tienes confirmación, deja el estado uncertain y escríbenos con el annulmentId y el correlationId.
Buenas prácticas
- Revisa antes de anular: confirma con la consulta por lote que ningún número del rango llegó a la DGII, o usa la prevalidación, que te dice cuál y por qué.
- Prueba en TesteCF: el flujo es igual al de producción y no toca tus secuencias reales.
- Anula por rangos, no número por número: un rango de 500 secuencias es una sola línea.
- Guarda el
annulmentIdjunto con los números anulados.
Siguiente: Recepción y aprobación comercial o 5. Certifica ante la DGII.