MCP serverAvailable tools
Create payroll CFDI draft
Create a payroll CFDI draft with canonical employee, earnings, deduction, other-payment, incapacity, and termination validation. This tool never stamps.
MCP tool
create_payroll_cfdi_draftPurpose
Create a tax-validated payroll CFDI draft.
- Use when
- You need to author employee payroll before SAT stamping.
- Do not use when
- The document is an income, credit-note, transfer, or payment-complement CFDI.
- Required permissions
- Side effects
- External side effect
- 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": { "type": "object", "properties": { "pdfCustomSection": { "type": "string" }, "emissionDate": { "description": "Optional emission instant with UTC offset, within the last 72 hours; revalidated at stamping.", "allOf": [ { "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)))$" } ] }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "kind": { "const": "payroll" }, "employeeId": { "type": "string", "minLength": 1 }, "payroll": { "type": "object", "properties": { "type": { "default": "O", "description": "O: ordinary payroll; E: extraordinary, requiring paymentFrequency 99.", "allOf": [ { "enum": [ "O", "E" ] } ] }, "paidOn": { "$ref": "#/definitions/__schema9" }, "periodStartedOn": { "$ref": "#/definitions/__schema9" }, "periodEndedOn": { "$ref": "#/definitions/__schema9" }, "paidDays": { "type": "number", "minimum": 0.001, "maximum": 36160, "multipleOf": 0.001 }, "employee": { "type": "object", "properties": { "curp": { "type": "string", "pattern": "^[A-Z][AEIOUX][A-Z]{2}[0-9]{2}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])[MHX]([ABCMTZ]S|[BCJMOT]C|[CNPST]L|[GNQ]T|[GQS]R|C[MH]|[MY]N|[DH]G|NE|VZ|DF|SP)[BCDFGHJ-NP-TV-Z]{3}[0-9A-Z][0-9]$" }, "employeeNumber": { "type": "string", "minLength": 1, "maxLength": 15, "pattern": "^[^|]+$" }, "socialSecurityNumber": { "type": "string", "pattern": "^\\d{1,15}$" }, "employmentStartedOn": { "allOf": [ { "$ref": "#/definitions/__schema9" } ] }, "contractType": { "enum": [ "10", "99", "01", "02", "03", "04", "05", "06", "07", "08", "09" ], "description": "Known SAT payroll contract-type code.", "x-exac-sat-catalog": "payroll-contract-types" }, "regimeType": { "enum": [ "10", "11", "12", "13", "99", "02", "03", "04", "05", "06", "07", "08", "09" ], "description": "Known SAT payroll regime-type code.", "x-exac-sat-catalog": "payroll-regime-types" }, "paymentFrequency": { "enum": [ "10", "99", "01", "02", "03", "04", "05", "06", "07", "08", "09" ], "description": "Known SAT payroll payment-frequency code.", "x-exac-sat-catalog": "payroll-payment-frequencies" }, "stateCode": { "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": "Known SAT federal-entity code.", "x-exac-sat-catalog": "federal-entities" }, "positionRisk": { "enum": [ "1", "2", "3", "4", "5", "99" ], "description": "Known SAT payroll position-risk code.", "x-exac-sat-catalog": "payroll-position-risks" }, "integratedDailySalary": { "allOf": [ { "$ref": "#/definitions/__schema22" } ] }, "contributionBaseSalary": { "allOf": [ { "$ref": "#/definitions/__schema22" } ] }, "department": { "allOf": [ { "$ref": "#/definitions/__schema25" } ] }, "position": { "allOf": [ { "$ref": "#/definitions/__schema25" } ] }, "workScheduleType": { "enum": [ "99", "01", "02", "03", "04", "05", "06", "07", "08" ], "description": "Known SAT payroll work-schedule code.", "x-exac-sat-catalog": "payroll-work-schedule-types" }, "unionMember": { "enum": [ "Sí", "No" ] }, "bankCode": { "enum": [ "102", "103", "106", "108", "110", "112", "113", "116", "124", "126", "127", "128", "129", "130", "131", "132", "133", "134", "135", "136", "137", "138", "139", "140", "141", "143", "145", "147", "148", "149", "150", "151", "152", "153", "154", "155", "156", "157", "158", "159", "160", "166", "168", "600", "601", "602", "605", "606", "607", "608", "610", "614", "615", "616", "617", "618", "619", "620", "621", "622", "623", "626", "627", "628", "629", "630", "631", "632", "633", "634", "636", "637", "638", "640", "642", "646", "647", "648", "649", "651", "652", "653", "655", "656", "659", "670", "901", "902", "002", "006", "009", "012", "014", "019", "021", "030", "032", "036", "037", "042", "044", "058", "059", "060", "062", "072" ], "description": "Known SAT payroll bank code.", "x-exac-sat-catalog": "payroll-banks" }, "bankAccount": { "type": "string", "pattern": "^(?:\\d{10}|\\d{11}|\\d{16}|\\d{18})$" } }, "required": [ "curp", "employeeNumber", "contractType", "regimeType", "paymentFrequency", "stateCode" ], "additionalProperties": false, "description": "Contracts 01–08 require regime 02/03/04, socialSecurityNumber, employmentStartedOn, positionRisk and integratedDailySalary. Other contracts use a different regime; those four fields are optional when applicable." }, "earnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "$ref": "#/definitions/__schema32" }, "description": { "$ref": "#/definitions/__schema33" }, "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/__schema22" }, "exemptAmount": { "$ref": "#/definitions/__schema22" }, "stock": { "type": "object", "properties": { "marketValue": { "$ref": "#/definitions/__schema37" }, "grantPrice": { "$ref": "#/definitions/__schema37" } }, "required": [ "marketValue", "grantPrice" ], "additionalProperties": false }, "overtime": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "type": { "enum": [ "01", "02", "03" ] }, "hours": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "amount": { "$ref": "#/definitions/__schema22" } }, "required": [ "days", "type", "hours", "amount" ], "additionalProperties": false } } }, "required": [ "code", "type", "taxableAmount", "exemptAmount" ], "additionalProperties": false } }, "pension": { "type": "object", "properties": { "accumulableIncome": { "$ref": "#/definitions/__schema22" }, "nonAccumulableIncome": { "$ref": "#/definitions/__schema22" }, "singlePayment": { "allOf": [ { "$ref": "#/definitions/__schema22" } ] }, "installment": { "allOf": [ { "$ref": "#/definitions/__schema22" } ] }, "dailyAmount": { "allOf": [ { "$ref": "#/definitions/__schema22" } ] } }, "required": [ "accumulableIncome", "nonAccumulableIncome" ], "additionalProperties": false }, "separation": { "type": "object", "properties": { "accumulableIncome": { "$ref": "#/definitions/__schema22" }, "nonAccumulableIncome": { "$ref": "#/definitions/__schema22" }, "totalPaid": { "$ref": "#/definitions/__schema22" }, "serviceYears": { "type": "integer", "minimum": 0, "maximum": 99 }, "lastMonthlySalary": { "$ref": "#/definitions/__schema22" } }, "required": [ "accumulableIncome", "nonAccumulableIncome", "totalPaid", "serviceYears", "lastMonthlySalary" ], "additionalProperties": false }, "incapacities": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "type": { "enum": [ "01", "02", "03", "04" ] }, "amount": { "allOf": [ { "$ref": "#/definitions/__schema22" } ] } }, "required": [ "days", "type" ], "additionalProperties": false } }, "deductions": { "type": "array", "items": { "type": "object", "properties": { "code": { "$ref": "#/definitions/__schema32" }, "description": { "$ref": "#/definitions/__schema33" }, "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": { "exclusiveMinimum": 0, "allOf": [ { "$ref": "#/definitions/__schema22" } ] } }, "required": [ "code", "type", "amount" ], "additionalProperties": false } }, "otherPayments": { "type": "array", "items": { "type": "object", "properties": { "code": { "$ref": "#/definitions/__schema32" }, "description": { "$ref": "#/definitions/__schema33" }, "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": { "description": "Zero is allowed only for type 002.", "allOf": [ { "$ref": "#/definitions/__schema22" } ] }, "compensation": { "description": "Required for 004. Current-year balances support periods wholly within December; mixed-month current-year periods are not yet supported.", "allOf": [ { "type": "object", "properties": { "balance": { "$ref": "#/definitions/__schema22" }, "year": { "type": "integer", "minimum": 2016, "maximum": 32767 }, "remainingBalance": { "$ref": "#/definitions/__schema22" } }, "required": [ "balance", "year", "remainingBalance" ], "additionalProperties": false } ] }, "employmentSubsidy": { "description": "Required for 002, at least amount; omitted for other types.", "allOf": [ { "$ref": "#/definitions/__schema22" } ] } }, "required": [ "code", "type", "amount" ], "additionalProperties": false } } }, "required": [ "type", "paidOn", "periodStartedOn", "periodEndedOn", "paidDays", "employee", "earnings" ], "additionalProperties": false } }, "required": [ "kind", "employeeId", "payroll" ], "additionalProperties": false, "title": "CFDI N · payroll" } }, "required": [ "idempotencyKey", "input" ], "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "definitions": { "__schema9": { "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)" } ] }, "__schema22": { "type": "number", "minimum": 0, "exclusiveMaximum": 1000000000000000000, "multipleOf": 0.01 }, "__schema25": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[^|]+$" }, "__schema32": { "type": "string", "minLength": 3, "maxLength": 15, "pattern": "^[^|]+$", "description": "Employer-assigned internal payroll accounting code, not the SAT type code" }, "__schema33": { "description": "Optional payroll concept description", "allOf": [ { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[^|]+$" } ] }, "__schema37": { "type": "number", "minimum": 0.000001, "multipleOf": 0.000001 } }}Output schema
JSON Schema{ "type": "object", "properties": { "data": { "type": "object", "properties": { "simulated": { "allOf": [ { "type": "boolean", "const": true } ] }, "documentRef": { "type": "string", "pattern": "^cfdi:.+$" }, "kind": { "enum": [ "income", "credit_note", "transfer", "payroll", "payment_complement" ] }, "status": { "const": "draft" } }, "required": [ "documentRef", "kind", "status" ], "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": "^(cfdi|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, "oneOf": [ { "required": [ "data" ] }, { "required": [ "error" ] } ]}Related workflow
See the canonical workflows in the introductionRelated tools
Create CFDI draft
Create a CFDI draft with canonical tax validation. Payment complements accept automatic taxes for known CFDIs or caller-provided taxObject and payment-level tax entries for external CFDIs. This tool never stamps.
Update CFDI draft
Fully replace the contents of an existing CFDI draft. The semantic kind must match the draft; changing fiscal kind requires archiving the old draft and creating a new draft.