Calculations query: settlement detail

Returns the calculations of a settlement (the calculated RLC, by concept) and the list of its workers; with naf, the detail of one worker with their tramos (the RED System service "Cotización SLD Remesas > Consulta de cálculos"). Query only: it changes nothing. The liquidation_number comes from the settlements list.

MCP tool: tgss_get_contribution_calculations_detail (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.
• 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.
• naf optional (integer) : Worker NAF, 12 digits. Taken from the naf field of workers. With it, the response adds data.worker with the worker's detail and tramos.
• 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",
  "liquidation_number": "28202600000000001"
}

With the detail of one worker:

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

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

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

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

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"

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.
• If there are none, it responds 404.

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

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

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

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

Fields of data:

• liquidation_number (string) : Settlement number, always 17 digits (with leading zeros).
• ccc, regimen, company_name, liquid_type (string) : Settlement data, with the same meaning as in the list (ccc always 11 digits).
• period_from, period_to (string) : First and last period, format MM/YYYY.
• calculated_at (string) : Date and time of the calculation, format YYYY-MM-DD HH:MM.
• fpr_period (string) : TGSS F.P.R. period, format MM/YYYY.
• calculation_description, base_type_description, workers_summary (string) : TGSS texts: calculation type, base type and summary of workers and tramos.
• confirmed_workers, calculated_tramos, total_tramos (integer) : Confirmed workers, calculated tramos and total tramos of the settlement.
• totals (array) : The calculated RLC, by concept:
  • description (string) : Concept (for example CONTINGENCIAS COMUNES).
  • base, employee, employer, total (decimal) : Base, worker contribution, employer contribution and total, in euros.
• workers_list_available (boolean) : true if the TGSS gives the list of workers; false for settlements with many workers. Always present.
• workers (array) : Workers of the settlement, each with naf, caf and extra. It is null when workers_list_available is false (see below).
• warnings (array) : Only when workers is null: the reason.
• extra (object) : TGSS fields without a translated key. See The extra field.

Worker detail (with naf)

With naf, the response adds data.worker. The request takes a few seconds per tramo of the worker.

• worker (object) :
  • naf, caf (string) : Worker NAF and CAF.
  • calculated_at, fpr_period, base_type_description (string) : As in the settlement, but for the worker.
  • accumulated (array) : Worker accumulated amounts, with the same shape as totals.
  • bonus_limits (object) : null if there are no fixed-amount bonuses. Otherwise: theoretical_limit_description, theoretical_limit and monthly[] (each with limit_description, limit, potential_description, potential).
  • reduction_adjustment (object) : null or applicable_potential_reduction, employer_quota_limit, previous_tramos_reduction, tramo_reduction, applied_reduction.
  • tramos (array) : Worker tramos:
    • date_from, date_to (date) : Start and end of the tramo, format YYYY-MM-DD.
    • liquidation_period (string) : Settlement period, format MM/YYYY.
    • days_contributed (integer) : Days contributed.
    • base_cc, base_at (decimal) : Base for common contingencies and for occupational accidents and diseases, in euros.
    • rectification_number (string) : Rectification number.
    • affiliation (object) : Tramo affiliation data:
      • days_contributed, worked_days, planned_days (integer) : Days contributed, worked and planned.
      • ipf (string) : Natural person identifier (DNI/NIE).
      • contribution_group, contribution_group_description (string) : Contribution group and its description.
      • contract_type, contract_type_description (string) : Contract type and its description.
      • at_ep_epigraph, cnae (string) : AT/EP epigraph and CNAE.
      • peculiarities (array) : Contribution peculiarities, each with incentive_group, quota_fraction and description.
    • calculations (object) : Tramo calculations:
      • total (decimal) : Tramo total. Only filled in when the TGSS does not give the rates (see the note below); otherwise null.
      • concepts (array) : Concepts: description, base, rate (total rate), employee_rate, employer_rate (worker and employer rates), employee, employer and total (contributions in euros).
      • fixed_amount_bonuses (array) : Fixed-amount bonuses: collective, description, daily_amount, days, applied_amount, limit.
      • previous_fixed_amount_bonuses (array) : Fixed-amount bonuses from previous periods: description and amount.
      • reduction_adjustment (object) : Tramo reduction adjustment; null if it does not apply.

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

Settlements with many workers

For settlements with many workers the TGSS does not give the list. Then workers_list_available is false, workers is null and warnings explains why ("Esta liquidación tiene N trabajadores y la TGSS no da su lista: consulta cada uno con naf.", with N = confirmed_workers). In that case query each worker with naf; NAFs come from the RNT/RLC or from the CCC employment history. The detail with naf works either way. A naf that does not belong to the settlement gives a 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`."
    ]
  }
}

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.

Example: a concept with a new TGSS field (fictitious):

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

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 or naf given are not found. It is a definitive response: do not retry it.

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