Calculations query: settlements list

Lists the settlements of a contribution account code in a period (the RED System service "Cotización SLD Remesas > Consulta de cálculos"). Query only: it changes nothing. It is the first step of the calculations query: the liquidation_number of each settlement is then used in the calculations detail and in the Bulk query via SILTRA.

MCP tool: tgss_list_contribution_calculations (read-only).

Parameters

• test optional (number (1)) : For testing, add the test=1 parameter. It must be omitted in production. It returns a sample response without querying the TGSS.
• regimen (integer) : Scheme, 4 digits. Possible values:
  • 0111: General Scheme
  • Table of scheme codes (opens in a new tab)
• ccc (integer) : Contribution account code, 11 digits.
• start_date (date) : First settlement period, format YYYY-MM-DD. Only the month and year are used.
• end_date (date) : Last settlement period, format YYYY-MM-DD. Only the month and year are used. It cannot be earlier than start_date.
• liquid_type optional (string) : Settlement type. Defaults to T (all). Possible values:
  • T: All
  • L00: Normal
  • L02: Supplementary for processing-period wages (normal)
  • L03: Supplementary for retroactive wage payments
  • L13: Paid untaken holidays
  • L90: Supplementary for base increase
  • L91: Supplementary for new workers and/or tramos
  • L92: Supplementary for processing-period wages, ex officio
  • L93: Supplementary for paid untaken holidays, ex officio
  • C00: Ordinary, non-agreed wages
  • C02: Supplementary for processing-period wages, non-agreed
  • C03: Supplementary for retroactive wages, non-agreed
  • C13: Supplementary for paid holidays, non-agreed
  • C90: Supplementary for base increase, non-agreed
  • C91: Supplementary for new workers and/or tramos, non-agreed
  • V03: Supplementary for retroactive wage payments of L13
  • V90: Supplementary for base increase of L13
• liquid_origin optional (string) : Settlement origin. Defaults to T (all). Possible values:
  • T: All
  • E: Submitted by the company
  • G: Generated by the TGSS
• authorized_num optional (integer) : RED authorised user number, 1 to 10 digits. Mandatory when the certificate has more than one RED authorised user; if you do not know it, send the request without it and capture data.authorized_list from the 422 response. Then resend it with the number.

{
  "test": 1,
  "regimen": "0111",
  "ccc": "28123456789",
  "start_date": "2026-09-01",
  "end_date": "2026-09-01",
  "liquid_type": "T",
  "liquid_origin": "T"
}

Successful response

All amounts are numeric (euros, with decimals) and data the TGSS does not provide is returned as null. Periods use the format MM/YYYY.

• ccc (string) : Contribution account code, 11 digits.
• regimen (string) : Scheme, 4 digits.
• company_name (string) : Registered company name.
• list (array) : One entry per settlement:
  • liquidation_number (string) : Settlement number, always 17 digits (with leading zeros).
  • ccc, regimen (string) : Contribution account code and scheme of the settlement.
  • liquid_type (string) : Settlement type (L00, C00…).
  • period_from, period_to (string) : First and last period of the settlement, format MM/YYYY.
  • amount (decimal) : Settlement amount, in euros.
  • origin_description (string) : Origin, as given by the TGSS (for example Usuario). The TGSS does not return the E/G code.
  • status_description (string) : Settlement status (for example Confirmada U.).
  • rectification_number (string) : Rectification number.
  • calculated_at (string) : Date and time of the calculation, format YYYY-MM-DD HH:MM.
  • extra (object) : TGSS fields without a translated key (see The extra field). data also carries 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": {}
  }
}

The extra field

All the objects in the response (data, each element of list, liquidations, totals, workers, accumulated, concepts, monthly, peculiarities, fixed_amount_bonuses, previous_fixed_amount_bonuses and tramos, and also bonus_limits, reduction_adjustment, affiliation, calculations and worker) carry an extra field.

extra is an object with the TGSS fields that have no translated key, with their original XML name and their unconverted value (text as is, for example "12,50"). If there are none, it is {}.

It lets a new field added by the TGSS show up there with no API change. If it is translated later, it moves to its own English key and no longer appears in extra. It never includes technical data or data about the logged-in user.

There is an example in the settlement detail.

Errors

• 422: validation error (errors.<field>), or a certificate with several RED authorised users and no authorized_num (the list is in 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: the TGSS returns no settlements for the account, period, type and origin given. It is a definitive response: do not retry it.

{
  "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: TGSS error or unexpected screen (errors.tgss).