REFERENCIA · CONTRACT V1

Endpoints delAPI partner.

Once superficies bajo /api/v1/partner/**. Los JSON son ilustrativos: no sustituyen una respuesta en vivo.

Auth: solo Authorization: Bearer al_plt_… (módulo partner_calculations, scope platform:read). No uses X-Company-Id — este contrato es de plataforma, sin tenant. El OpenAPI filtrado (GET /api/partner/openapi) tampoco lo pide.

Ejemplos ilustrativos · contract_version=v1

POST/api/v1/partner/calculate/mx/payroll

Nómina

Calcula ISR, IMSS, Infonavit, neto y costo patronal a partir de un sueldo bruto mensual.

AuthBearer al_plt_… · módulo partner_calculations · scope platform:read

sundays_worked opcional: prima dominical Art. 71 (25% del diario × N) con exención Art. 93 de 1 UMA × N. No entra al SBC/IMSS; sí al neto.
Cuando hay tasa ISN de catálogo: isn_note = ISN_ESTIMATED. Sin tasa: ISN_STATE_NOT_CONFIGURED.

Request body (ilustrativo)

{
  "gross_salary": 45000,
  "period": "monthly",
  "year": 2026,
  "worker_type": "employee",
  "state": "JAL",
  "include_employer_cost": true,
  "sundays_worked": 2
}

Response (ilustrativo)

{
  "year": 2026,
  "period": "monthly",
  "gross_salary_input": 45000,
  "gross_monthly": 45000,
  "isr_monthly": 7124.12,
  "imss_monthly": 1128.45,
  "net_salary_monthly": 37210.33,
  "sunday_premium_monthly": 750.00,
  "sunday_premium_exempt": 226.04,
  "sunday_premium_taxable": 523.96,
  "isn_rate_percent": 2.0,
  "isn_note": "ISN_ESTIMATED",
  "employer_cost": { "…": "desglose patronal" }
}

POST/api/v1/partner/calculate/mx/payroll-gross-up

Gross-up (neto → bruto)

Encuentra el bruto mensual que produce un neto objetivo (± $0.01), con el mismo desglose que payroll.

AuthBearer al_plt_… · módulo partner_calculations · scope platform:read

Input: target_net_monthly + mismos opcionales que payroll (sin gross_salary).
La búsqueda se parte en el acantilado del subsidio al empleo.

Request body (ilustrativo)

{
  "target_net_monthly": 35000,
  "period": "monthly",
  "year": 2026,
  "worker_type": "employee",
  "state": "JAL"
}

Response (ilustrativo)

{
  "year": 2026,
  "period": "monthly",
  "target_net_monthly": 35000,
  "gross_monthly": 42180.55,
  "gross_salary_input": 42180.55,
  "net_salary_monthly": 35000.00,
  "isr_monthly": 6280.12,
  "imss_monthly": 900.43,
  "isn_note": "ISN_ESTIMATED"
}

POST/api/v1/partner/calculate/mx/severance

Finiquito / liquidación

Simula finiquito y, cuando aplica, liquidación nacional a partir de fechas y sueldo mensual.

AuthBearer al_plt_… · módulo partner_calculations · scope platform:read

Request body (ilustrativo)

{
  "hire_date": "2021-03-15",
  "termination_date": "2026-06-30",
  "monthly_gross": 45000,
  "termination_type": "dismissal"
}

Response (ilustrativo)

{
  "currency": "MXN",
  "include_liquidation": true,
  "isr_is_estimated": true,
  "tenure": {
    "years_worked": 5,
    "months_worked": 3,
    "hire_date": "2021-03-15",
    "termination_date": "2026-06-30",
    "monthly_gross": 45000
  },
  "finiquito": { "total": 18240.5 },
  "liquidation": { "total": 135000.0 },
  "totals": {
    "total_severance_amount": 153240.5,
    "total_taxes": 18420.0,
    "net_amount_to_pay": 134820.5
  }
}

POST/api/v1/partner/calculate/mx/employer-cost

Costo patronal mensual

Devuelve solo el costo patronal del mismo camino de nómina (IMSS patronal, Infonavit, ISN estimado).

AuthBearer al_plt_… · módulo partner_calculations · scope platform:read

Request body (ilustrativo)

{
  "gross_salary": 45000,
  "year": 2026,
  "worker_type": "employee",
  "state": "JAL"
}

Response (ilustrativo)

{
  "year": 2026,
  "period": "monthly",
  "gross_monthly": 45000,
  "employer_cost": { "…": "desglose patronal" },
  "isn_rate_percent": 2.0,
  "isn_note": "ISN_ESTIMATED"
}

POST/api/v1/partner/calculate/mx/annual-employer-cost

Costo patronal anual

Anualiza el costo de empleo al mínimo de ley del año 1 (12 días de vacaciones). Separa aguinaldo y prima vacacional.

AuthBearer al_plt_… · módulo partner_calculations · scope platform:read

vacation_days_assumed = 12. No usa la tabla progresiva por antigüedad.

Request body (ilustrativo)

{
  "monthly_gross": 45000,
  "year": 2026,
  "worker_type": "employee",
  "state": "JAL"
}

Response (ilustrativo)

{
  "year": 2026,
  "monthly_gross": 45000,
  "annual_salary": 540000,
  "annual_aguinaldo": 18493.15,
  "annual_vacation_premium": 3698.63,
  "annual_employer_imss": 98400.00,
  "annual_employer_infonavit": 27000.00,
  "annual_isn": 10800.00,
  "annual_total_employer_cost": 698391.78,
  "vacation_days_assumed": 12,
  "benefits_basis_note": "Año 1 LFT mínimo (12 días). No tabla por antigüedad.",
  "isn_note": "ISN_ESTIMATED"
}

GET/api/v1/partner/catalog/mx/fiscal-parameters?year=2026

Parámetros fiscales

UMA, salarios mínimos, días de mes, factor de integración y tope/monto del subsidio al empleo.

AuthBearer al_plt_… · módulo partner_calculations · scope platform:read

Response (ilustrativo)

{
  "year": 2026,
  "uma_daily": 113.14,
  "min_wage_general": 278.80,
  "min_wage_frontera": 419.19,
  "days_per_month_salary": 30.4,
  "employment_subsidy_income_cap": 11492.66,
  "employment_subsidy_pct_uma": 11.82,
  "employment_subsidy_monthly": 417.48
}

GET/api/v1/partner/catalog/mx/isr-brackets?year=2026&period=monthly

Tablas de ISR

Tramos de ISR del catálogo nacional para el periodo solicitado.

AuthBearer al_plt_… · módulo partner_calculations · scope platform:read

Response (ilustrativo)

{
  "year": 2026,
  "period": "monthly",
  "bracket_type": "isr",
  "brackets": [
    {
      "lower_limit": 0.01,
      "upper_limit": 746.04,
      "fixed_fee": 0,
      "marginal_rate": 0.0192
    }
  ]
}

GET/api/v1/partner/catalog/mx/imss-employer-rates?year=2026

Tasas IMSS patronales

Tasas patronales IMSS e Infonavit del año solicitado.

AuthBearer al_plt_… · módulo partner_calculations · scope platform:read

Response (ilustrativo)

{
  "year": 2026,
  "fixed_em_rate_percent": 20.4,
  "em_excess_rate_percent": 1.1,
  "infonavit_employer_rate_percent": 5.0,
  "work_risk_rate_percent": 0.54355
}

GET/api/v1/partner/catalog/mx/municipalities?state=JAL

Municipios

Catálogo de municipios por estado (código INEGI / nombre).

AuthBearer al_plt_… · módulo partner_calculations · scope platform:read

Response (ilustrativo)

{
  "state": "JAL",
  "municipalities": [
    { "code": "14039", "name": "Guadalajara" },
    { "code": "14120", "name": "Zapopan" }
  ]
}

GET/api/v1/partner/health

Health

Liveness del contrato partner.

AuthBearer al_plt_… · módulo partner_calculations · scope platform:read

Response (ilustrativo)

{
  "status": "ok"
}

GET/api/v1/partner/version

Versión del contrato

Identifica la versión publicada del contrato (hoy v1).

AuthBearer al_plt_… · módulo partner_calculations · scope platform:read

Response (ilustrativo)

{
  "contract_version": "v1"
}