Secuencias eNCF

Zarela registra los rangos de secuencias eNCF por ambiente y tipo para controles operativos, certificacion y ANECF. Tu POS/ERP asigna el numero a cada venta y lo envia dentro del JSON; el endpoint de emision no mueve el cursor del rango.

En el dashboard, Rangos de control corresponde exclusivamente a produccion eCF. TesteCF se usa para pruebas tecnicas y CerteCF se gestiona dentro del flujo de certificacion DGII; ninguno de esos ambientes cambia la secuencia que asigna tu POS.

Requiere el scope tenant:admin.

Listar rangos

GET /{environment}/secuencias

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

Respuesta:

{
  "ok": true,
  "ranges": [
    {
      "id": "a7f1e2c3-...",
      "ecfType": "E31",
      "rangeStart": 1,
      "rangeEnd": 1000,
      "nextSequence": 11,
      "encfLength": 10,
      "lowWaterMark": 25,
      "expiresAt": "2028-12-31T23:59:59-04:00",
      "active": true
    }
  ]
}

Crear un rango

POST /{environment}/secuencias

curl -X POST \
  https://ecf.api.zarela.do/eCF/secuencias \
  -H 'X-API-KEY: zk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "ecfType": "E31",
    "rangeStart": 1,
    "rangeEnd": 1000,
    "nextSequence": 1,
    "encfLength": 10,
    "lowWaterMark": 25,
    "expiresAt": "2028-12-31T23:59:59-04:00"
  }'

Campos

Campo	Requerido	Descripcion
ecfType	si	Tipo de comprobante (E31..E47).
rangeStart	si	Primer numero del rango autorizado por la DGII.
rangeEnd	si	Ultimo numero del rango.
nextSequence	no	Cursor operativo inicial (por defecto rangeStart); la emision desde el POS no lo incrementa.
encfLength	no	Longitud de la parte numerica del eNCF (por defecto 10).
lowWaterMark	no	Umbral de alerta de agotamiento del rango.
expiresAt	no	Fecha de vencimiento de la secuencia.

Respuesta (201): el rango creado, incluyendo id y active.

Como se usan los rangos

• Tu POS controla la asignacion correlativa de cada eNCF. El valor combina el prefijo (E + tipo) con la secuencia rellenada a encfLength digitos; por ejemplo, tipo E31 y secuencia 10 producen E310000000010.
• Al recibir el JSON, Zarela valida el formato, el tipo y que el eNCF no este anulado ni asociado a otro contenido.
• Los rangos configurados tambien permiten comprobar que una ANECF solo incluya secuencias administradas para ese ambiente.

Rangos por ambiente

Configura rangos separados por ambiente. Las secuencias de CerteCF (certificacion) y eCF (produccion) nunca se comparten.

El eNCF siempre viaja en la emision

El endpoint de emision no asigna secuencias. Genera y persiste el eNCF en tu POS antes del POST, incluyelo en el JSON y reutiliza ese mismo valor si debes reintentar.