# Listar recibos de nómina

> `GET https://api.cfdi.express/v1/nominas` — Lista los recibos de nómina con filtros por emisor, estatus, UUID, RFC del trabajador y fecha de pago, y con búsqueda libre (q). Paginación por cursor.

URL de esta página: https://cfdi.express/docs/api/listar-nominas
Autenticación: requiere API key (`Authorization: Bearer sk_test_…` o `sk_live_…`)
Header `x-account-id`: indica la cuenta. Si no eres miembro, la respuesta es 403.

Cada elemento es un recurso `nomina`.

Desde la v1.50.3, `q` es una búsqueda libre de hasta 100 caracteres. No distingue mayúsculas y se combina con los demás filtros de esta lista. Si lo omites, o va vacío, el listado no se filtra por texto. Encuentra por el RFC, el nombre o el número de empleado del trabajador (una subcadena basta: `CACX760510`, `XOCHILT` o `0042`), por un UUID parcial, o por el folio tal como se timbró. `WLC-1`, `WLC1` y `wlc 1` son la serie WLC con folio 1. `#1001` es el folio de cliente tal cual, y una subcadena de ese folio también entra: `1001` encuentra `#1001`. Una serie sola, como `WLC`, lista esa serie. El folio que coincide es el del XML: con folio de cliente, ese texto es el que cuenta; el consecutivo interno entra cuando el recibo se timbró sin folio de cliente.

### Query string

| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| `limit` | integer | no | Elementos por página. Entre 1 y 100. Default 10. |
| `starting_after` | string | no | Id del último recibo de la página anterior (cursor), mientras has_more sea true. |
| `q` | string | no | Búsqueda libre, opcional, máximo 100 caracteres. Desde la v1.50.3. RFC, nombre o número de empleado del trabajador, UUID parcial, o el folio tal como se timbró (WLC-1, WLC1 o #1001). |
| `merchantId` | string | no | Filtra por emisor. |
| `status` | string | no | stamping, stamped, stamp_failed, cancel_pending o cancelled. |
| `uuid` | string | no | Busca por folio fiscal (UUID) del SAT. |
| `employeeRfc` | string | no | RFC de un trabajador. |
| `fechaPagoFrom` | string | no | Fecha de pago desde, inclusive. Formato YYYY-MM-DD. |
| `fechaPagoTo` | string | no | Fecha de pago hasta, inclusive. Formato YYYY-MM-DD. |
| `createdFrom` | string | no | Fecha ISO 8601 mínima de creación. |
| `createdTo` | string | no | Fecha ISO 8601 máxima de creación. |

## Ejemplos

### cURL — por RFC

```bash
curl -G https://api.cfdi.express/v1/nominas \
  -H "Authorization: Bearer sk_test_..." \
  --data-urlencode "q=CACX7605101P8"
```

### cURL — por UUID parcial

```bash
curl -G https://api.cfdi.express/v1/nominas \
  -H "Authorization: Bearer sk_test_..." \
  --data-urlencode "q=9f1b2c3d"
```

### cURL — por folio

```bash
curl -G https://api.cfdi.express/v1/nominas \
  -H "Authorization: Bearer sk_test_..." \
  --data-urlencode "q=WLC-1"
```

## Respuesta

### 200 OK

```json
{
  "object": "list",
  "data": [
    {
      "id": "nom7k3q9x2m4v1t8p6d0n5cb",
      "object": "nomina",
      "livemode": false,
      "status": "stamped",
      "merchantId": "mkq2f8v3x1t7p9d4n6c0b5rz",
      "uuid": "9f1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
      "serie": "WLC",
      "folio": 1,
      "folioText": null,
      "tipoNomina": "O",
      "fechaPago": "2026-10-15",
      "employee": {
        "rfc": "CACX7605101P8",
        "name": "XOCHILT CASAS CHAVEZ",
        "numEmpleado": "0042"
      },
      "total": 8500.00,
      "currency": "MXN",
      "files": { "status": "ready" },
      "createdAt": "2026-10-15T18:00:08.907Z"
    }
  ],
  "has_more": false
}
```

## Errores

| Status | code | Cuándo aparece |
|---|---|---|
| 401 | `unauthorized` | Falta el header Authorization o la llave es inválida. |
| 429 | `rate_limited` | Excediste el límite de requests por minuto de tu cuenta (300 por default). La respuesta incluye Retry-After. |

---

Referencia completa: https://cfdi.express/docs/api · OpenAPI: https://api.cfdi.express/openapi.json · Llaves: https://dash.cfdi.express