Consulta de cálculos: detalle de una liquidación

Devuelve los cálculos de una liquidación (el RLC calculado, por conceptos) y la lista de sus trabajadores; con naf, el detalle de un trabajador con sus tramos (servicio «Cotización SLD Remesas > Consulta de cálculos» del Sistema RED). Solo consulta: no modifica nada. El liquidation_number sale de la lista de liquidaciones.

Herramienta MCP: tgss_get_contribution_calculations_detail (solo lectura).

Parámetros

• test opcional (número (1)) : Para pruebas, añade el parámetro test=1. Para producción se debe omitir. Devuelve una respuesta de ejemplo sin consultar a la TGSS.
• regimen (número entero) : Régimen, 4 dígitos. Posibles valores:
  • 0111: Régimen general
  • Tabla con los códigos de régimen (opens in a new tab)
• ccc (número entero) : Cuenta de cotización, 11 dígitos.
• start_date (date) : Primer periodo de liquidación, formato YYYY-MM-DD. Solo se tienen en cuenta el mes y el año.
• end_date (date) : Último periodo de liquidación, formato YYYY-MM-DD. Solo se tienen en cuenta el mes y el año. No puede ser anterior a start_date.
• liquidation_number opcional (número entero) : Número de liquidación de la TGSS, de 10 a 20 dígitos. Si se omite, se busca con el resto de filtros y se usa la liquidación única que resulte; si hay varias, la respuesta es un 422 con data.liquidations. Ver Cómo obtener liquidation_number.
• naf opcional (número entero) : NAF del trabajador, 12 dígitos. Sale del campo naf de workers. Con él, la respuesta añade data.worker con el detalle del trabajador y sus tramos.
• liquid_type opcional (caracteres) : Tipo de liquidación. Por defecto T (todas). Posibles valores:
  • T: Todas
  • L00: Normal
  • L02: Complementaria por salarios de tramitación (normal)
  • L03: Complementaria por abono de salarios con carácter retroactivo
  • L13: Vacaciones retribuidas y no disfrutadas
  • L90: Complementaria por incremento de bases
  • L91: Complementaria por nuevos trabajadores y/o tramos
  • L92: Complementaria por salarios de tramitación de oficio
  • L93: Complementaria por vacaciones retribuidas y no disfrutadas de oficio
  • C00: Ordinaria de salarios no concertados
  • C02: Complementaria por salarios de tramitación no concertados
  • C03: Complementaria por salarios retroactivos no concertados
  • C13: Complementaria por vacaciones retribuidas no concertados
  • C90: Complementaria por incremento de bases no concertados
  • C91: Complementaria por nuevos trabajadores y/o tramos no concertados
  • V03: Complementaria por abono de salarios retroactivos de L13
  • V90: Complementaria por incremento de bases de L13
• liquid_origin opcional (caracteres) : Origen de la liquidación. Por defecto T (todas). Posibles valores:
  • T: Todas
  • E: Presentadas por la empresa
  • G: Generadas por la TGSS
• authorized_num opcional (número entero) : Número de autorizado RED, de 1 a 10 dígitos. Es obligatorio cuando el certificado tiene más de un autorizado RED; si no lo conoces, envía la petición sin él y captura data.authorized_list de la respuesta 422. Luego, reenvíala con él.

{
  "test": 1,
  "regimen": "0111",
  "ccc": "28123456789",
  "start_date": "2026-09-01",
  "end_date": "2026-09-01",
  "liquidation_number": "28202600000000001"
}

Con el detalle de un trabajador:

{
  "test": 1,
  "regimen": "0111",
  "ccc": "28123456789",
  "start_date": "2026-09-01",
  "end_date": "2026-09-01",
  "liquidation_number": "28202600000000001",
  "naf": "281234567890"
}

Cómo obtener liquidation_number

El liquidation_number es el número de liquidación de la TGSS: el «Nº Liq.» de 17 dígitos que aparece en el RLC, en la RNT y en la Consulta de cálculos de la TGSS. Identifica una liquidación de una cuenta de cotización, un mes y un tipo (L00, L03…).

Cómo está formado

Tiene 17 dígitos: PP (2, código de provincia de la dirección provincial de la TGSS, igual a los 2 primeros dígitos del CCC) + AAAA (4, año) + 11 dígitos de secuencia que asigna la TGSS. Ejemplo ficticio: 28 2026 00012345678 → 28202600012345678 (CCC 28xxxxxxxxx).

No se puede construir a partir de otros datos: la secuencia la asigna la TGSS. Hay que obtenerlo de la lista de liquidaciones, del RLC/RNT o de SILTRA.

Opción 1: en dos pasos

Paso 1: pedir el listado. GET /api/v4/seg-social/contribution-calculations con estos parámetros:

• ccc (número entero) : Cuenta de cotización, 11 dígitos (los 2 primeros son la provincia).
• regimen (número entero) : Régimen, 4 dígitos (por ejemplo 0111).
• start_date, end_date (date) : Formato YYYY-MM-DD. Solo cuentan el mes y el año: para un mes, el día 1 y el último día del mismo mes (2026-09-01 y 2026-09-30).
• liquid_type opcional (caracteres) : T (todas, por defecto), L00, L03… (ver los valores arriba).
• liquid_origin opcional (caracteres) : T (todas, por defecto), E (empresa) o G (TGSS).

Las cabeceras son las de las demás páginas de la Seguridad Social: Authorization: Bearer {token} y X-Cert-Secret (clave secreta del certificado).

curl -G "https://api.saltra.es/api/v4/seg-social/contribution-calculations" -H "Authorization: Bearer $TOKEN" -H "X-Cert-Secret: $CERT_SECRET" \
  --data-urlencode "regimen=0111" --data-urlencode "ccc=28123456789" \
  --data-urlencode "start_date=2026-09-01" --data-urlencode "end_date=2026-09-30"

Respuesta: el número está en data.list[].liquidation_number (aquí 28202600000000001):

{
  "success": true,
  "message": "OK",
  "status": 200,
  "data": {
    "ccc": "28123456789",
    "regimen": "0111",
    "company_name": "EMPRESA DE PRUEBA SL",
    "list": [
      {
        "liquidation_number": "28202600000000001",
        "ccc": "28123456789",
        "regimen": "0111",
        "liquid_type": "L00",
        "period_from": "09/2026",
        "period_to": "09/2026",
        "amount": 10858.95,
        "origin_description": "Usuario",
        "status_description": "Confirmada U.",
        "rectification_number": "001",
        "calculated_at": "2026-10-14 09:30",
        "extra": {}
      }
    ],
    "extra": {}
  }
}

Paso 2: usarlo en esta llamada:

curl -G "https://api.saltra.es/api/v4/seg-social/contribution-calculations/detail" -H "Authorization: Bearer $TOKEN" -H "X-Cert-Secret: $CERT_SECRET" \
  --data-urlencode "regimen=0111" --data-urlencode "ccc=28123456789" \
  --data-urlencode "start_date=2026-09-01" --data-urlencode "end_date=2026-09-30" \
  --data-urlencode "liquidation_number=28202600000000001"

Opción 2: sin liquidation_number

La API busca las liquidaciones con ccc, regimen, start_date, end_date, liquid_type y liquid_origin:

• Si hay una, usa esa. Es el caso habitual: un mes con liquid_type=L00 devuelve una sola liquidación y basta una llamada.
• Si hay varias, responde 422 con data.liquidations (misma forma que los elementos de list). Elige una y repite la llamada con su liquidation_number.
• Si no hay ninguna, responde 404.

Consejo: filtra con liquid_type=L00 para obtener la liquidación normal del mes.

{
  "success": false,
  "message": "Hay varias liquidaciones en ese periodo: indica {liquidation_number}",
  "status": 422,
  "data": {
    "liquidations": [
      {
        "liquidation_number": "28202600000000001",
        "ccc": "28123456789",
        "regimen": "0111",
        "liquid_type": "L00",
        "period_from": "09/2026",
        "period_to": "09/2026",
        "amount": 10858.95,
        "origin_description": "Usuario",
        "status_description": "Confirmada U.",
        "rectification_number": "001",
        "calculated_at": "2026-10-14 09:30",
        "extra": {}
      },
      {
        "liquidation_number": "28202600000000002",
        "ccc": "28123456789",
        "regimen": "0111",
        "liquid_type": "L03",
        "period_from": "09/2026",
        "period_to": "09/2026",
        "amount": 1204.5,
        "origin_description": "Usuario",
        "status_description": "Confirmada U.",
        "rectification_number": "002",
        "calculated_at": "2026-10-14 09:30",
        "extra": {}
      }
    ]
  }
}

Respuesta OK

Todos los importes son numéricos (euros, con decimales) y un dato que la TGSS no da se devuelve como null. Los periodos van en formato MM/YYYY.

Sin naf:

{
  "success": true,
  "message": "OK",
  "status": 200,
  "data": {
    "liquidation_number": "28202600000000001",
    "ccc": "28123456789",
    "regimen": "0111",
    "company_name": "EMPRESA DE PRUEBA SL",
    "liquid_type": "L00",
    "period_from": "09/2026",
    "period_to": "09/2026",
    "calculated_at": "2026-10-14 09:30",
    "fpr_period": "10/2026",
    "calculation_description": "Liquidación total confirmada",
    "base_type_description": "Bases Reales",
    "workers_summary": "Trabajadores confirmados en la liquidación: 1. Tramos calculados: 1 de 1.",
    "confirmed_workers": 1,
    "calculated_tramos": 1,
    "total_tramos": 1,
    "totals": [
      {
        "description": "CONTINGENCIAS COMUNES",
        "base": 4936.56,
        "employee": 232.02,
        "employer": 1165.02,
        "total": 1397.04,
        "extra": {}
      },
      {
        "description": "LIQUIDO DE TOTALES",
        "base": null,
        "employee": 320.91,
        "employer": 1203.06,
        "total": 1523.97,
        "extra": {}
      }
    ],
    "workers_list_available": true,
    "workers": [
      {
        "naf": "281234567890",
        "caf": "PRUEB",
        "extra": {}
      }
    ],
    "extra": {}
  }
}

Campos de data:

• liquidation_number (caracteres) : Número de liquidación, siempre de 17 dígitos (con ceros a la izquierda).
• ccc, regimen, company_name, liquid_type (caracteres) : Datos de la liquidación, con el mismo significado que en la lista (ccc siempre de 11 dígitos).
• period_from, period_to (caracteres) : Primer y último periodo, formato MM/YYYY.
• calculated_at (caracteres) : Fecha y hora del cálculo, formato YYYY-MM-DD HH:MM.
• fpr_period (caracteres) : Periodo F.P.R. de la TGSS, formato MM/YYYY.
• calculation_description, base_type_description, workers_summary (caracteres) : Textos de la TGSS: tipo de cálculo, tipo de bases y resumen de trabajadores y tramos.
• confirmed_workers, calculated_tramos, total_tramos (número entero) : Trabajadores confirmados, tramos calculados y tramos totales de la liquidación.
• totals (arreglo) : El RLC calculado, por conceptos:
  • description (caracteres) : Concepto (por ejemplo CONTINGENCIAS COMUNES).
  • base, employee, employer, total (decimal) : Base, cuota del trabajador, cuota de la empresa y total, en euros.
• workers_list_available (booleano) : true si la TGSS da la lista de trabajadores; false en liquidaciones con muchos trabajadores. Viene siempre.
• workers (arreglo) : Trabajadores de la liquidación, cada uno con naf, caf y extra. Es null cuando workers_list_available es false (ver más abajo).
• warnings (arreglo) : Solo cuando workers es null: el motivo.
• extra (objeto) : Campos de la TGSS sin clave traducida. Ver El campo extra.

Detalle de un trabajador (con naf)

Con naf, la respuesta añade data.worker. La petición tarda unos segundos por cada tramo del trabajador.

• worker (objeto) :
  • naf, caf (caracteres) : NAF y CAF del trabajador.
  • calculated_at, fpr_period, base_type_description (caracteres) : Como en la liquidación, pero del trabajador.
  • accumulated (arreglo) : Acumulados del trabajador, con la misma forma que totals.
  • bonus_limits (objeto) : null si no hay bonificaciones de cuantía fija. Si no: theoretical_limit_description, theoretical_limit y monthly[] (cada uno con limit_description, limit, potential_description, potential).
  • reduction_adjustment (objeto) : null o applicable_potential_reduction, employer_quota_limit, previous_tramos_reduction, tramo_reduction, applied_reduction.
  • tramos (arreglo) : Tramos del trabajador:
    • date_from, date_to (date) : Inicio y fin del tramo, formato YYYY-MM-DD.
    • liquidation_period (caracteres) : Periodo de liquidación, formato MM/YYYY.
    • days_contributed (número entero) : Días cotizados.
    • base_cc, base_at (decimal) : Base de contingencias comunes y de accidentes de trabajo y enfermedades profesionales, en euros.
    • rectification_number (caracteres) : Número de rectificación.
    • affiliation (objeto) : Datos de afiliación del tramo:
      • days_contributed, worked_days, planned_days (número entero) : Días cotizados, trabajados y previstos.
      • ipf (caracteres) : Identificador de la persona física (DNI/NIE).
      • contribution_group, contribution_group_description (caracteres) : Grupo de cotización y su descripción.
      • contract_type, contract_type_description (caracteres) : Tipo de contrato y su descripción.
      • at_ep_epigraph, cnae (caracteres) : Epígrafe de AT/EP y CNAE.
      • peculiarities (arreglo) : Peculiaridades de cotización, cada una con incentive_group, quota_fraction y description.
    • calculations (objeto) : Cálculos del tramo:
      • total (decimal) : Total del tramo. Solo viene informado cuando la TGSS no da los tipos (ver la nota de abajo); si no, null.
      • concepts (arreglo) : Conceptos: description, base, rate (tipo total), employee_rate, employer_rate (tipos del trabajador y de la empresa), employee, employer y total (cuotas en euros).
      • fixed_amount_bonuses (arreglo) : Bonificaciones de cuantía fija: collective, description, daily_amount, days, applied_amount, limit.
      • previous_fixed_amount_bonuses (arreglo) : Bonificaciones de cuantía fija de periodos anteriores: description y amount.
      • reduction_adjustment (objeto) : Ajuste de reducción del tramo; null si no aplica.

Con naf:

{
  "success": true,
  "message": "OK",
  "status": 200,
  "data": {
    "liquidation_number": "28202600000000001",
    "ccc": "28123456789",
    "regimen": "0111",
    "company_name": "EMPRESA DE PRUEBA SL",
    "liquid_type": "L00",
    "period_from": "09/2026",
    "period_to": "09/2026",
    "calculated_at": "2026-10-14 09:30",
    "fpr_period": "10/2026",
    "calculation_description": "Liquidación total confirmada",
    "base_type_description": "Bases Reales",
    "workers_summary": "Trabajadores confirmados en la liquidación: 1. Tramos calculados: 1 de 1.",
    "confirmed_workers": 1,
    "calculated_tramos": 1,
    "total_tramos": 1,
    "totals": [
      {
        "description": "CONTINGENCIAS COMUNES",
        "base": 4936.56,
        "employee": 232.02,
        "employer": 1165.02,
        "total": 1397.04,
        "extra": {}
      },
      {
        "description": "LIQUIDO DE TOTALES",
        "base": null,
        "employee": 320.91,
        "employer": 1203.06,
        "total": 1523.97,
        "extra": {}
      }
    ],
    "workers_list_available": true,
    "workers": [
      {
        "naf": "281234567890",
        "caf": "PRUEB",
        "extra": {}
      }
    ],
    "extra": {},
    "worker": {
      "naf": "281234567890",
      "caf": "PRUEB",
      "calculated_at": "2026-10-14 09:30",
      "fpr_period": "10/2026",
      "base_type_description": "Bases reales",
      "accumulated": [
        {
          "description": "CONTINGENCIAS COMUNES",
          "base": 4936.56,
          "employee": 232.02,
          "employer": 1165.02,
          "total": 1397.04,
          "extra": {}
        },
        {
          "description": "LIQUIDO DE TOTALES",
          "base": null,
          "employee": 320.91,
          "employer": 1203.06,
          "total": 1523.97,
          "extra": {}
        }
      ],
      "bonus_limits": {
        "theoretical_limit_description": "Límite Teórico Bonificaciones Cuantía Fija.",
        "theoretical_limit": 1550.04,
        "monthly": [],
        "extra": {}
      },
      "reduction_adjustment": null,
      "extra": {},
      "tramos": [
        {
          "date_from": "2026-09-01",
          "date_to": "2026-09-30",
          "liquidation_period": "09/2026",
          "days_contributed": 30,
          "base_cc": 4936.56,
          "base_at": 4936.56,
          "rectification_number": "1",
          "extra": {},
          "affiliation": {
            "days_contributed": 30,
            "ipf": "12345678Z",
            "contribution_group": "7",
            "contribution_group_description": "AUXILIARES ADMINISTRATIVOS",
            "contract_type": "100",
            "contract_type_description": "INDEFINIDO TIEMPO COMPLETO",
            "at_ep_epigraph": "0",
            "cnae": "6220",
            "worked_days": 0,
            "planned_days": 0,
            "peculiarities": [],
            "extra": {}
          },
          "calculations": {
            "total": null,
            "concepts": [
              {
                "description": "CONTINGENCIAS COMUNES",
                "base": 4936.56,
                "rate": 28.3,
                "employee_rate": 4.7,
                "employer_rate": 23.6,
                "employee": 232.02,
                "employer": 1165.02,
                "total": 1397.04,
                "extra": {}
              }
            ],
            "fixed_amount_bonuses": [],
            "previous_fixed_amount_bonuses": [],
            "reduction_adjustment": null,
            "extra": {}
          }
        }
      ]
    }
  }
}

Liquidaciones con muchos trabajadores

En liquidaciones con muchos trabajadores la TGSS no da la lista. Entonces workers_list_available es false, workers es null y warnings explica el motivo («Esta liquidación tiene N trabajadores y la TGSS no da su lista: consulta cada uno con naf.», con N = confirmed_workers). En ese caso consulta cada trabajador con naf; los NAF salen de la RNT/RLC o de la vida laboral del CCC. Con naf el detalle funciona igualmente. Un naf que no es de la liquidación da un 404.

{
  "success": true,
  "message": "OK",
  "status": 200,
  "data": {
    "liquidation_number": "28202600000000001",
    "ccc": "28123456789",
    "regimen": "0111",
    "company_name": "EMPRESA DE PRUEBA SL",
    "liquid_type": "L00",
    "period_from": "09/2026",
    "period_to": "09/2026",
    "calculated_at": "2026-10-14 09:30",
    "fpr_period": "10/2026",
    "calculation_description": "Liquidación total confirmada",
    "base_type_description": "Bases Reales",
    "workers_summary": "Trabajadores confirmados en la liquidación: 420. Tramos calculados: 420 de 420.",
    "confirmed_workers": 420,
    "calculated_tramos": 420,
    "total_tramos": 420,
    "totals": [
      {
        "description": "CONTINGENCIAS COMUNES",
        "base": 4936.56,
        "employee": 232.02,
        "employer": 1165.02,
        "total": 1397.04,
        "extra": {}
      },
      {
        "description": "LIQUIDO DE TOTALES",
        "base": null,
        "employee": 320.91,
        "employer": 1203.06,
        "total": 1523.97,
        "extra": {}
      }
    ],
    "workers_list_available": false,
    "workers": null,
    "extra": {},
    "warnings": [
      "Esta liquidación tiene 420 trabajadores y la TGSS no da su lista: consulta cada uno con `naf`."
    ]
  }
}

El campo extra

Todos los objetos de la respuesta (data, cada elemento de list, liquidations, totals, workers, accumulated, concepts, monthly, peculiarities, fixed_amount_bonuses, previous_fixed_amount_bonuses y tramos, y también bonus_limits, reduction_adjustment, affiliation, calculations y worker) llevan un campo extra.

extra es un objeto con los campos de la TGSS que no tienen una clave traducida, con su nombre original del XML y su valor sin convertir (texto tal cual, por ejemplo "12,50"). Si no hay ninguno, es {}.

Sirve para que, si la TGSS añade un campo nuevo, aparezca ahí sin cambios en la API. Si más adelante se traduce, pasa a su propia clave en inglés y deja de aparecer en extra. Nunca incluye datos técnicos ni del usuario con el que se ha iniciado sesión.

Ejemplo: un concepto con un campo nuevo de la TGSS (ficticio):

{
  "description": "CONTINGENCIAS COMUNES",
  "base": 4936.56,
  "rate": 28.3,
  "employee_rate": 4.7,
  "employer_rate": 23.6,
  "employee": 232.02,
  "employer": 1165.02,
  "total": 1397.04,
  "extra": {
    "campoNuevoConcepto": "valor 1"
  }
}

Errores

• 422: error de validación (errors.<campo>), o certificado con varios autorizados RED y sin authorized_num (la lista viene en data.authorized_list, igual que en la lista de liquidaciones). Si omites liquidation_number y hay varias liquidaciones, la lista viene en data.liquidations (ver Cómo obtener liquidation_number).
• 404: no hay liquidaciones para esos filtros, o el liquidation_number o el naf indicados no figuran. Es una respuesta definitiva: no la reintentes.

{
  "success": false,
  "message": "SISTEMA RED: El trabajador 281234567891 no figura en esta liquidación.",
  "status": 404,
  "data": [],
  "errors": {
    "tgss": [
      "SISTEMA RED: El trabajador 281234567891 no figura en esta liquidación."
    ]
  }
}

{
  "success": false,
  "message": "La liquidación 28202600000000009 no figura entre las que devuelve la TGSS para esta cuenta de cotización, periodo, tipo y origen (disponibles: 28202600000000001).",
  "status": 404,
  "data": [],
  "errors": {
    "tgss": [
      "La liquidación 28202600000000009 no figura entre las que devuelve la TGSS para esta cuenta de cotización, periodo, tipo y origen (disponibles: 28202600000000001)."
    ]
  }
}

• 502: error de la TGSS o pantalla inesperada (errors.tgss).