--- title: "Actualizar recibo de nómina" description: "Cambia un recibo antes de timbrarlo. excluded true lo omite (también uno rechazado, cuyo borrador se elimina); desde entonces se lee omitted: true y queda fuera, aunque su empleado salga de la nómina y vuelva, hasta que excluded false lo vuelve a incluir; manual reemplaza sus importes por percepciones, deducciones, otros pagos y, si se envían, días pagados capturados; source calculated descarta los importes capturados y lo recalcula. Un concepto capturado que requiere un nodo del complemento (horas extra, acciones, incapacidad, separación, jubilación, compensación) devuelve 400; timbra ese recibo de forma individual. Devuelve 409 conflict en cuanto el recibo está en cola, timbrándose o timbrado." language: es-MX canonical_url: "https://exac.mx/docs/api/documents/payroll/update-payroll-row" md_url: "https://exac.mx/docs/api/documents/payroll/update-payroll-row.md" --- # Actualizar recibo de nómina Cambia un recibo antes de timbrarlo. excluded true lo omite (también uno rechazado, cuyo borrador se elimina); desde entonces se lee omitted: true y queda fuera, aunque su empleado salga de la nómina y vuelva, hasta que excluded false lo vuelve a incluir; manual reemplaza sus importes por percepciones, deducciones, otros pagos y, si se envían, días pagados capturados; source calculated descarta los importes capturados y lo recalcula. Un concepto capturado que requiere un nodo del complemento (horas extra, acciones, incapacidad, separación, jubilación, compensación) devuelve 400; timbra ese recibo de forma individual. Devuelve 409 conflict en cuanto el recibo está en cola, timbrándose o timbrado. ## Solicitud `PATCH /v1/payroll/rows/{rowId}` - **Autorización:** Permiso requerido: `employees:manage`. - **Entornos:** Producción y prueba - **Idempotencia:** 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": "PATCH", "path": "/v1/payroll/rows/{rowId}", "operation": { "operationId": "updatePayrollRow", "tags": [ "Payroll" ], "summary": "Actualizar recibo de nómina", "description": "Cambia un recibo antes de timbrarlo. excluded true lo omite (también uno rechazado, cuyo borrador se elimina); desde entonces se lee omitted: true y queda fuera, aunque su empleado salga de la nómina y vuelva, hasta que excluded false lo vuelve a incluir; manual reemplaza sus importes por percepciones, deducciones, otros pagos y, si se envían, días pagados capturados; source calculated descarta los importes capturados y lo recalcula. Un concepto capturado que requiere un nodo del complemento (horas extra, acciones, incapacidad, separación, jubilación, compensación) devuelve 400; timbra ese recibo de forma individual. Devuelve 409 conflict en cuanto el recibo está en cola, timbrándose o timbrado.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "rowId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "rowId of a receipt, as listed in its run's receipts." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Clave estable para reintentar exactamente la misma solicitud sin duplicar efectos." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "excluded": { "type": "boolean", "description": "Omitir (true) or include again (false) this receipt." } }, "required": [ "excluded" ], "additionalProperties": false }, { "type": "object", "properties": { "manual": { "type": "object", "properties": { "paidDays": { "description": "NumDiasPagados, up to three decimals; omitted, the days the calculation pays, or the frequency's days for the days employed.", "type": "number", "minimum": 0.001, "maximum": 36160, "multipleOf": 0.001 }, "earnings": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 3, "maxLength": 15, "description": "The employer's clave for the concept, 3 to 15 characters." }, "description": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "description": "Known SAT payroll earning-type code.", "x-exac-sat-catalog": "payroll-earning-types", "oneOf": [ { "type": "string", "title": "SAT c_TipoPercepcion", "description": "Consulta códigos y nombres vigentes [aquí](/docs/sat-catalogs/payroll#payroll-earning-types).", "enum": [ "001", "002", "003", "004", "005", "006", "009", "010", "011", "012", "013", "014", "015", "019", "020", "021", "022", "023", "024", "025", "026", "027", "028", "029", "030", "031", "032", "033", "034", "035", "036", "037", "038", "039", "044", "045", "046", "047", "048", "049", "050", "051", "052", "053", "054", "055", "056", "057" ] } ] }, "taxableAmount": { "type": "number", "minimum": 0, "exclusiveMaximum": 1000000000000000000, "multipleOf": 0.01 }, "exemptAmount": { "type": "number", "minimum": 0, "exclusiveMaximum": 1000000000000000000, "multipleOf": 0.01 } }, "required": [ "code", "type", "taxableAmount", "exemptAmount" ], "additionalProperties": false } }, "deductions": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 3, "maxLength": 15, "description": "The employer's clave for the concept, 3 to 15 characters." }, "description": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "description": "Known SAT payroll deduction-type code.", "x-exac-sat-catalog": "payroll-deduction-types", "oneOf": [ { "type": "string", "title": "SAT c_TipoDeduccion", "description": "Consulta códigos y nombres vigentes [aquí](/docs/sat-catalogs/payroll#payroll-deduction-types).", "enum": [ "100", "101", "102", "103", "104", "105", "106", "107", "108", "109", "110", "111", "112", "113", "114", "115", "001", "002", "003", "004", "005", "006", "007", "008", "009", "010", "011", "012", "013", "014", "015", "016", "017", "018", "019", "020", "021", "022", "023", "024", "025", "026", "027", "028", "029", "030", "031", "032", "033", "034", "035", "036", "037", "038", "039", "040", "041", "042", "043", "044", "045", "046", "047", "048", "049", "050", "051", "052", "053", "054", "055", "056", "057", "058", "059", "060", "061", "062", "063", "064", "065", "066", "067", "068", "069", "070", "071", "072", "073", "074", "075", "076", "077", "078", "079", "080", "081", "082", "083", "084", "085", "086", "087", "088", "089", "090", "091", "092", "093", "094", "095", "096", "097", "098", "099" ] } ] }, "amount": { "type": "number", "minimum": 0, "exclusiveMaximum": 1000000000000000000, "multipleOf": 0.01 } }, "required": [ "code", "type", "amount" ], "additionalProperties": false } }, "otherPayments": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 3, "maxLength": 15, "description": "The employer's clave for the concept, 3 to 15 characters." }, "description": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "description": "Known SAT payroll other-payment code.", "x-exac-sat-catalog": "payroll-other-payment-types", "oneOf": [ { "type": "string", "title": "SAT c_TipoOtroPago", "description": "Consulta códigos y nombres vigentes [aquí](/docs/sat-catalogs/payroll#payroll-other-payment-types).", "enum": [ "999", "001", "002", "003", "004", "005", "006", "007", "008", "009" ] } ] }, "amount": { "type": "number", "minimum": 0, "exclusiveMaximum": 1000000000000000000, "multipleOf": 0.01 }, "employmentSubsidy": { "type": "number", "minimum": 0, "exclusiveMaximum": 1000000000000000000, "multipleOf": 0.01 } }, "required": [ "code", "type", "amount" ], "additionalProperties": false } } }, "required": [ "earnings", "deductions", "otherPayments" ], "additionalProperties": false, "description": "Types that need a complement node (overtime, stock, incapacity, separation, pension, compensation) are refused; issue those receipts individually." } }, "required": [ "manual" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "calculated", "description": "Drop captured amounts and calculate from the employee's salary." } }, "required": [ "source" ], "additionalProperties": false } ] }, "example": { "excluded": true } } } }, "responses": { "200": { "description": "Operación completada.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PayrollRowDetail" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "rowId": "payroll-row-example", "runId": "payroll-run-example", "employeeId": "employee-example", "employeeName": "Persona Ejemplo", "employeeTaxId": "EJE010101AAA", "state": "excluded", "omitted": true, "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", "earnings": [ { "type": "001", "code": "001", "description": "Sueldo", "taxableAmount": 4291.37, "exemptAmount": 0 } ], "deductions": [ { "type": "001", "code": "001", "description": "IMSS", "amount": 105.68 }, { "type": "002", "code": "002", "description": "ISR", "amount": 268.41 } ], "otherPayments": [], "lastReceiptSalaryAvailable": 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:manage`.\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):.+$" }, "PayrollRowDetail": { "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" }, "earnings": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "description": { "type": "string" }, "taxableAmount": { "type": "number" }, "exemptAmount": { "type": "number" } }, "required": [ "type", "code", "taxableAmount", "exemptAmount" ], "additionalProperties": false } }, "deductions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "type", "code", "amount" ], "additionalProperties": false } }, "otherPayments": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "number" }, "employmentSubsidy": { "type": "number" } }, "required": [ "type", "code", "amount" ], "additionalProperties": false } }, "explanation": { "type": "object", "properties": { "paidDays": { "type": "number" }, "contributionDays": { "type": "number" }, "dailyWage": { "type": "number" }, "integratedDailySalary": { "type": "number" }, "contributionBaseSalary": { "type": "number" }, "isrCaused": { "type": "number" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "label", "amount" ], "additionalProperties": false } }, "rules": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "legalBasis": { "type": "string" }, "readOn": { "type": "string", "format": "date", "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])))$", "description": "The day it was read on: the payment date, the period's last day or, for the rules of SAT's validation matrix, the day the receipt is stamped." }, "validFrom": { "type": "string", "format": "date", "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])))$", "description": "The day its value took effect." }, "sourceUrl": { "description": "The official publication its value was read from.", "type": "string" } }, "required": [ "key", "label", "legalBasis", "readOn", "validFrom" ], "additionalProperties": false }, "description": "The tax rules this calculation read, each once." } }, "required": [ "paidDays", "contributionDays", "dailyWage", "integratedDailySalary", "contributionBaseSalary", "isrCaused", "lines", "rules" ], "additionalProperties": false }, "lastReceiptSalaryAvailable": { "type": "boolean", "description": "Whether the employee's last ordinary receipt states a salary the employee could take as theirs." } }, "required": [ "rowId", "runId", "employeeId", "employeeName", "state", "omitted", "source", "issues", "updatedAt", "earnings", "deductions", "otherPayments", "lastReceiptSalaryAvailable" ], "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 - [`save_payroll`](/docs/mcp/tools/save_payroll.md) Documentación completa: https://exac.mx/docs.md Índice para agentes: https://exac.mx/docs/llms.txt