Saltar al contenido principal

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.

La anulación es irreversible

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" }] }
]
}'
CampoRequeridoQué es
cancellationsSíUn bloque por tipo de e-CF (también se acepta ranges).
cancellations[].ecfTypeSíTipo del bloque, de E31 a E47. Todos sus eNCF deben ser de ese tipo.
cancellations[].sequences[].fromSíPrimer eNCF del rango.
cancellations[].sequences[].toNoÚltimo eNCF del rango. Si lo omites, se anula solo from.
annulmentDateNoFecha de la anulación; por defecto, ahora.
submitNofalse 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: queda rejected como 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_CONFLICT con cada comprobante en details.conflicts y su reason:
reasonPor qué
document_already_submitted_or_dgii_validatedSe envió a la DGII, tiene TrackID o ya tiene respuesta de la DGII.
document_in_contingencyEstá en contingencia: se enviará a la DGII cuando vuelva.
document_dgii_submission_uncertainUn envío a la DGII empezó y no se confirmó.
document_dgii_submission_in_progressSe está enviando a la DGII en este momento.
document_already_delivered_to_receiverSe 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.

statusQué significa
builtArmado, sin firmar ni enviar.
signedFirmado, sin enviar.
acceptedLa DGII aceptó la anulación (202).
rejectedLa 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.
failedFalló antes de llegar a la DGII.
uncertainPudo 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ódigoCausa
400 ANECF_INVALIDRangos 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_CERTECFSe pidió en CerteCF; anula en eCF o prueba en TesteCF.
400 CERTIFICATE_NOT_CONFIGUREDNo hay certificado activo para firmar.
400 ANECF_DOCUMENT_CONFLICTEl 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_CONFLICTLo mismo, detectado mientras se registraba la anulación (details.documentId).
409 ANECF_RANGE_RESERVEDSe solapa con otra anulación en curso o aceptada.
409 ANECF_IDEMPOTENCY_CONFLICTLa 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_REQUIREDFalta 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 annulmentId junto con los números anulados.

Siguiente: Recepción y aprobación comercial o 5. Certifica ante la DGII.