Secuencias de e-NCF

Cada e-CF lleva un número de comprobante (e-NCF) que sale de una secuencia: el rango que la DGII te autorizó para ese tipo de e-CF, con su vencimiento. Sin una secuencia vigente de un tipo, no puedes emitir ese tipo. AC-PAY asigna los números por ti: tomas la secuencia del tipo, usas el próximo número y no pasas de rangeTo ni de expiresAt. Tú solo registras el rango cuando la DGII te lo autoriza y lo amplías cuando te lo renueva.

Registrar una secuencia

Solicita el rango en la Oficina Virtual de la DGII y regístralo tal como te lo autorizaron:

curl -X POST https://e-cf.acpay.do/sandbox/v1/sequences \
  -H "Authorization: Bearer $ACPAY_TEST_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "ecfType": 31, "rangeFrom": 1, "rangeTo": 1000, "expiresAt": "2027-12-31" }'

Campo	Qué es
`ecfType`	Tipo de e-CF: 31, 32, 33, 34, 41, 43, 44, 45, 46 o 47.
`rangeFrom`	Primer número autorizado. El primer e-CF de este tipo lo usará.
`rangeTo`	Último número autorizado. Igual o mayor que `rangeFrom`.
`expiresAt`	Vencimiento autorizado, `YYYY-MM-DD`. Obligatorio salvo en los e-CF 32 y 34.

La respuesta (201) es la secuencia, igual que en GET /v1/sequences. Como todo POST, lleva Idempotency-Key: si se corta la conexión, repite con la misma llave y recibes la misma secuencia.

Ampliar una secuencia

Cuando la DGII te amplía el rango o renueva el vencimiento, actualiza la secuencia de ese tipo:

curl -X PATCH https://e-cf.acpay.do/sandbox/v1/sequences/31 \
  -H "Authorization: Bearer $ACPAY_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rangeTo": 2000, "expiresAt": "2028-12-31" }'

Envía rangeTo, expiresAt o ambos.
La API solo amplía: rangeTo igual o mayor que el actual. El inicio del rango y el próximo número no cambian.
Repetir la misma solicitud deja la secuencia igual, así que no lleva Idempotency-Key.

Antes de emitir

Revisa GET /v1/sequences y emite solo con las secuencias que tengan usable: true (activa, vigente y con números). Vigila remaining y expiresAt para pedir la ampliación a la DGII antes de quedarte sin números.

{
  "ecfType": 31,
  "prefix": "E31",
  "rangeFrom": 1,
  "rangeTo": 1000,
  "nextNumber": 58,
  "remaining": 943,
  "expiresAt": "2027-12-31T00:00:00.000Z",
  "active": true,
  "usable": true
}

expiresAt es un día: la secuencia sirve hasta el final de ese día en hora de República Dominicana. Se devuelve a medianoche UTC; lee solo la fecha.

Reglas

Una secuencia por tipo. Registrar otra del mismo tipo responde 409: amplía la que tienes.
Solo rangos autorizados. AC-PAY numera desde rangeFrom; la DGII rechaza un e-NCF que no te autorizó.
Varios comercios con el mismo RNC comparten la numeración. Un rango que se cruce con el de otro de tus comercios responde 409 con el primer número libre.
Vencimiento vigente. Un expiresAt que ya pasó responde 400.
Lo demás, en el panel. Corregir el inicio, saltar números, desactivar o borrar una secuencia se hace en el panel de AC-PAY: un error ahí repite e-NCF ya reportados a la DGII.

Permiso de la llave

Registrar y ampliar exigen una llave con el permiso Secuencias e-NCF; sin él responden 403. Listar solo necesita el permiso de consulta. Pide a AC-PAY que lo agregue a tu llave si tu sistema va a administrar las secuencias.

Las secuencias del sandbox y las de producción son distintas. Al pasar a producción, registra allí los rangos reales que te autorizó la DGII.

Empezar

Conceptos

Producción

Registrar una secuencia

Ampliar una secuencia

Antes de emitir

Reglas

Permiso de la llave

​Registrar una secuencia

​Ampliar una secuencia

​Antes de emitir

​Reglas

​Permiso de la llave

Registrar una secuencia

Ampliar una secuencia

Antes de emitir

Reglas

Permiso de la llave