Anulaciones (ANECF)

La Anulacion de e-NCF (ANECF) se usa para reportar a la DGII rangos de eNCF que no seran utilizados. Zarela genera el XML ANECF, lo valida contra anecf.xsd, lo firma y lo envia.

Requiere el scope tenant:admin.

Prevalidar

Genera el ANECF sin enviarlo: valida rangos/documentos y comprueba contra el XSD.

POST /{environment}/anulaciones-ecf/prevalidar

curl -X POST \
  https://ecf.api.zarela.do/eCF/anulaciones-ecf/prevalidar \
  -H 'X-API-KEY: zk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "annulmentDate": "2026-06-03T10:30:00-04:00",
    "cancellations": [
      {
        "ecfType": "E31",
        "sequences": [
          { "from": "E310000000150", "to": "E310000000160" }
        ]
      }
    ]
  }'

Firmar y enviar

POST /{environment}/anulaciones-ecf

curl -X POST \
  https://ecf.api.zarela.do/eCF/anulaciones-ecf \
  -H 'X-API-KEY: zk_live_...' \
  -H 'Idempotency-Key: anecf-cierre-2026-06-e31-150-160' \
  -H 'Content-Type: application/json' \
  -d '{
    "annulmentDate": "2026-06-03T10:30:00-04:00",
    "cancellations": [
      {
        "ecfType": "E31",
        "sequences": [
          { "from": "E310000000150", "to": "E310000000160" }
        ]
      }
    ],
    "submit": true
  }'

Campos del cuerpo

Campo	Requerido	Descripcion
rncEmisor	no	RNC emisor; por defecto el de la cuenta del API key.
annulmentDate	no	Fecha de la anulacion; por defecto la fecha actual.
cancellations	si	Bloques de anulacion, uno por tipo de e-CF (alias: ranges).
cancellations[].ecfType	si	Tipo de comprobante del bloque (E31..E47).
cancellations[].sequences	si	Rangos de eNCF a anular dentro del bloque.
cancellations[].sequences[].from	si	Primer eNCF del rango (alias: desde).
cancellations[].sequences[].to	no	Ultimo eNCF del rango (alias: hasta); por defecto igual a from para anular un solo eNCF.
submit	no	true firma y envia; false solo construye/valida. Por defecto true.

Cuando submit es true, el header Idempotency-Key es obligatorio. Reutiliza la misma clave únicamente con los mismos rangos. Si la clave ya fue usada con rangos diferentes, la API responde 409 ANECF_IDEMPOTENCY_CONFLICT.

Todos los eNCF de un bloque deben coincidir con su ecfType (por ejemplo, un rango E31... en un bloque E31); de lo contrario la API responde 400.

Respuesta

202 cuando se envio a la DGII (200 si submit:false):

{
  "ok": true,
  "annulmentId": "9b2c...",
  "totalAnnulled": 11,
  "status": "accepted",
  "signedXml": "<ANECF>...</ANECF>",
  "dgii": { "codigo": "...", "trackId": "..." },
  "annulment": { "id": "9b2c...", "status": "accepted", "totalAnnulled": 11 }
}

status	Significado
built	ANECF construido (no enviado).
signed	Firmado.
accepted	Aceptado por la DGII.
rejected	Rechazado por la DGII.
failed	Error durante el proceso.
uncertain	La solicitud pudo llegar a la DGII, pero Zarela no pudo confirmar el resultado. No la reenvies automaticamente.

Consultar una anulacion

GET /{environment}/anulaciones-ecf/{annulmentId}

curl -X GET \
  https://ecf.api.zarela.do/eCF/anulaciones-ecf/9b2c... \
  -H 'X-API-KEY: zk_live_...'

Devuelve { "ok": true, "annulment": { ... } } con el estado actual de la anulacion.

Reconciliar un resultado incierto

Solo usa esta operacion cuando el estado sea uncertain y tengas una confirmacion externa verificable del resultado:

POST /{environment}/anulaciones-ecf/{annulmentId}/reconciliar

curl -X POST \
  https://ecf.api.zarela.do/eCF/anulaciones-ecf/9b2c.../reconciliar \
  -H 'X-API-KEY: zk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "outcome": "accepted",
    "evidence": {
      "source": "dgii-status-query",
      "reference": "track-o-referencia-dgii",
      "observedAt": "2026-06-03T15:00:00-04:00",
      "details": { "codigo": "0" }
    }
  }'

Para ANECF, outcome admite accepted o rejected. La reconciliacion no vuelve a enviar la solicitud y no puede cambiarse posteriormente con otra evidencia. Si no tienes confirmacion suficiente, conserva el estado uncertain y contacta soporte con el annulmentId y correlationId.

Prevalida primero

Ejecuta prevalidar antes de enviar para confirmar que los rangos son validos y el XML cumple el XSD. Asi evitas rechazos de la DGII.