Numeración de facturas

Cuándo se asigna el número

FiscalRail asigna el código definitivo cuando la factura se emite correctamente. Tu integración puede seleccionar una serie de facturación; si no lo hace, FiscalRail utiliza la serie predeterminada de la cuenta para esa operación.

FiscalRail garantiza que:

• los números son correlativos dentro de cada serie;
• dos peticiones concurrentes no reciben el mismo código;
• los intentos de emisión rechazados o revertidos quedan sin numerar; y
• el código de una factura emitida nunca cambia.

El code asignado se devuelve en la factura. Guarda ese valor en lugar de predecir el siguiente número en tu aplicación. Para reintentar una emisión cuyo resultado sea incierto, envía exactamente el mismo cuerpo con el mismo Idempotency-Key; FiscalRail devolverá la factura original en vez de emitir otra.

Series de facturación

Cada factura pertenece a una serie. La serie proporciona el prefijo de códigos como INV-00001 o CN-00001 y permite numerar por separado distintos tipos de documentos fiscales.

Tu cuenta define series predeterminadas para facturas ordinarias, facturas rectificativas y rectificaciones por sustitución. La emisión utiliza la serie predeterminada aplicable salvo que envíes el ID de otra serie en series.

Los prefijos contienen como máximo 20 letras mayúsculas o dígitos. Se vuelven inmutables después de la primera factura y una serie utilizada no se puede eliminar. Las cuentas Test añaden automáticamente el marcador reservado TEST-.

Consulta Series de facturación para crear series y asignar los valores predeterminados de la cuenta.

Numeración por cuenta y por cliente

El campo invoice_numbering_scope de la cuenta determina si cada serie se numera para toda la cuenta o por separado para cada cliente. account es el valor predeterminado. customer impide que un cliente sepa cuántas facturas has emitido a todos los demás.

Compara los dos modos

Con la numeración por cliente, FiscalRail combina el prefijo de la serie seleccionada con el invoice_prefix del cliente. Todos los clientes ya tienen un prefijo generado de seis letras, por lo que activar este modo no requiere una migración. Puedes proporcionar un prefijo personalizado al crear el cliente o actualizarlo antes de emitir su primera factura. A partir de entonces queda inmutable.

Las facturas sin cliente siguen utilizando la numeración por cuenta. El ámbito seleccionado se aplica de forma uniforme a todas las series configuradas.

La API de emisión no cambia

Continúas identificando el cliente y, de forma opcional, la serie exactamente igual que antes:

curl https://api.fiscalrail.com/v1/invoices \
  --request POST \
  --header "Authorization: Bearer $FISCALRAIL_API_KEY" \
  --header "Idempotency-Key: 2f294ef2-9a60-4c7e-a573-5e18fa8348e2" \
  --header "Content-Type: application/json" \
  --data '{
    "customer": "cus_...",
    "lines": [{
      "description": "Consultoría",
      "quantity": "2",
      "unit_price": "75.00",
      "taxes": [{"tax": "vat", "rule": "general"}]
    }]
  }'

FiscalRail elige el código correcto y lo devuelve en la factura emitida. No tienes que crear un recurso InvoiceSeries distinto para cada cliente ni cambiar ningún parámetro de la factura.

Activa la numeración por cliente

En el Dashboard, abre Configuración → Series, elige Una secuencia distinta por cliente en Numeración y guarda los cambios.

También puedes actualizar la cuenta mediante la API:

curl https://api.fiscalrail.com/v1/accounts/$ACCOUNT_ID \
  --request PATCH \
  --header "Authorization: Bearer $FISCALRAIL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"invoice_numbering_scope":"customer"}'

El cambio solo afecta a facturas futuras. Al volver a account, se reanuda la numeración anterior de la cuenta; al reactivar customer, se reanuda la numeración anterior de cada cliente. Los códigos emitidos nunca cambian.

Implicaciones del régimen fiscal

Algunos regímenes fiscales regulan cuándo se pueden utilizar series de facturación separadas. FiscalRail mantiene sus garantías de numeración, inmutabilidad y registros fiscales en ambos modos, pero el motivo para elegir series separadas por cliente forma parte de tu política de facturación.

Consulta la guía del régimen fiscal de tu cuenta antes de activar la numeración por cliente. Para cuentas españolas, consulta Numeración de facturas en el régimen fiscal de España.

Consulta Idempotencia, Cuentas, Clientes y Facturas para ver el contrato completo de la API.