Calculations query: Bulk query via SILTRA

⚠️

Add test=1 to run tests without real effects. In production, omit this parameter.

Requests from the TGSS the Bulk query (Consulta Masiva) of the calculations of all the workers of a settlement (the RED System service "Cotización SLD Remesas > Consulta de cálculos"). The TGSS delivers it deferred to the SILTRA mailbox of the RED authorised user: the response carries no file. The liquidation_number comes from the settlements list.

MCP tool: tgss_request_contribution_calculations_siltra (not read-only: it creates a request at the TGSS).

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.
liquidation_number optional (integer) : TGSS settlement number, 10 to 20 digits. If omitted, it is looked up with the other filters and the single settlement found is used; if there are several, the response is a 422 with data.liquidations. See How to get liquidation_number.
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.

The parameters can be sent in the JSON body or in the query.

POST /contribution-calculations/siltra

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

How to get `liquidation_number`

The liquidation_number is the TGSS settlement number: the 17-digit "Nº Liq." shown in the RLC, the RNT and the TGSS calculations query. It identifies a settlement of a contribution account code, a month and a type (L00, L03…).

How it is built

It has 17 digits: PP (2, province code of the TGSS provincial office, equal to the first 2 digits of the CCC) + AAAA (4, year) + 11 sequence digits assigned by the TGSS. Fictitious example: 28 2026 00012345678 → 28202600012345678 (CCC 28xxxxxxxxx).

It cannot be built from other data: the sequence is assigned by the TGSS. Get it from the settlements list, the RLC/RNT or SILTRA.

Option 1: in two steps

Step 1: request the list. GET /api/v4/seg-social/contribution-calculations with these parameters:

ccc (integer) : Contribution account code, 11 digits (the first 2 are the province).
regimen (integer) : Scheme, 4 digits (for example 0111).
start_date, end_date (date) : Format YYYY-MM-DD. Only the month and year are used: for one month, the 1st and the last day of the same month (2026-09-01 and 2026-09-30).
liquid_type optional (string) : T (all, default), L00, L03… (see the values above).
liquid_origin optional (string) : T (all, default), E (company) or G (TGSS).

The headers are the same as on the other Social Security pages: Authorization: Bearer {token} and X-Cert-Secret (secret key of the certificate).

Paso 1: lista

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"

Response: the number is in data.list[].liquidation_number (here 28202600000000001):

Respuesta del paso 1

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

Step 2: use it in this call:

Paso 2: siltra

curl -X POST "https://api.saltra.es/api/v4/seg-social/contribution-calculations/siltra" -H "Authorization: Bearer $TOKEN" -H "X-Cert-Secret: $CERT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"regimen":"0111","ccc":"28123456789","start_date":"2026-09-01","end_date":"2026-09-30","liquidation_number":"28202600000000001"}'

Option 2: without `liquidation_number`

The API looks up the settlements with ccc, regimen, start_date, end_date, liquid_type and liquid_origin:

If there is one, it uses that one. This is the usual case: one month with liquid_type=L00 returns a single settlement and one call is enough.
If there are several, it responds 422 with data.liquidations (same shape as the list items). Pick one and repeat the call with its liquidation_number. Nothing is sent to the TGSS.
If there are none, it responds 404.

Tip: filter with liquid_type=L00 to get the month's normal settlement.

Respuesta status 422 (varias liquidaciones)

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

Successful response

Respuesta

{
  "success": true,
  "message": "Petición de la Consulta Masiva tramitada: la TGSS enviará el resultado en diferido al buzón SILTRA del autorizado.",
  "status": 200,
  "data": {
    "status": "requested",
    "delivery": "siltra",
    "liquidation_number": "28202600000000001",
    "regimen": "0111",
    "ccc": "28123456789",
    "company_name": "EMPRESA DE PRUEBA SL",
    "liquid_type": "L00",
    "period_from": "09/2026",
    "period_to": "09/2026",
    "messages": [
      "Su solicitud se ha tramitado correctamente. El resultado de la solicitud será remitido en diferido, para su recepción mediante la aplicación SILTRA."
    ],
    "extra": {}
  }
}

Fields of data:

status (string) : requested: the TGSS has processed the request.
delivery (string) : Delivery channel; always siltra.
liquidation_number, regimen, ccc, company_name, liquid_type, period_from, period_to (string) : Settlement data, with the same meaning as in the settlements list.
messages (array) : Confirmation text from the TGSS.
extra (object) : TGSS fields without a translated key (see The extra field).

It also works for settlements with many workers, even when the TGSS does not give their list in the detail.

⚠️

This is a write to the TGSS: every call creates a request. If communication with the TGSS is disabled in the environment, it returns 409 without sending anything. With test=1 a sample response is returned without touching the TGSS.

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, as in the settlements list). If you omit liquidation_number and there are several settlements, the list is in data.liquidations (see How to get liquidation_number).
404: there are no settlements for those filters, or the liquidation_number given is not found.
409: communication with the TGSS is disabled in the environment; nothing has been sent.

Respuesta status 409 (comunicación con la TGSS desactivada)

{
  "success": false,
  "message": "Este entorno no comunica con la TGSS: el trámite no se ha enviado.",
  "status": 409,
  "data": [],
  "errors": {
    "tgss": [
      "Este entorno no comunica con la TGSS: el trámite no se ha enviado."
    ]
  }
}

502: TGSS error or unexpected screen (errors.tgss).
504: the TGSS did not respond in time. Check whether the request was registered (in the SILTRA mailbox) before repeating it.

Respuesta status 504 (timeout)

{
  "success": false,
  "message": "La TGSS no respondió a tiempo: comprueba si el trámite se registró antes de reintentar.",
  "status": 504,
  "data": [],
  "errors": {
    "tgss": [
      "La TGSS no respondió a tiempo: comprueba si el trámite se registró antes de reintentar."
    ]
  }
}

Calculations query: Bulk query via SILTRA

Parameters

How to get liquidation_number