# Numeración de facturas

Entiende cuándo asigna FiscalRail los números de factura y elige numeración por cuenta o por cliente.

## 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](/en/api/invoice-series) 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

| Documento | Numeración por cuenta | Numeración por cliente |
| --- | --- | --- |
| Primera factura del cliente A | `INV-00001` | `INV-A-00001` |
| Segunda factura del cliente A | `INV-00002` | `INV-A-00002` |
| Primera factura del cliente B | `INV-00003` | `INV-B-00001` |
| Tercera factura del cliente A | `INV-00004` | `INV-A-00003` |
| Factura rectificativa para el cliente A | `CN-00001` | `CN-A-00001` |
| Segunda factura del cliente B | `INV-00005` | `INV-B-00002` |
| Factura rectificativa para el cliente B | `CN-00002` | `CN-B-00001` |
| Factura sin cliente | `INV-00006` | `INV-00001` |

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:

```bash
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:

```bash
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](/es/tax-regimes/spain#numeracion-de-facturas).

Consulta [Idempotencia](/en/api/idempotency), [Cuentas](/en/api/accounts), [Clientes](/en/api/customers) y [Facturas](/en/api/invoices) para ver el contrato completo de la API.