Listar recibos de nómina

GEThttps://api.cfdi.express/v1/nominasAPI key

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.

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.

Autenticación

Authorization: Bearer sk_test_... | sk_live_...

El header x-account-id indica la cuenta. Si no eres miembro, la respuesta es 403.

Parámetros

Query string

Campo	Tipo	Descripción
limit	integer	Elementos por página. Entre 1 y 100. Default 10.
starting_after	string	Id del último recibo de la página anterior (cursor), mientras has_more sea true.
q	string	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	Filtra por emisor.
status	string	stamping, stamped, stamp_failed, cancel_pending o cancelled.
uuid	string	Busca por folio fiscal (UUID) del SAT.
employeeRfc	string	RFC de un trabajador.
fechaPagoFrom	string	Fecha de pago desde, inclusive. Formato YYYY-MM-DD.
fechaPagoTo	string	Fecha de pago hasta, inclusive. Formato YYYY-MM-DD.
createdFrom	string	Fecha ISO 8601 mínima de creación.
createdTo	string	Fecha ISO 8601 máxima de creación.

Ejemplos

cURL — por RFC

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

cURL — por UUID parcial

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

cURL — por folio

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

Respuesta

200 OK

{
  "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.