> ## Documentation Index
> Fetch the complete documentation index at: https://dev.acpay.do/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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:

```bash theme={null}
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.

```json theme={null}
{
  "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.

> [!NOTE]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.