Consulta de cálculos: Consulta Masiva por SILTRA

⚠️

Añade test=1 para realizar pruebas sin efectos reales. En producción, omite este parámetro.

Pide a la TGSS la Consulta Masiva de los cálculos de todos los trabajadores de una liquidación (servicio «Cotización SLD Remesas > Consulta de cálculos» del Sistema RED). La TGSS la entrega en diferido en el buzón SILTRA del autorizado RED: la respuesta no trae ningún fichero. El liquidation_number sale de la lista de liquidaciones.

Herramienta MCP: tgss_request_contribution_calculations_siltra (no es de solo lectura: crea una petición en la TGSS).

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

Los parámetros se pueden enviar en el cuerpo JSON o en la query.

POST /contribution-calculations/siltra

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

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

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"

Respuesta: el número está en data.list[].liquidation_number (aquí 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": {}
  }
}

Paso 2: usarlo en esta llamada:

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

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. No se envía nada a la TGSS.
Si no hay ninguna, responde 404.

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

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

Respuesta OK

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

Campos de data:

status (caracteres) : requested: la TGSS ha tramitado la petición.
delivery (caracteres) : Canal de entrega; siempre siltra.
liquidation_number, regimen, ccc, company_name, liquid_type, period_from, period_to (caracteres) : Datos de la liquidación, con el mismo significado que en la lista de liquidaciones.
messages (arreglo) : Texto de confirmación de la TGSS.
extra (objeto) : Campos de la TGSS sin clave traducida (ver El campo extra).

Funciona también en liquidaciones con muchos trabajadores, aunque la TGSS no dé su lista en el detalle.

⚠️

Es una escritura en la TGSS: cada llamada crea una petición. Si la comunicación con la TGSS está desactivada en el entorno, devuelve 409 sin enviar nada. Con test=1 se devuelve una respuesta de ejemplo sin tocar la TGSS.

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, 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 indicado no figura.
409: la comunicación con la TGSS está desactivada en el entorno; no se ha enviado nada.

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: error de la TGSS o pantalla inesperada (errors.tgss).
504: la TGSS no ha respondido a tiempo. Comprueba si el trámite se registró (en el buzón SILTRA) antes de repetir la petición.

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."
    ]
  }
}

Consulta de cálculos: Consulta Masiva por SILTRA

Parámetros

Cómo obtener liquidation_number