# Timbrar (/docs/developers/api-reference/payroll-calculation/stamp)

## Descripcion general [#descripcion-general]

Este endpoint **timbra** ante el SAT (CFDI de nómina) los recibos de un periodo cerrado. Cerrar el periodo no timbra nada: el timbrado es un paso aparte.

Cada llamada crea un **lote de timbrado** con los recibos que aún no se enviaron y responde de inmediato; se timbran en segundo plano. Un recibo con error se reintenta desde la bandeja de timbrado.

Todos los recibos del lote llevan la **fecha de pago** que envías. Si no la envías, se toma la fecha de pago del periodo.

Requiere que la API key tenga el permiso **Timbrar nómina**. Las API keys con **Cerrar nómina** lo recibieron al agregarse este endpoint.

## Endpoint [#endpoint]

`POST https://app.integranom.com/api/v1/payroll-calendars/{payroll_calendar_number}/periods/{period_number}/stamp`

**Path params:**

* `payroll_calendar_number`: entero positivo, el número del calendario.
* `period_number`: el periodo, con el formato `{fiscal_year}-{sequence_number}` (por ejemplo `2026-14`).

**Body (opcional):**

* `payment_date`: fecha de pago de los recibos, con el formato `YYYY-MM-DD`.

## Inicia el timbrado del periodo [#inicia-el-timbrado-del-periodo]

***

Crea el lote de timbrado con los recibos pendientes del periodo y los envía al SAT en segundo plano.

## Campos de la respuesta [#campos-de-la-respuesta]

| Campo                | Tipo           | Descripcion                           |
| -------------------- | -------------- | ------------------------------------- |
| `period_number`      | string         | El periodo timbrado.                  |
| `payroll_run_number` | integer        | Número de la corrida.                 |
| `stamping_batch_id`  | string         | Identificador del lote de timbrado.   |
| `payment_date`       | string (fecha) | Fecha de pago que llevan los recibos. |
| `receipt_count`      | integer        | Recibos incluidos en el lote.         |

**cURL**

```bash
curl -X POST "https://app.integranom.com/api/v1/payroll-calendars/1/periods/2026-14/stamp" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "payment_date": "2026-07-31" }'
```

**Respuesta**

```json
{
"period_number": "2026-14",
"payroll_run_number": 14,
"stamping_batch_id": "6f1c2a8e-3b0d-4c55-9a51-2f7d0e9b4c11",
"payment_date": "2026-07-31",
"receipt_count": 48
}
```

## Errores [#errores]

| Status | Código             | Causa                                                                                                                |
| ------ | ------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `400`  |                    | `payroll_calendar_number` o `period_number` inválidos en la URL, o `payment_date` no es una fecha válida.            |
| `401`  |                    | API key ausente o inválida.                                                                                          |
| `403`  |                    | La API key no tiene el permiso **Timbrar nómina**, o el periodo es de una razón social fuera de su alcance.          |
| `404`  |                    | El calendario o el periodo no existen en esta organización.                                                          |
| `409`  | `NOT_CALCULATED`   | El periodo no está calculado (o nunca se abrió).                                                                     |
| `409`  | `NOT_CLOSED`       | El periodo no está cerrado. Ciérralo primero con [cerrar](/docs/developers/api-reference/payroll-calculation/close). |
| `409`  | `NOTHING_TO_STAMP` | Todos los recibos del periodo ya se enviaron a timbrar.                                                              |