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

# Series y folios

> Cómo Timbrix numera tus facturas: series por tipo de comprobante, folio automático o manual, y qué esperar cuando algo falla

Cada factura lleva una **serie** y un **folio**, por ejemplo `A-15`. Es tu numeración interna: la ves en el PDF y te sirve para encontrar la factura. Timbrix la asigna por ti, para que no tengas que llevar la cuenta.

## Qué es una serie

Una serie es una letra o un nombre corto (`A`, `NC`, `FAC`) que agrupa facturas con su propio contador de folios. Cada serie lleva dos contadores: uno para **producción** y otro para **sandbox**, así tus pruebas nunca gastan los folios de tus facturas reales.

Al crear una organización, Timbrix te deja listo esto:

| Serie | Se usa para | Primer folio |
| - | - | - |
| `A` | Ingreso y Traslado | 1 |
| `NC` | Egreso (nota de crédito) | 1 |
| `P` | Pago (complemento de pago) | 1 |

Si tu organización ya existía, sus series se crearon a partir de lo que ya habías emitido, para que el siguiente folio continúe donde te quedaste.

## Serie predeterminada por tipo

Cada tipo de comprobante (Ingreso, Egreso, Traslado y Pago) tiene una **serie predeterminada**. Es la que Timbrix usa cuando no indicas ninguna. Puedes cambiarla cuando quieras, por ejemplo para que tus ingresos salgan con la serie `FAC` en lugar de `A`.

Una serie predeterminada no se puede eliminar. Primero elige otra serie como predeterminada de ese tipo.

## Folio automático o manual

Al crear una factura o un complemento de pago, `series` y `folioNumber` son opcionales:

| Qué envías | Qué hace Timbrix |
| - | - |
| Nada | Usa la serie predeterminada del tipo y el siguiente folio libre de esa serie |
| Solo la serie | Usa esa serie (debe existir) y su siguiente folio libre |
| Serie y folio | Usa exactamente ese folio. No mueve el contador de la serie |

El folio manual sirve, por ejemplo, para registrar una factura que ya numeraste en otro sistema. Como no mueve el contador, el siguiente folio automático sigue su curso. Debe tener de 1 a 40 caracteres y no puede contener `|`.

```typescript theme={null}
import { Timbrix } from "@timbrix/sdk"

const client = new Timbrix({ apiKey: "<your_api_key>" })

// Sin serie ni folio: Timbrix asigna ambos
const invoice = await client.invoices.create({
  date: "2026-08-29T12:00:00",
  paymentForm: "03",
  use: "G03",
  customerId: "123e4567-e89b-12d3-a456-426614174000",
  items: [/* ... */],
})
console.log(`${invoice.series}-${invoice.folioNumber}`)
```

## No se repiten folios

Una misma serie y folio solo se pueden usar una vez por organización y ambiente, **aunque la factura original esté cancelada**. Si envías un folio que ya existe, Timbrix responde `409` con el código `FOLIO_ALREADY_USED` y el mensaje `La factura A-15 ya existe.`

El contador automático se salta los folios ya usados, así que moverlo hacia atrás nunca genera un duplicado.

Si reintentas una solicitud con la misma `idempotencyKey`, Timbrix te devuelve la factura original y no gasta otro folio.

## Saltos de folio

Si un timbrado falla, el folio automático que se le asignó se da por usado y la siguiente factura toma el que sigue. Verás entonces un salto en tu numeración (por ejemplo `A-14` y luego `A-16`). Es normal: el SAT no exige que los folios sean consecutivos.

## Sandbox y producción

Los contadores de sandbox y producción son independientes. Puedes reiniciar el de sandbox a `1` cuando quieras sin afectar tu numeración real.

## Dónde administrarlas

En el panel, entra a **Configuración > Series y folios**. Ahí puedes ver el siguiente folio de cada serie, crear series nuevas, ajustar el siguiente folio (por ejemplo, si vienes de otro sistema y quieres continuar tu numeración), elegir la serie predeterminada de cada tipo y eliminar las que ya no uses.

Cualquier miembro de la organización puede ver las series. Solo el Owner y los Admin pueden crearlas, cambiarlas o eliminarlas. Estas acciones requieren iniciar sesión en el panel o con un token de usuario; las API keys no pueden modificar series.

## Desde la API, el SDK y la CLI

| Acción | API | SDK | CLI |
| - | - | - | - |
| Ver series | [GET series](https://docs.timbrix.mx/api-reference/series/list.md) | `client.series.list` | `timbrix series list` |
| Crear una serie | [POST series](https://docs.timbrix.mx/api-reference/series/create.md) | `client.series.create` | `timbrix series create` |
| Cambiar el siguiente folio | [PUT series](https://docs.timbrix.mx/api-reference/series/update.md) | `client.series.update` | `timbrix series update` |
| Eliminar una serie | [DELETE series](https://docs.timbrix.mx/api-reference/series/delete.md) | `client.series.delete` | `timbrix series delete` |
| Elegir la serie predeterminada | [PUT default-series](https://docs.timbrix.mx/api-reference/series/set-default.md) | `client.series.setDefault` | `timbrix series default` |

## Errores frecuentes

| Código | Estado | Qué significa |
| - | - | - |
| `FOLIO_ALREADY_USED` | 409 | Esa serie y folio ya existen (incluso en una factura cancelada) |
| `SERIES_NOT_FOUND` | 404 | Enviaste una serie sin folio y esa serie no existe |
| `SERIES_ALREADY_EXISTS` | 409 | Ya tienes una serie con ese nombre |
| `SERIES_IS_DEFAULT` | 409 | La serie es la predeterminada de un tipo; elige otra antes de eliminarla |


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