MCP serverAvailable tools
Save payroll
Prepare or adjust payroll before stamping: change payroll settings (only the fields sent change; null clears one), prepare the run of a pay period (idempotent per period; receipts calculate in the background), change its payment date, recalculate it, or update one receipt (omit or include it, capture its amounts, or return it to the calculation), or prepare a canceled receipt again.
MCP tool
save_payrollPurpose
Prepare a pay period and adjust its receipts before they are stamped.
- Use when
- A run must be prepared, recalculated, or dated, or a receipt omitted, included, captured, or prepared again.
- Do not use when
- The receipts are ready to stamp, or you need to change employee data; use save_employee and then recalculate.
- Required permissions
- Side effects
- Writes data
- Idempotency
- Idempotent
Input schema
JSON Schema{ "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Unique retry key for this exact operation. Reuse it only when retrying the same request." }, "input": { "oneOf": [ { "type": "object", "properties": { "operation": { "const": "update_settings" }, "minimumWageZone": { "anyOf": [ { "enum": [ "general", "northBorder" ], "description": "Minimum wage zone the employer confirmed; unset, employees without their own zone are not calculated." }, { "type": "null" } ] }, "defaultRiskClass": { "anyOf": [ { "enum": [ "1", "2", "3", "4", "5", "99" ], "description": "RiesgoPuesto for employees without their own.", "x-exac-sat-catalog": "payroll-position-risks" }, { "type": "null" } ] }, "defaultStateCode": { "anyOf": [ { "enum": [ "AGU", "BCN", "BCS", "CAM", "CHH", "CHP", "CMX", "COA", "COL", "DIF", "DUR", "GRO", "GUA", "HID", "JAL", "MEX", "MIC", "MOR", "NAY", "NLE", "OAX", "PUE", "QUE", "ROO", "SIN", "SLP", "SON", "TAB", "TAM", "TLA", "VER", "YUC", "ZAC" ], "description": "ClaveEntFed for employees without their own.", "x-exac-sat-catalog": "federal-entities" }, { "type": "null" } ] }, "weeklyStartsOn": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 6, "description": "Weekday weekly periods start on, 0 = Sunday; Monday when unset." }, { "type": "null" } ] }, "biweeklyAnchorStart": { "anyOf": [ { "allOf": [ { "type": "string", "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])))$" }, { "type": "string", "pattern": "^(19|20)" }, { "$ref": "#/definitions/__schema0" } ], "description": "First day of any catorcenal period." }, { "type": "null" } ] } }, "required": [ "operation" ], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "const": "prepare" }, "frequency": { "enum": [ "10", "02", "03", "04", "05" ] }, "periodStart": { "allOf": [ { "type": "string", "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])))$" }, { "type": "string", "pattern": "^(19|20)" }, { "$ref": "#/definitions/__schema0" } ], "description": "First day of the pay period." } }, "required": [ "operation", "frequency", "periodStart" ], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "const": "update_run" }, "runId": { "$ref": "#/definitions/__schema1" }, "paidOn": { "allOf": [ { "type": "string", "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])))$" }, { "type": "string", "pattern": "^(19|20)" }, { "$ref": "#/definitions/__schema0" } ], "description": "FechaPago of every receipt." } }, "required": [ "operation", "runId", "paidOn" ], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "const": "recalculate" }, "runId": { "$ref": "#/definitions/__schema1" } }, "required": [ "operation", "runId" ], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "const": "update_row" }, "rowId": { "$ref": "#/definitions/__schema2" }, "update": { "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.", "allOf": [ { "type": "number", "minimum": 0.001, "maximum": 36160, "multipleOf": 0.001 } ] }, "earnings": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "code": { "$ref": "#/definitions/__schema7" }, "description": { "$ref": "#/definitions/__schema8" }, "type": { "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" ], "description": "Known SAT payroll earning-type code.", "x-exac-sat-catalog": "payroll-earning-types" }, "taxableAmount": { "$ref": "#/definitions/__schema9" }, "exemptAmount": { "$ref": "#/definitions/__schema9" } }, "required": [ "code", "type", "taxableAmount", "exemptAmount" ], "additionalProperties": false } }, "deductions": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "code": { "$ref": "#/definitions/__schema7" }, "description": { "$ref": "#/definitions/__schema8" }, "type": { "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" ], "description": "Known SAT payroll deduction-type code.", "x-exac-sat-catalog": "payroll-deduction-types" }, "amount": { "$ref": "#/definitions/__schema9" } }, "required": [ "code", "type", "amount" ], "additionalProperties": false } }, "otherPayments": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "code": { "$ref": "#/definitions/__schema7" }, "description": { "$ref": "#/definitions/__schema8" }, "type": { "enum": [ "999", "001", "002", "003", "004", "005", "006", "007", "008", "009" ], "description": "Known SAT payroll other-payment code.", "x-exac-sat-catalog": "payroll-other-payment-types" }, "amount": { "$ref": "#/definitions/__schema9" }, "employmentSubsidy": { "allOf": [ { "$ref": "#/definitions/__schema9" } ] } }, "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": { "const": "calculated", "description": "Drop captured amounts and calculate from the employee's salary." } }, "required": [ "source" ], "additionalProperties": false } ] } }, "required": [ "operation", "rowId", "update" ], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "const": "prepare_again" }, "rowId": { "$ref": "#/definitions/__schema2" } }, "required": [ "operation", "rowId" ], "additionalProperties": false } ] } }, "required": [ "idempotencyKey", "input" ], "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "definitions": { "__schema0": { "type": "string", "allOf": [ { "type": "string", "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])))$" }, { "type": "string", "pattern": "^(19|20)" } ] }, "__schema1": { "type": "string", "minLength": 1, "description": "runId of a payroll run, as prepared or listed." }, "__schema2": { "type": "string", "minLength": 1, "description": "rowId of a receipt, as listed in its run's receipts." }, "__schema7": { "type": "string", "minLength": 3, "maxLength": 15, "description": "The employer's clave for the concept, 3 to 15 characters." }, "__schema8": { "type": "string", "minLength": 1, "maxLength": 100 }, "__schema9": { "type": "number", "minimum": 0, "exclusiveMaximum": 1000000000000000000, "multipleOf": 0.01 } }}Output schema
JSON Schema{ "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "minimumWageZone": { "enum": [ "general", "northBorder" ] }, "defaultRiskClass": { "type": "string" }, "defaultStateCode": { "type": "string" }, "weeklyStartsOn": { "type": "integer", "minimum": 0, "maximum": 6 }, "biweeklyAnchorStart": { "type": "string", "allOf": [ { "type": "string", "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])))$" }, { "type": "string", "pattern": "^(19|20)" } ] }, "suggestedMinimumWageZone": { "allOf": [ { "enum": [ "general", "northBorder" ] } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "runId": { "type": "string" }, "frequency": { "enum": [ "10", "02", "03", "04", "05" ] }, "periodStart": { "$ref": "#/definitions/__schema0" }, "periodEnd": { "$ref": "#/definitions/__schema0" }, "paidOn": { "$ref": "#/definitions/__schema0" }, "calculating": { "type": "boolean" }, "rows": { "type": "object", "properties": { "ready": { "$ref": "#/definitions/__schema2" }, "needs_attention": { "$ref": "#/definitions/__schema2" }, "excluded": { "$ref": "#/definitions/__schema2" }, "queued": { "$ref": "#/definitions/__schema2" }, "stamping": { "$ref": "#/definitions/__schema2" }, "stamped": { "$ref": "#/definitions/__schema2" }, "rejected": { "$ref": "#/definitions/__schema2" }, "canceled": { "$ref": "#/definitions/__schema2" } }, "required": [ "ready", "needs_attention", "excluded", "queued", "stamping", "stamped", "rejected", "canceled" ], "additionalProperties": false }, "missingSalary": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "$ref": "#/definitions/__schema3" }, "stampRequestedAt": { "allOf": [ { "$ref": "#/definitions/__schema3" } ] }, "stampBlock": { "type": "object", "properties": { "code": { "enum": [ "payment_required", "interrupted", "rules_pending_review" ] } }, "required": [ "code" ], "additionalProperties": false } }, "required": [ "runId", "frequency", "periodStart", "periodEnd", "paidOn", "calculating", "rows", "missingSalary", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "rowId": { "type": "string" }, "runId": { "type": "string" }, "employeeId": { "type": "string" }, "employeeName": { "type": "string" }, "employeeTaxId": { "allOf": [ { "type": "string" } ] }, "state": { "enum": [ "ready", "needs_attention", "excluded", "queued", "stamping", "stamped", "rejected", "canceled" ] }, "omitted": { "type": "boolean" }, "source": { "enum": [ "calculated", "manual" ] }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "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" ] }, "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": { "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" ] }, "updatedAt": { "$ref": "#/definitions/__schema3" }, "earnings": { "type": "array", "items": { "type": "object", "properties": { "type": { "$ref": "#/definitions/__schema5" }, "code": { "$ref": "#/definitions/__schema6" }, "description": { "$ref": "#/definitions/__schema7" }, "taxableAmount": { "type": "number" }, "exemptAmount": { "type": "number" } }, "required": [ "type", "code", "taxableAmount", "exemptAmount" ], "additionalProperties": false } }, "deductions": { "type": "array", "items": { "type": "object", "properties": { "type": { "$ref": "#/definitions/__schema5" }, "code": { "$ref": "#/definitions/__schema6" }, "description": { "$ref": "#/definitions/__schema7" }, "amount": { "type": "number" } }, "required": [ "type", "code", "amount" ], "additionalProperties": false } }, "otherPayments": { "type": "array", "items": { "type": "object", "properties": { "type": { "$ref": "#/definitions/__schema5" }, "code": { "$ref": "#/definitions/__schema6" }, "description": { "$ref": "#/definitions/__schema7" }, "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": { "allOf": [ { "$ref": "#/definitions/__schema0" } ] }, "validFrom": { "allOf": [ { "$ref": "#/definitions/__schema0" } ] }, "sourceUrl": { "allOf": [ { "type": "string" } ] } }, "required": [ "key", "label", "legalBasis", "readOn", "validFrom" ], "additionalProperties": false } } }, "required": [ "paidDays", "contributionDays", "dailyWage", "integratedDailySalary", "contributionBaseSalary", "isrCaused", "lines", "rules" ], "additionalProperties": false }, "lastReceiptSalaryAvailable": { "type": "boolean" } }, "required": [ "rowId", "runId", "employeeId", "employeeName", "state", "omitted", "source", "issues", "updatedAt", "earnings", "deductions", "otherPayments", "lastReceiptSalaryAvailable" ], "additionalProperties": false } ] }, "error": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "code": { "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" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "document": { "type": "object", "properties": { "documentRef": { "type": "string", "pattern": "^(invoice|withholding|sales_receipt|declaration|tax_compliance_opinion|sales_receipt_refund):.+$" }, "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 } }, "required": [ "code", "message" ], "additionalProperties": false } }, "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "definitions": { "__schema0": { "type": "string", "format": "date" }, "__schema2": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "net": { "type": "number" } }, "required": [ "count", "net" ], "additionalProperties": false }, "__schema3": { "type": "string", "format": "date-time" }, "__schema5": { "type": "string" }, "__schema6": { "type": "string" }, "__schema7": { "type": "string" } }, "oneOf": [ { "required": [ "data" ] }, { "required": [ "error" ] } ]}Related workflow
See the canonical workflows in QuickstartRelated tools
Read payroll
Read payroll settings, runs (optionally of one frequency), one run with its receipt count and net per state, a run's receipts (optionally in one state), or one receipt with its lines and calculation.
Stamp payroll
Irreversibly stamp payroll receipts. stamp_run queues every ready receipt of a run; send the ready count and net you checked with get_payroll, and a difference stamps nothing. restamp_row stamps a rejected receipt again after its employee was corrected. Receipts stamp in the background, each on its own; follow them with get_payroll. Safe retries require reusing the same idempotencyKey.