---
title: "Listar recibos de nómina"
description: "Lista los recibos de una nómina por nombre del empleado, opcionalmente en un estado, con sus totales, los motivos por los que un recibo requiere atención (issues), si alguien lo omitió (omitted) y el documentRef del CFDI timbrado."
language: es-MX
canonical_url: "https://exac.mx/docs/api/documents/payroll/list-payroll-rows"
md_url: "https://exac.mx/docs/api/documents/payroll/list-payroll-rows.md"
---

# Listar recibos de nómina

Lista los recibos de una nómina por nombre del empleado, opcionalmente en un estado, con sus totales, los motivos por los que un recibo requiere atención (issues), si alguien lo omitió (omitted) y el documentRef del CFDI timbrado.

## Solicitud

`GET /v1/payroll/runs/{runId}/rows`

- **Autorización:** Permiso requerido: `employees:read`.

- **Entornos:** Producción y prueba

- **Idempotencia:** No requerida

## Contrato canónico para máquinas

Este fragmento se genera desde la operación canónica y los contratos Zod que utiliza la ruta.

```json
{
  "method": "GET",
  "path": "/v1/payroll/runs/{runId}/rows",
  "operation": {
    "operationId": "listPayrollRows",
    "tags": [
      "Payroll"
    ],
    "summary": "Listar recibos de nómina",
    "description": "Lista los recibos de una nómina por nombre del empleado, opcionalmente en un estado, con sus totales, los motivos por los que un recibo requiere atención (issues), si alguien lo omitió (omitted) y el documentRef del CFDI timbrado.",
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "parameters": [
      {
        "name": "runId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 1,
          "description": "runId of a payroll run, as prepared or listed."
        }
      },
      {
        "name": "cursor",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "minLength": 1
        }
      },
      {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        }
      },
      {
        "name": "state",
        "in": "query",
        "required": false,
        "schema": {
          "description": "Only receipts in this state.",
          "type": "string",
          "enum": [
            "ready",
            "needs_attention",
            "excluded",
            "queued",
            "stamping",
            "stamped",
            "rejected",
            "canceled"
          ]
        }
      }
    ],
    "responses": {
      "200": {
        "description": "Operación completada.",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PayrollRow"
                  }
                },
                "pagination": {
                  "$ref": "#/components/schemas/Pagination"
                }
              },
              "required": [
                "data",
                "pagination"
              ],
              "additionalProperties": false
            },
            "example": {
              "data": [
                {
                  "rowId": "payroll-row-example",
                  "runId": "payroll-run-example",
                  "employeeId": "employee-example",
                  "employeeName": "Persona Ejemplo",
                  "employeeTaxId": "EJE010101AAA",
                  "state": "ready",
                  "omitted": false,
                  "source": "calculated",
                  "issues": [],
                  "paidDays": 7,
                  "totals": {
                    "gross": 4291.37,
                    "deductions": 374.09,
                    "net": 3917.28,
                    "isr": 268.41,
                    "subsidy": 0,
                    "imss": 105.68
                  },
                  "updatedAt": "2026-09-21T15:00:05.000Z"
                }
              ],
              "pagination": {
                "nextCursor": null,
                "hasMore": false
              }
            }
          }
        }
      },
      "400": {
        "description": "Solicitud inválida.\n\n`validation_error`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "401": {
        "description": "Credencial inválida o ausente.\n\n`unauthenticated`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "WWW-Authenticate": {
            "$ref": "#/components/headers/WWWAuthenticate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "402": {
        "description": "Saldo prepagado insuficiente o requisito de facturación pendiente.\n\n`payment_required`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "403": {
        "description": "La credencial no incluye el permiso `employees:read`.\n\n`forbidden`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "WWW-Authenticate": {
            "$ref": "#/components/headers/WWWAuthenticate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "404": {
        "description": "Recurso no encontrado.\n\n`not_found`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "405": {
        "description": "Método no permitido.\n\n`method_not_allowed`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Allow": {
            "$ref": "#/components/headers/Allow"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "409": {
        "description": "Conflicto de estado, entorno o idempotencia. Usa error.code para decidir cómo recuperarte.\n\nCódigos posibles: `conflict`, `idempotency_conflict`, `operation_in_progress`, `recovery_required`, `migration_required`.",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "429": {
        "description": "Demasiadas solicitudes.\n\n`rate_limited`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "500": {
        "description": "Error interno del servidor.\n\n`internal`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "503": {
        "description": "Servicio temporalmente no disponible.\n\n`provider_unavailable`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      }
    },
    "x-exac-environments": [
      "production",
      "sandbox"
    ]
  },
  "components": {
    "schemas": {
      "ApiError": {
        "type": "object",
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ProgrammaticError"
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      },
      "ProgrammaticError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "validation_error",
              "unauthenticated",
              "forbidden",
              "payment_required",
              "not_found",
              "method_not_allowed",
              "conflict",
              "idempotency_conflict",
              "operation_in_progress",
              "recovery_required",
              "migration_required",
              "rate_limited",
              "provider_unavailable",
              "internal"
            ],
            "description": "Acción recomendada por código:\n\n- `validation_error` — Corrige la solicitud usando error.message y, cuando existan, los paths y códigos de details.issues.\n- `unauthenticated` — Proporciona una API key o un token de acceso OAuth válido.\n- `forbidden` — Usa una credencial con el permiso requerido.\n- `payment_required` — Si details.reason = api_wallet_insufficient, agrega saldo prepagado de API/MCP mediante details.topUpUrl; balanceMinor indica el saldo en centavos. En otros casos revisa el requisito de facturación. Reintenta solo después de resolverlo.\n- `not_found` — Verifica el identificador del recurso dentro de la organización.\n- `method_not_allowed` — Usa el método HTTP documentado.\n- `conflict` — Actualiza el recurso y resuelve su estado actual.\n- `idempotency_conflict` — Usa otra clave de idempotencia para una solicitud modificada.\n- `operation_in_progress` — Espera el tiempo de Retry-After y repite la misma solicitud.\n- `recovery_required` — No reintentes automáticamente ni cambies la clave de idempotencia. Consulta details.document.documentRef cuando exista, verifica el resultado y contacta a soporte con Request-Id si continúa incierto.\n- `migration_required` — Contacta a soporte para completar la migración histórica; no vuelvas a emitir el documento.\n- `rate_limited` — Espera el tiempo de Retry-After antes de reintentar.\n- `provider_unavailable` — Reintenta solo cuando la respuesta marque la falla como reintentable.\n- `internal` — Una respuesta fallida no demuestra que una escritura no tuvo efectos. Reintenta una lectura después de una espera; una escritura solo con su clave de idempotencia original y la solicitud sin cambios. Contacta a soporte con Request-Id si persiste."
          },
          "message": {
            "type": "string"
          },
          "details": {
            "type": "object",
            "properties": {
              "document": {
                "type": "object",
                "properties": {
                  "documentRef": {
                    "$ref": "#/components/schemas/DocumentRef"
                  },
                  "editable": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "documentRef",
                  "editable"
                ],
                "additionalProperties": false
              },
              "issues": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "path": {
                      "type": "array",
                      "items": {
                        "anyOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "number"
                          }
                        ]
                      }
                    },
                    "message": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "path",
                    "message"
                  ],
                  "additionalProperties": false
                }
              },
              "retryable": {
                "type": "boolean"
              },
              "retryAfterSeconds": {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 9007199254740991
              },
              "reason": {
                "type": "string"
              },
              "balanceMinor": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "topUpUrl": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "status": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "code",
          "message",
          "status"
        ],
        "additionalProperties": false
      },
      "DocumentRef": {
        "type": "string",
        "pattern": "^(invoice|withholding|sales_receipt|declaration|tax_compliance_opinion|sales_receipt_refund):.+$"
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "nextCursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "hasMore": {
            "type": "boolean"
          }
        },
        "required": [
          "nextCursor",
          "hasMore"
        ],
        "additionalProperties": false
      },
      "PayrollRow": {
        "type": "object",
        "properties": {
          "rowId": {
            "type": "string"
          },
          "runId": {
            "type": "string"
          },
          "employeeId": {
            "type": "string"
          },
          "employeeName": {
            "type": "string"
          },
          "employeeTaxId": {
            "description": "Absent once the employee was deleted.",
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "ready",
              "needs_attention",
              "excluded",
              "queued",
              "stamping",
              "stamped",
              "rejected",
              "canceled"
            ]
          },
          "omitted": {
            "type": "boolean",
            "description": "True while a person omitted the receipt (state excluded): it stays out of the nómina, also when its employee leaves the roster and returns, until a person includes it again."
          },
          "source": {
            "type": "string",
            "enum": [
              "calculated",
              "manual"
            ]
          },
          "issues": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "$ref": "#/components/schemas/PayrollIssueCode"
                },
                "field": {
                  "type": "string"
                }
              },
              "required": [
                "code"
              ],
              "additionalProperties": false
            }
          },
          "paidDays": {
            "type": "number"
          },
          "totals": {
            "type": "object",
            "properties": {
              "gross": {
                "type": "number"
              },
              "deductions": {
                "type": "number"
              },
              "net": {
                "type": "number"
              },
              "isr": {
                "type": "number"
              },
              "subsidy": {
                "type": "number"
              },
              "imss": {
                "type": "number"
              }
            },
            "required": [
              "gross",
              "deductions",
              "net",
              "isr",
              "subsidy",
              "imss"
            ],
            "additionalProperties": false
          },
          "documentRef": {
            "type": "string"
          },
          "uuid": {
            "type": "string"
          },
          "rejectionCode": {
            "type": "string"
          },
          "errorCode": {
            "$ref": "#/components/schemas/PayrollIssueCode"
          },
          "updatedAt": {
            "$ref": "#/components/schemas/Instant"
          }
        },
        "required": [
          "rowId",
          "runId",
          "employeeId",
          "employeeName",
          "state",
          "omitted",
          "source",
          "issues",
          "updatedAt"
        ],
        "additionalProperties": false
      },
      "Instant": {
        "type": "string",
        "format": "date-time",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
      },
      "PayrollIssueCode": {
        "type": "string",
        "enum": [
          "rfc_invalid",
          "tax_system_invalid",
          "postal_code_invalid",
          "curp_invalid",
          "employee_number_invalid",
          "contract_type_invalid",
          "regime_type_invalid",
          "payment_frequency_invalid",
          "unsupported_regime",
          "unsupported_contract",
          "unsupported_frequency",
          "state_code_missing",
          "social_security_number_missing",
          "employment_start_missing",
          "position_risk_missing",
          "integrated_daily_salary_missing",
          "bank_account_invalid",
          "job_title_invalid",
          "department_invalid",
          "work_schedule_type_invalid",
          "contribution_base_salary_invalid",
          "salary_missing",
          "salary_below_minimum_wage",
          "minimum_wage_zone_missing",
          "employer_rfc_missing",
          "employer_registration_missing",
          "employer_curp_missing",
          "invalid_salary",
          "not_employed_in_period",
          "sdi_below_daily_wage",
          "rules_unavailable",
          "negative_net",
          "employee_missing",
          "not_in_roster",
          "period_already_paid",
          "subsidy_line_invalid",
          "subsidy_ceiling_exceeded",
          "subsidy_month_cap_exceeded",
          "invalid_request",
          "amounts_changed",
          "stamp_failed",
          "stamp_unconfirmed"
        ]
      }
    }
  }
}
```

[OpenAPI 3.1](/openapi.json)

## Herramientas MCP equivalentes

- [`get_payroll`](/docs/mcp/tools/get_payroll.md)

Documentación completa: https://exac.mx/docs.md
Índice para agentes: https://exac.mx/docs/llms.txt