Endpoints
Secuencias NCF

Secuencias NCF (e-CF)

Gestiona las secuencias de comprobantes fiscales electrónicos (NCF electrónicos / e-CF) de tu empresa por programación — lo mismo que haces manualmente en el portal bajo Secuencias, ahora vía API.

MétodoPathPara qué
GET/ncfListar tus secuencias + tipos disponibles
POST/ncfCrear o editar una secuencia (upsert por prefijo)
DELETE/ncf/:prefixEliminar la secuencia de un prefijo

Todos requieren Authorization: Bearer <JWT>.

🔑

El worker sólo necesita una secuencia ACTIVA por prefijo para resolver la FechaVencimientoSecuencia (fecha de vencimiento) al firmar tus e-CF. Tú mandas el eNCF completo en cada POST /invoices; esta API es donde registras el rango autorizado por DGII y su vencimiento.

¿Por qué gestionar secuencias por API?

Si provisionas tenants o sucursales de forma automatizada (POS/ERP, onboarding self-service, scripts de despliegue), estos endpoints te evitan entrar al portal a mano: creas las secuencias E31, E32, … junto con el resto del alta del cliente.

Tipos de e-CF (prefijos)

Para comprobantes electrónicos el prefijo ES el tipo — type === prefix. Sólo se aceptan estos prefijos:

PrefijoTipo de documento
E31Factura de Crédito Fiscal
E32Factura de Consumo
E33Nota de Débito Electrónica
E34Nota de Crédito Electrónica
E41Compras
E43Gastos Menores
E44Régimen Especial
E45Gubernamental
E46Comprobante de Pago al Exterior
E47Régimen Especial de Pago al Exterior

Cualquier otro prefijo → 400 Bad Request.

GET /ncf

Lista todas las secuencias electrónicas del tenant y, por conveniencia, el catálogo de tipos disponibles.

GET /api/v1/fe/ncf
Authorization: Bearer <JWT>

Scope requerido: ncf:read

Response — 200 OK

{
  "availableTypes": [
    { "code": "E31", "name": "Factura de Crédito Fiscal" },
    { "code": "E32", "name": "Factura de Consumo" }
    /* ... el resto de tipos ... */
  ],
  "items": [
    {
      "id": "9e5c8010-fa9a-4190-9c3c-d727aa99b26c",
      "type": "E31",
      "prefix": "E31",
      "description": "Factura de Crédito Fiscal",
      "minSequence": "1",
      "maxSequence": "9999999999",
      "currentSequence": "1",
      "isActive": true,
      "expireAt": "2026-12-31T00:00:00.000Z"
    }
    /* ... una entry por secuencia configurada ... */
  ]
}
CampoDescripción
type / prefixEl prefijo e-CF. Para electrónicos, iguales.
minSequencePrimer número de la secuencia autorizada (string).
maxSequenceÚltimo número autorizado (string).
currentSequencePróximo número a consumir (string).
isActivefalse = configurada pero ignorada por el worker.
expireAtVencimiento de la secuencia (ISO 8601) o null.

minSequence, maxSequence y currentSequence vienen como strings porque el rango llega hasta 9999999999, cerca de Number.MAX_SAFE_INTEGER. Conviértelos a BigInt si necesitas operar con ellos.

POST /ncf

Upsert por prefijo. Si el prefijo aún no existe, lo crea; si ya lo tienes, lo actualiza en su lugar. Es idempotente — no necesitas conocer ningún id interno, el prefix es la clave natural.

POST /api/v1/fe/ncf
Authorization: Bearer <JWT>
Content-Type: application/json

Scope requerido: ncf:write

Request body

CampoTipoRequeridoDefaultDescripción
prefixstring✅—Uno de E31…E47
minSequencenumber❌1Inicio del rango (1…9999999999)
maxSequencenumber❌9999999999Fin del rango (≥ minSequence)
expireAtISO date❌nullVencimiento (YYYY-MM-DD o ISO completo)
isActiveboolean❌truefalse para dejarla inactiva
{
  "prefix": "E31",
  "minSequence": 1,
  "maxSequence": 9999999999,
  "expireAt": "2026-12-31",
  "isActive": true
}
✍️

El mínimo es sólo { "prefix": "E31" }. Rellenamos minSequence=1, maxSequence=9999999999, expireAt=null, isActive=true por ti.

Comportamiento del rango

  • Si maxSequence < minSequence → 400.
  • Al editar, si el currentSequence actual queda fuera del nuevo rango, lo ajustamos al borde más cercano (nunca lo dejamos inválido).
  • Al crear, currentSequence arranca en minSequence.

Response — 200 OK

Devuelve la secuencia resultante (misma forma que un item de GET /ncf):

{
  "id": "9e5c8010-fa9a-4190-9c3c-d727aa99b26c",
  "type": "E31",
  "prefix": "E31",
  "description": "Factura de Crédito Fiscal",
  "minSequence": "1",
  "maxSequence": "9999999999",
  "currentSequence": "1",
  "isActive": true,
  "expireAt": "2026-12-31T00:00:00.000Z"
}

Response — 400 Bad Request

{
  "message": "prefix debe ser un tipo e-CF válido (E31, E32, … E47)",
  "statusCode": 400
}

Otros 400 comunes:

  • La secuencia máxima debe ser mayor o igual a la mínima.
  • Tipo de e-CF inválido.

DELETE /ncf/:prefix

Elimina la secuencia de un prefijo. Sólo afecta secuencias de tu tenant — nunca podrás borrar la de otro aunque adivines un prefijo.

DELETE /api/v1/fe/ncf/E31
Authorization: Bearer <JWT>

Scope requerido: ncf:write

Path params

CampoTipoDescripción
prefixstringUno de E31…E47

Response — 200 OK

{
  "ok": true,
  "prefix": "E31"
}

Response — 404 Not Found

{
  "message": "No existe una secuencia NCF para el prefijo E31.",
  "statusCode": 404
}
⚠️

Eliminar una secuencia no revoca los e-CF ya emitidos con ella, pero el worker dejará de poder resolver su vencimiento en emisiones futuras de ese prefijo hasta que la vuelvas a crear. Bórrala sólo si de verdad ya no vas a emitir ese tipo.

Scopes y keys existentes

Los endpoints NCF usan dos scopes nuevos:

ScopeOtorga
ncf:readGET /ncf
ncf:writePOST /ncf, DELETE /ncf/:prefix
🔓

No necesitas recrear tus keys. Al hacer POST /login, el JWT hereda los scopes NCF a partir de la capacidad de facturación de la key: una key con invoices:write recibe ncf:read + ncf:write; una key de sólo lectura (invoices:read) recibe ncf:read. Revisa el array scopes en la respuesta de /login para confirmar lo que tu key puede hacer.

Ver también: Autenticación → Scopes, POST /invoices (donde consumes estas secuencias).

InvoicesGET /usage