Secuencias de e-NCF

Registra y amplía por el API los rangos de e-NCF que te autorizó la DGII.

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.