Consulta de cálculos: lista de liquidaciones

Lista las liquidaciones de una cuenta de cotización en un periodo (servicio «Cotización SLD Remesas > Consulta de cálculos» del Sistema RED). Solo consulta: no modifica nada. Es el primer paso de la Consulta de cálculos: el liquidation_number de cada liquidación se usa luego en el detalle de los cálculos y en la Consulta Masiva por SILTRA.

Herramienta MCP: tgss_list_contribution_calculations (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.
• 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",
  "liquid_type": "T",
  "liquid_origin": "T"
}

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.

• ccc (caracteres) : Cuenta de cotización, siempre 11 dígitos.
• regimen (caracteres) : Régimen, 4 dígitos.
• company_name (caracteres) : Razón social de la empresa.
• list (arreglo) : Una entrada por liquidación:
  • liquidation_number (caracteres) : Número de liquidación, siempre de 17 dígitos (con ceros a la izquierda).
  • ccc, regimen (caracteres) : Cuenta de cotización y régimen de la liquidación.
  • liquid_type (caracteres) : Tipo de liquidación (L00, C00…).
  • period_from, period_to (caracteres) : Primer y último periodo de la liquidación, formato MM/YYYY.
  • amount (decimal) : Importe de la liquidación, en euros.
  • origin_description (caracteres) : Origen, tal como lo da la TGSS (por ejemplo Usuario). La TGSS no devuelve el código E/G.
  • status_description (caracteres) : Estado de la liquidación (por ejemplo Confirmada U.).
  • rectification_number (caracteres) : Número de rectificación.
  • calculated_at (caracteres) : Fecha y hora del cálculo, formato YYYY-MM-DD HH:MM.
  • extra (objeto) : Campos de la TGSS sin clave traducida (ver El campo extra). data también lleva extra.

{
  "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": {}
  }
}

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.

Hay un ejemplo en el detalle de una liquidación.

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).

{
  "success": false,
  "message": "Es obligatorio introducir el autorizado {authorized_num}",
  "status": 422,
  "data": {
    "authorized_list": [
      {
        "numero": "100001",
        "razSoc": "EMPRESA DE PRUEBA SL"
      },
      {
        "numero": "100002",
        "razSoc": "OTRA EMPRESA DE PRUEBA SL"
      }
    ]
  }
}

• 404: la TGSS no devuelve liquidaciones para la cuenta, el periodo, el tipo y el origen indicados. Es una respuesta definitiva: no la reintentes.

{
  "success": false,
  "message": "SISTEMA RED: La TGSS no devuelve liquidaciones para esta cuenta de cotización, periodo, tipo y origen.",
  "status": 404,
  "data": [],
  "errors": {
    "tgss": [
      "SISTEMA RED: La TGSS no devuelve liquidaciones para esta cuenta de cotización, periodo, tipo y origen."
    ]
  }
}

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