Prórrogas SEPE: discontinuidad ya no es obligatoria en la API

Afecta a POST /api/v4/sepe/prorroga (Prórroga) y a su herramienta MCP. Corrige lo indicado el 20/10/2026.

• Sin discontinuidad ya no hay 422 propio. Antes, si el formulario del SEPE tenía el campo y no lo enviabas, la API respondía 422 sin llegar al SEPE. Ahora la prórroga se envía indicando que no hubo discontinuidad.
• El campo depende del contrato, no del hueco de fechas. El SEPE lo muestra en ciertos contratos aunque la prórroga empiece el día siguiente; en ese caso, sin discontinuidad, la comunicación sigue adelante con normalidad.
• N vuelve a ser válido y equivale a no enviar el campo.
• Si hay hueco de fechas, el SEPE exige la S y, si no la recibe, rechaza la comunicación con «Debe indicar el campo discontinuidad». Ese rechazo llega como cualquier otro rechazo del SEPE.

Qué revisar en tu integración: nada si ya no enviabas el campo cuando no hubo inactividad. Envía S solo si hubo inactividad que justifique la discontinuidad; si el SEPE responde «Debe indicar el campo discontinuidad» y no la hubo, corrige las fechas para que la prórroga empiece el día siguiente al fin del contrato o de la última prórroga.

Situación del empleado: parámetro getTc con los datos de +TC

Afecta a Consultar la situación del empleado en la empresa (GET /api/v4/seg-social/employee-situations) y a su herramienta MCP.

Nuevo parámetro opcional getTc

Cambio aditivo, no rompe integraciones. Con getTc=1, cada registro de data incluye una clave tc con los datos de la pantalla «+TC» (Peculiaridades de cotización) del Sistema RED:

• rlce y rlce_text: código y descripción de la Relación Laboral de Carácter Especial.
• special_code: campo «C.Esp» de la pantalla, tal cual lo informa la TGSS.
• sepe_contract_type: tipo de contrato comunicado al SEPE.
• unemployed_company / unemployed_company_text: condición de desempleado declarada por la empresa.
• unemployed_spee / unemployed_spee_text: condición de desempleado según el SPEE.
• fic_age: edad del trabajador en la fecha de inicio del contrato (número entero).
• fict_calculated: fecha de inicio del contrato calculada por la TGSS (YYYY-MM-DD).

Todos los campos pueden venir a null si la TGSS no los informa. Sin getTc la respuesta no cambia.

Cambio de contrato TGSS: reglas de la huelga y fin de la huelga en el histórico

Afecta al cambio de contrato (PUT /api/v4/seg-social/contract-coeficiente) y a su herramienta MCP tgss_update_contract_coeficiente.

El CTP de huelga es solo de la huelga parcial: nuevos 422

Cambio de comportamiento. Antes de enviar nada a la TGSS se comprueba tgss_ctp_huelga según tgss_inactividad, y la API responde 422 sin comunicar el trámite (la herramienta MCP devuelve un error con el mismo texto):

• Huelga total (2) con CTP de huelga: en una huelga total no se trabaja ninguna parte de la jornada, así que no cabe CTP de huelga.
• Huelga parcial (3) sin CTP de huelga: el CTP de huelga (el coeficiente de la jornada trabajada) es obligatorio.
• CTP de huelga 0 o 000, con cualquier inactividad: si no se trabaja nada, es huelga total (tipo 2 sin CTP). Antes un 0 se trataba como vacío.

Con el resto de tipos de inactividad (ERE/ERTE) el CTP de huelga no se valida: lo sigue decidiendo la TGSS. Detalle y mensajes en Reglas de la huelga.

El fin de la huelga queda en el histórico

Hasta ahora este endpoint solo comunicaba a la TGSS y no guardaba nada en el contrato de Saltra. Ahora, si el trámite va bien y el trabajador tiene su contrato en Saltra (se busca por el ccc entre las cuentas de tu empresa o de las empresas que gestionas), el cambio se guarda en él con la fecha del cambio (startDate), igual que desde la web.

El ATR45 no tiene fecha de fin: la huelga se termina con otro cambio sin tgss_inactividad ni tgss_ctp_huelga. Lo que la TGSS borra entonces se guarda como una entrada vacía con la fecha del fin: la fila de la huelga se cierra el día anterior, el periodo de huelga se conserva en el histórico y el valor vigente queda vacío.

Qué revisar en tu integración: envía tgss_ctp_huelga siempre que uses la inactividad 3, no lo envíes con la 2 y no uses 0/000 para «sin CTP» (omite el campo). La respuesta de un trámite correcto no cambia.

Errores de organismo: 424 y 503 en lugar de 502 y 504

Cambio de comportamiento. Cambian los códigos HTTP con los que la API informa de un fallo de un organismo (TGSS/Sistema RED, SEPE, DEHU, AEAT, Hacienda de Navarra) o de un sistema conectado. A partir del lunes 26/10/2026 la API no devuelve nunca a propósito 502 ni 504. El cuerpo no cambia: sigue siendo {success: false, message, status, data, errors}, con el motivo en message.

Por qué

Hemos incorporado una nueva capa de protección perimetral de la API (filtrado de tráfico malicioso / WAF y protección frente a ataques de denegación de servicio). Esta capa trata los 502 y 504 como fallos de red y sustituye su contenido por un mensaje genérico, por lo que el motivo del error no llegaba al cliente: se perdía nuestro JSON y, con él, el message con el motivo del rechazo de la TGSS o del SEPE. Los códigos 424 y 503 llegan intactos.

Qué cambia

retryable es un campo nuevo, en la raíz del cuerpo junto a maintenance y timeout.

Qué debes hacer

• Lee el cuerpo en cualquier código, no solo en el 200: el motivo está en message.
• 424: no reintentes sin corregir los datos (o cambiar el certificado, si es lo que ha rechazado el organismo). Repetir la misma petición devuelve el mismo rechazo.
• 503 con Retry-After: reintenta después de los segundos que indique la cabecera (o retry_after). No hagas polling a intervalo fijo.
• 503 sin Retry-After: no reintentes a ciegas. Comprueba antes si el trámite se registró (consulta el movimiento, el TA o el buzón correspondiente); reenviarlo podría duplicarlo.
• Un 502, 504 o 52x que aún recibas lo genera la infraestructura de red, no la API, y no trae nuestro cuerpo. Trátalo como un fallo de conexión: si era una escritura, comprueba si se registró antes de reintentar.

Las tablas de códigos de cada organismo están actualizadas: Seguridad Social, SEPE, DEHU, AEAT y Hacienda de Navarra.

Sistema RED: Consulta de cálculos (liquidaciones, cálculos y Consulta Masiva)

Tres endpoints nuevos bajo /api/v4/seg-social/ para el servicio «Cotización SLD Remesas > Consulta de cálculos» del Sistema RED:

• GET /contribution-calculations: lista las liquidaciones de una cuenta de cotización en un periodo. Herramienta MCP tgss_list_contribution_calculations. Documentación.
• GET /contribution-calculations/detail: cálculos de una liquidación por conceptos y lista de trabajadores; con naf, el detalle del trabajador con sus tramos. Herramienta MCP tgss_get_contribution_calculations_detail. Documentación.
• POST /contribution-calculations/siltra: pide la Consulta Masiva de los cálculos de todos los trabajadores de una liquidación; la TGSS la entrega en diferido en el buzón SILTRA. Es una escritura (409 si la comunicación con la TGSS está desactivada). Herramienta MCP tgss_request_contribution_calculations_siltra. Documentación.

detail devuelve siempre workers_list_available: en liquidaciones con muchos trabajadores la TGSS no da su lista, workers es null y warnings indica que se consulte cada trabajador con naf (que funciona en ambos casos; un naf ajeno a la liquidación da 404). siltra funciona también en esas liquidaciones. ccc es siempre de 11 dígitos y liquidation_number de 17.

Todos los objetos de la respuesta llevan un campo extra, con los campos de la TGSS sin clave traducida (nombre original del XML, valor sin convertir; {} si no hay). Si la TGSS añade un campo nuevo aparece ahí sin cambios en la API; si más adelante se traduce, pasa a su clave en inglés.

liquidation_number es opcional en detail y siltra: si se omite, se busca con ccc, regimen, start_date, end_date, liquid_type y liquid_origin; con una sola liquidación se usa esa, con varias responde 422 con data.liquidations para elegir (en la masiva, sin enviar nada a la TGSS) y sin ninguna, 404. Se obtiene con GET /contribution-calculations (data.list[].liquidation_number).

Los parámetros van en snake_case (regimen, ccc, start_date, end_date, liquid_type, liquid_origin, liquidation_number, naf, authorized_num, test). Es un cambio aditivo: no cambia nada para las integraciones existentes.

Recibo de Liquidación de Cotizaciones: format=siltra

El parámetro format del endpoint GET /report-rlc (Recibo de Liquidación de Cotizaciones) admite un tercer valor:

• siltra: pide a la TGSS el duplicado de la Relación Nominal de Trabajadores (RNT) de todos los trabajadores de la liquidación. La TGSS lo entrega en diferido en el buzón SILTRA del autorizado RED, no en la respuesta. data.status indica si la petición se ha tramitado (requested) o si ya había una pendiente (already_in_progress).

A diferencia de pdf y json, siltra no es una consulta: cada llamada crea una petición en la TGSS. La herramienta MCP tgss_report_rlc admite el mismo valor.

No cambia nada para quien envíe pdf, json o no envíe format.

Agregar cesión (ETTS): endDate opcional

En POST /seg-social/etts/cesion (Agregar cesión) el parámetro endDate pasa a ser opcional, como en el Sistema RED de la TGSS. Si se omite, la cesión queda sin fecha de fin. Si se envía, no puede ser anterior a startDate. La herramienta MCP etts_add_cesion admite lo mismo.

En «Actualizar cesión» endDate sigue siendo obligatoria. No cambia nada para quien ya envíe endDate.

Datos de la empresa: endpoint documentado y nueva opción situacion

El endpoint GET /enterprise/data (Datos de la empresa) ya tiene página de documentación y una opción nueva en options:

• situacion: añade data.situacion con la situación completa del CCC: estado, trabajadores, CNAE (93, 2009 y 2025), CCC principal / anterior / sucesor, mutua y datos de recaudación. Requiere ccc y regimen; sin ellos la respuesta es un 422.

Pedir cnae y situacion a la vez consulta la TGSS una sola vez. mutua y recaudacion no aparecen si la TGSS no devuelve esa pantalla. Con test=1 se devuelven datos de ejemplo sin consultar la TGSS. Hay una herramienta equivalente en el servidor MCP (tgss_enterprise_data).

No cambia nada para quien no envíe situacion.

Prórrogas SEPE: discontinuidad solo admite S

Corrige lo indicado el 16/10/2026 para POST /api/v4/sepe/prorroga (Prórroga). El campo discontinuidad solo admite el valor S; N no es válido.

• Cuándo lo pide el SEPE: solo cuando la prórroga no empieza el día siguiente al fin del contrato o de la prórroga anterior (hay al menos un día de hueco). No depende del tipo de contrato.
• Con N, vacío o sin el campo el SEPE rechaza siempre la comunicación («Debe indicar el campo discontinuidad. No se acepta la comunicación.»).

Qué revisar en tu integración: no envíes N. Si hubo inactividad que justifique el hueco, envía S. Si no la hubo, corrige las fechas para que la prórroga empiece el día siguiente al fin del contrato o de la prórroga anterior; entonces el SEPE no pregunta y el campo no hace falta.

Informe de Situación de un C.C.C.: nuevo parámetro format

El endpoint GET /report-situation-ccc (Informe de Situación de un C.C.C.) tiene un nuevo parámetro opcional format:

• pdf (por defecto): igual que hasta ahora, el PDF en data.file (base64).
• json: además del PDF, data.parsed con los datos del informe: razón social, CIF, situación del CCC, fechas de alta y de situación y autorización RED.

No cambia nada para quien no envíe format.

Recibo de Liquidación de Cotizaciones: nuevo parámetro format

El endpoint GET /report-rlc (Recibo de Liquidación de Cotizaciones) tiene un nuevo parámetro opcional format:

• pdf (por defecto): igual que hasta ahora, el PDF en data.file (base64).
• json: los datos de cada recibo de la liquidación (bases, cuotas y totales) en data.list, sin el PDF. Sirve cuando solo se necesitan los importes y mientras la TGSS no entregue el PDF de algunos periodos.

No cambia nada para quien no envíe format.

Prórrogas SEPE (discontinuidad) y cambio de contrato TGSS (reducción de jornada y CTP Inicial)

Prórrogas SEPE: la N de discontinuidad ya se envía, y si el SEPE la exige y falta, 422 claro

En POST /api/v4/sepe/prorroga el parámetro discontinuidad (S/N) responde a la pregunta «¿Ha existido un periodo de inactividad conforme a la normativa vigente, que justifique la discontinuidad?». El SEPE solo la hace en algunos contratos (por ejemplo, los temporales por circunstancias de la producción) y en ellos es obligatoria.

Qué fallaba: solo enviábamos discontinuidad cuando valía S. Con N se descartaba, el desplegable llegaba vacío y el SEPE rechazaba la comunicación con 422: Debe indicar el campo discontinuidad. No se acepta la comunicación.

Qué cambia:

• S y N se envían al SEPE tal cual.
• Si el SEPE exige el campo para ese contrato y no lo has enviado, la API responde 422 sin enviar nada al SEPE, con el error en errors.discontinuidad: «Para este contrato el SEPE exige indicar si ha existido un periodo de inactividad conforme a la normativa vigente que justifique la discontinuidad. Envía el campo discontinuidad con S o N.».
• Si el SEPE no pregunta por la discontinuidad en ese contrato, el campo se ignora aunque lo envíes.
• discontinuidad y prorroga_exist_convenio son strings S/N (la documentación los describía por error como números enteros).

Qué revisar en tu integración: envía siempre discontinuidad (S o N) en las prórrogas; es inocuo cuando el SEPE no lo pide y evita el 422 cuando sí lo exige. No asumimos ningún valor por defecto, porque la respuesta tiene efectos legales y es tuya.

Cambio de contrato TGSS: reducción de jornada y CTP Inicial

El cambio de contrato (PUT /api/v4/seg-social/contract-coeficiente) admite dos parámetros opcionales nuevos:

• reduccion_jornada: la «Reducción de jornada» (motivo) de la TGSS, 3 dígitos. Por ejemplo 001 (cuidado de menor), 002 (cuidado de persona con discapacidad) o 004 (corresponsabilidad en el cuidado del lactante). La tabla completa de códigos está enlazada en la documentación del endpoint. Solo se envía si la TGSS muestra el campo para ese contrato/coeficiente.
• tgss_ctp_inicial: el «CTP Inicial», de 1 a 3 dígitos en milésimas del coeficiente (la TGSS pone «0,» delante): 750 = 0,750; se rellena con ceros a la izquierda, 75 = 0,075.

Ambos se conservan si se omiten: si no los envías (o van vacíos), la TGSS mantiene el valor que tuviera el trabajador. Para quitar el CTP Inicial, envía 000. Ojo: no es el mismo comportamiento que tgss_inactividad y tgss_ctp_huelga, que se borran si se omiten.

MCP: la herramienta tgss_update_contract_coeficiente acepta ahora reduccion_jornada, tgss_inactividad, tgss_ctp_huelga y tgss_ctp_inicial, igual que el endpoint.

Afiliación de NAF: identificacion validada, limitación UE/EEE sin NIE y error 3001 con el campo rechazado

En POST /api/v4/seg-social/assignment-nss:

• identificacion (1=DNI, 2=Pasaporte, 6=NIE) ahora sí se valida: cualquier otro valor (antes llegaba a la TGSS) devuelve 422 con errors.identificacion (antes la regla no se aplicaba). Si no se envía, se deduce del documento (DNI→1, NIE→6, resto→2).
• Limitación de la TGSS, ahora con 422 propio: por Sistema RED no se puede asignar NAF a un ciudadano de la UE/EEE/Suiza (country, sin España) con tipo efectivo 2 (pasaporte o documento nacional, enviado o deducido). Saltra responde 422 con errors.identificacion sin llamar a la TGSS (antes llegaba a la TGSS y fallaba). Necesita NIE (tipo 6); sin NIE, el NAF se solicita en una administración de la TGSS (modelo TA.1).
• Cuando la TGSS rechaza un campo concreto (3001), el 502 lo indica en el message y en errors.field (campo nuevo, aditivo). Sin campo reconocible, la respuesta es la de siempre.
• streetType debe ser un código de 2 letras mayúsculas (CL), si no 422; el domicilio debe ser el del trabajador.

Clientes: nueva ruta /api/v4/customer

La API de clientes tiene ya su versión en v4, con las mismas operaciones que documentábamos:

GET    https://api.saltra.es/api/v4/customer
POST   https://api.saltra.es/api/v4/customer
DELETE https://api.saltra.es/api/v4/customer/{customerID}
PUT    https://api.saltra.es/api/v4/customer/{customerID}/activate

Hasta hoy la documentación apuntaba a /api/web/v3/customer, que es la ruta que usa la propia plataforma Saltra. Su validación sigue al formulario de la web y, por eso, al crear un cliente exigía profile.codigo_postal y profile.parameters aunque la documentación los daba como opcionales. La v4 tiene validación propia de la API:

• Obligatorios: name, access.email, profile.dni, profile.razon_social y al menos una cuenta en profile.account (regimen, cuenta y alias).
• Opcionales: profile.codigo_postal, profile.parameters, access.password (si la envías, con password_confirmation), profile.direccion, profile.external_id, not_notify.
• Representante legal: los cuatro campos de profile.parameters.representativeData (doc, name, surname, job_position) solo son obligatorios si envías representativeData.

Las respuestas tienen el mismo formato (success, message, data, status) y los errores de validación devuelven 422 con el detalle por campo en errors. Las herramientas MCP clients_* usan ya la v4.

Qué revisar en tu integración:

• Cambia la URL base a https://api.saltra.es/api/v4/customer. El cuerpo de las peticiones no cambia.
• /api/web/v3/customer sigue funcionando, pero es interna de la plataforma: su validación puede cambiar sin aviso cuando cambie la web. No construyas sobre ella.
• perPage en el listado admite como máximo 50; si pides más, se devuelven 50.

Certific@ no disponible: 503 inmediato con Retry-After

Hasta hoy, cuando el servicio Certific@ del SEPE no estaba disponible, una consulta de certificados de empresa (GET /sepe/certifica) podía tardar unos 12 segundos y acabar en 500 con un mensaje de «Tiempo agotado» que invitaba a revisar el certificado. A partir de hoy la API responde enseguida con 503 Service Unavailable, maintenance: true y la cabecera Retry-After:

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Retry-After: 120

{
  "success": false,
  "message": "SEPE: El servicio Certific@ no está disponible en este momento. Inténtalo de nuevo más tarde.",
  "status": 503,
  "errors": {
    "sepe": ["SEPE: El servicio Certific@ no está disponible en este momento. Inténtalo de nuevo más tarde."]
  },
  "maintenance": true,
  "retry_after": 120
}

Afecta a todos los endpoints de Certific@: enviar el certificado de empresa (POST /sepe/certifica), enviarlo por XML (POST /sepe/certifica/xml), el duplicado (GET /sepe/certifica), el listado (GET /sepe/certifica/list) y el detalle (GET /sepe/certifica/detail).

Mientras el servicio Certific@ siga sin estar disponible, las peticiones siguientes también reciben un 503 de inmediato, a veces con el mensaje SEPE: El SEPE no responde. Inténtelo de nuevo en unos minutos.. En los dos casos, Retry-After (igual que retry_after en el cuerpo) indica los segundos que faltan para que merezca la pena volver a intentarlo.

El formato del cuerpo no cambia (success, message, status, errors, maintenance, retry_after).

Qué revisar en tu integración:

• Un 503 no es un problema de tu certificado ni de los datos enviados. No cambies de certificado ni corrijas la petición: es una indisponibilidad del SEPE.
• Espera lo que indique Retry-After y no reintentes en bucle: reintentar antes devuelve el mismo 503.
• Si tratabas el 500 de Certific@ como un caso aparte, pásalo a la lógica que ya tengas para el 503 con maintenance: true. Los códigos de estado están en Errores del SEPE.

Cambio de contrato: tipo de inactividad y CTP de huelga/ERE

El cambio de contrato (PUT /contract-coeficiente) admite dos parámetros opcionales nuevos de la pantalla de cambio de contrato (ATR45) del Sistema RED:

• tgss_inactividad: el «Tipo de inactividad». Los valores posibles están en la tabla de tipos de inactividad. Se envía tal cual a la TGSS; Saltra no lo valida contra la lista y es la TGSS quien rechaza un valor no válido.
• tgss_ctp_huelga: el «CTP Actvid. Huelga/ERE», de 1 a 3 dígitos. Son las milésimas del coeficiente, porque la TGSS pone un «0,» fijo delante: 750 = 0,750. Saltra rellena con ceros a la izquierda hasta 3 dígitos, así que 75 = 0,075.

Ninguno de los dos se conserva. Si se omiten o van vacíos ("" / null), se envían vacíos y se elimina el valor que tuviera el trabajador. A diferencia de rlce, omitirlos no conserva el valor actual: para mantenerlo, reenvíalo; para quitarlo, envíalo vacío.

Datos bancarios: 404 sin cuentas y arreglo del autorizado

Consultar Datos Bancarios (GET /datos-bancarios) ya no responde 200 con saldo_acreedor y cargo_en_cuenta a null cuando la cuenta de cotización no tiene ninguna cuenta comunicada: responde 404 con success: false y el mensaje «SISTEMA RED: No hay datos bancarios comunicados para esta cuenta de cotización.».

• Si solo tiene una de las dos cuentas, sigue siendo 200 con la otra a null.
• El 404 es una respuesta definitiva, no un fallo de la TGSS: no hace falta reintentarla.

Además, con un certificado con varios autorizados RED, la consulta y Comunicar Datos Bancarios (PUT /datos-bancarios) fallaban con «El campo Autorizado es obligatorio» aunque se enviara authorized_num. Ya no: sin authorized_num responden 422 con data.authorized_list, como está documentado, y con él entran con ese autorizado.

Consultar los datos bancarios de una CCC

Nuevo endpoint Consultar Datos Bancarios (GET /datos-bancarios, mismo path que el PUT de Comunicar Datos Bancarios). Con regimen y ccc devuelve lo que la TGSS tiene comunicado para esa cuenta de cotización:

• saldo_acreedor y cargo_en_cuenta: IBAN completo, sus partes y el titular (tipo de documento, identificación y nombre); null si no hay cuenta comunicada.
• datos_bancarios: la pantalla de la TGSS completa, con sus nombres de campo originales.
• Si el certificado tiene varios autorizados RED, 422 con data.authorized_list, igual que el PUT.

La herramienta MCP tgss_get_datos_bancarios hace la misma consulta.

Cambio de contrato: ahora también el R.L.C.E.

El cambio de contrato (PUT /contract-coeficiente) admite el parámetro opcional rlce: la Relación Laboral de Carácter Especial, 4 dígitos (por ejemplo, 9941 para entrenadores y monitores bonificados por la Ley 7/2024). Hasta ahora, un R.L.C.E. que no quedara registrado en el alta no se podía comunicar después por la API.

• Si se omite rlce, se conserva el que ya tenga el trabajador en la TGSS: no se borra.
• Si no se envían ni contractType ni coeficiente, el coeficiente de tiempo parcial se conserva.
• Un rlce que no tenga 4 dígitos devuelve 422 antes de llamar a la TGSS.

La herramienta MCP tgss_update_contract_coeficiente acepta el mismo parámetro.

Cabecera Retry-After en los 503 de SEPE y TGSS

Cuando el SEPE (Contrat@, Certific@) o la TGSS/Sistema RED están en mantenimiento o no operativos, la API responde 503 con maintenance: true. Hasta hoy esa respuesta no decía cuánto esperar, así que la única opción era reintentar a ciegas. A partir de hoy lleva la cabecera Retry-After con los segundos que debes esperar antes de volver a intentarlo, igual que el 429:

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Retry-After: 120

{
  "success": false,
  "message": "SEPE: SEPE en mantenimiento.",
  "status": 503,
  "errors": {
    "sepe": ["SEPE: SEPE en mantenimiento."]
  },
  "maintenance": true,
  "retry_after": 120
}

El cuerpo puede traer además retry_after (entero, segundos) junto a maintenance: true, con el mismo valor que la cabecera. Si no viene, usa la cabecera.

El valor depende del caso. Cuando Saltra ya sabe que el organismo está parado (por ejemplo, Certific@ en mantenimiento), responde sin volver a consultarlo y Retry-After son los segundos que faltan para que lo compruebe de nuevo (hasta 300 segundos, 5 minutos). En el resto de paradas es un valor por defecto de unos minutos.

El formato del cuerpo no cambia (success, message, status, errors, maintenance).

Qué revisar en tu integración:

• Espera lo que indique Retry-After. Reintentar antes no desbloquea nada: devuelve el mismo 503.
• No hagas polling a intervalo fijo (por ejemplo, cada 10 segundos) mientras el organismo está parado. Programa el siguiente intento con el valor de la cabecera.
• Los códigos de estado y su detalle están en Errores del SEPE y Errores de la Seguridad Social.

FIE en JSON: columnas repetidas sin perder datos

El informe FIE de la TGSS repite algunas cabeceras en secciones distintas. Con format=json cada cabecera era una clave, así que las repetidas se pisaban y solo quedaba la última: llegaban 85 columnas de 88.

A partir de hoy la primera aparición conserva el nombre y las siguientes llevan entre paréntesis el código de su sección del informe. Las claves siguen saliendo del propio fichero de la TGSS: si añade una columna o una sección, aparece sola.

El formato excel no cambia.

Qué revisar en tu integración: si leías Entidad Responsable o Fecha Baja IT del JSON, antes recibías el dato de otras prestaciones o de incapacidad permanente. Ahora es el de incapacidad temporal; para los otros, usa las claves con (DOP) o (DIP).

FIE por Autorizado RED desde el MCP

La herramienta MCP tgss_excel_fie solo aceptaba la búsqueda por empresa (regimen + ccc obligatorios). Ahora admite los mismos parámetros que el endpoint: opcionesBusqueda (0 empresa, 1 autónomo con naf, 2 Autorizado RED, solo fechas) y format (excel o json). Con opcionesBusqueda: 2 se obtiene el FIE de todas las empresas del autorizado del certificado.

La TGSS rechaza los rangos de 29 días o más con «El rango de búsqueda no puede ser superior a 30 días». Por eso el máximo del endpoint baja de 30 a 28 días entre startDate y endDate: un rango mayor devuelve 422 antes de llamar a la TGSS, con el mismo límite por API y por MCP.

Trámites sin confirmar: 502 en vez de 500

Cuando el organismo acepta la petición pero no confirma si el trámite se ha hecho, la API lo devolvía como 500, a veces sin mensaje. Un 500 dice que el fallo es nuestro, y aquí no lo era. A partir de hoy estos casos salen como 502, con un mensaje que dice qué ha pasado, igual que el resto de respuestas inesperadas del organismo.

El formato del cuerpo no cambia (success, message, status, errors), y el mensaje de la baja tampoco: si tu integración lo reconoce por el texto, seguirá funcionando.

Qué revisar en tu integración:

• Bajas: algunas bajas que antes salían como error ahora salen con 200 y su TA, porque la TGSS sí las había hecho. Si reenviabas la baja o la marcabas para revisar a mano por ese error, ya no hace falta en esos casos.
• Reintentos: un 502 «…verifique si la operación se realizó correctamente» significa que el trámite puede estar hecho. Compruébalo antes de repetirlo. Si reintentas cualquier 5xx a ciegas, puedes duplicar la baja o la anulación.

Certificado de estar al corriente de la Hacienda de Navarra

Nueva sección Hacienda de Navarra con un endpoint, GET /api/v4/navarra/report-corriente, que pide a la Hacienda Foral de Navarra el certificado de estar al corriente de las obligaciones tributarias y lo devuelve en PDF (base64), igual que el certificado de la AEAT.

• Se pide con el certificado de la AEAT (tipo 3) en X-Cert-Secret, el mismo que en los endpoints de la AEAT.
• Por defecto se pide en representación (representation=true) del nif indicado; si no lo envías, se usa el CIF de la empresa del usuario. Con representation=false se pide en nombre propio del titular del certificado.
• type elige el certificado: EstarAlCorriente (por defecto), DeudasPorNif o EstarAlCorrienteContratistas.
• La respuesta añade data.result (positive, negative o null) leído del propio PDF.
• Si Hacienda no emite el certificado (el titular no representa a ese NIF, o devuelve su PDF de error), la API responde 502 con el motivo en errors.navarra.

En el servidor MCP público está disponible como la herramienta navarra_report_corriente.

Es un cambio aditivo: las integraciones existentes no tienen que tocar nada.

Causa de sustitución no admitida: 422 con los códigos válidos

En la comunicación de un contrato al SEPE, los códigos que admite CAUSA_SUSTITUCION dependen del contrato: Contrat@ ofrece unos u otros en su formulario. Hasta hoy, si el código enviado no estaba entre ellos, la API respondía 502 con el mensaje «SEPE: Sustitución no permitida por el SEPE», sin decir cuáles valían. Y en modo test no se podía reproducir, porque no se llega a abrir el formulario del SEPE.

A partir de ahora responde 422, porque son los datos los que hay que corregir, y devuelve en data.accepted los códigos que el SEPE admite para ese contrato:

{
  "success": false,
  "message": "SEPE: Causa de sustitución «19» no admitida por el SEPE para este contrato. Los códigos admitidos van en data.accepted",
  "status": 422,
  "data": {
    "field": "CAUSA_SUSTITUCION",
    "value": "19",
    "accepted": [
      { "code": "A", "description": "..." },
      { "code": "B", "description": "..." }
    ]
  }
}

Qué revisar en tu integración: no reintentes este error con el mismo código. Corrige CAUSA_SUSTITUCION con uno de data.accepted, que es una letra (tabla TEIINTER), no un número.

Grado de minusvalía en el alta de la TGSS

El alta de un trabajador admite un parámetro nuevo, grado_minusvalia: el grado de discapacidad reconocido al trabajador, como número de 2 dígitos (p. ej. 33, 65). Saltra lo comunica en el campo «Grado Minusvalía» de la pantalla de alta del Sistema RED.

• Es opcional: si no lo envías, el alta se comunica igual que hasta ahora, sin grado.
• Con rlce = 0600 (trabajadores con discapacidad en Centros Especiales de Empleo), la TGSS exige que el grado sea 33 o superior; si envías uno menor, la API responde 422 antes de ir al organismo.

Es un cambio aditivo: las integraciones que no lo usen no tienen que tocar nada.

El SEPE caído ya es 503, no 502

Cuando el SEPE se cae, no siempre nos deja leer su aviso de mantenimiento: a veces su servidor deja de responder de forma verificable y la conexión no llega a establecerse. Hasta hoy eso salía así:

{
  "success": false,
  "message": "Error de conexión de SALTRA con el (SEPE). ServiceOffLine",
  "status": 502,
  "maintenance": false
}

Dos problemas para quien integra: el mensaje nombra a Saltra, como si el fallo fuera nuestro, y maintenance va a false, así que no hay forma de distinguirlo de un rechazo puntual que sí merece reintento.

A partir de ahora es una parada del organismo como cualquier otra:

{
  "success": false,
  "message": "El (SEPE) está en mantenimiento. Inténtelo más tarde.",
  "status": 503,
  "maintenance": true
}

Afecta a todas las operaciones del SEPE, consultas y comunicaciones.

Qué revisar en tu integración: si decides reintentar mirando el texto del message, deja de hacerlo y mira maintenance. Es el campo pensado para esto, no cambia de redacción y ya distinguía el resto de paradas del organismo. La tabla completa está en Errores del SEPE.

Consultas sin resultados: 404 en vez de 502

Hasta hoy, cualquier texto que el SEPE devolviera al rechazar una consulta salía como 502. Eso incluía las respuestas en las que el organismo contesta perfectamente y lo que dice es que no hay nada:

• No existen certificados para ese NIF
• No se encuentra el documento en esta fecha 19/06/2026. Última fecha disponible para descargar…
• No se encontraron datos para la consulta solicitada.

Para una integración eso es indistinguible de un fallo del servicio, así que la respuesta razonable era reintentar — y reintentar una consulta sin resultados devuelve siempre lo mismo.

A partir de ahora:

El cuerpo de la respuesta no cambia: mismo success, message y errors.sepe con el texto del organismo. Solo cambia el código HTTP.

Afecta a todas las consultas del SEPE, y en particular a Duplicado de CERTIFIC@2, Detalle y Datos.

Qué revisar en tu integración: si tratas cualquier 5xx como “reintentar”, ahora los 404 y 422 salen de ese camino y dejas de repetir consultas que no van a cambiar. La tabla completa está en Errores del SEPE.

Informes RLC y RNT por trabajador: doc y tools MCP

Dos endpoints de informes de la TGSS que ya existían en /api/v4/seg-social no tenían página en esta documentación. Ahora la tienen:

• Recibo de Liquidación de Cotizaciones (RLC) — GET /report-rlc: el recibo de una cuenta de cotización para un tipo de liquidación y un rango de periodos, en PDF.
• Relación Nominal de Trabajadores (RNT) de un trabajador — GET /report-rnt-for-nss: la RNT filtrada por el número de afiliación de un trabajador, en PDF.

Las dos páginas recogen el catálogo completo de valores de liquidType (L00, L02, L03, L13, L90…), el parámetro numAutorizado para certificados con varios autorizados RED y, en el RLC, la fecha de control controlDate que exige el Sistema RED para las liquidaciones L03.

El servidor MCP público (api.saltra.es/api/v4/mcp, versión 1.0.3) incorpora las dos tools espejo: tgss_report_rlc y tgss_report_rnt_for_nss, con los mismos nombres de campo que las páginas.

No cambia nada en la API REST: son endpoints que ya estaban disponibles.

Certific@2 en JSON: nuevo GET /certifica/detail

Hasta ahora, de un CERTIFIC@2 ya comunicado solo se podía recuperar el PDF (GET /certifica). El SEPE no devuelve el XML original, así que quien quería los datos tenía que leerlos del documento.

Nuevo GET /certifica/detail: los mismos parámetros que el duplicado (dni, startDate, ccc) y el certificado entero en JSON, sin PDF: empresa, representante, trabajador, causa y fechas de suspensión, bases de cotización mes a mes, vacaciones y totales.

{
  "success": true,
  "message": "OK",
  "status": 200,
  "data": {
    "enterprise": { "cif": "B99999999", "ccc": "281999699", "name": "NOMBRE EMPRESA" },
    "employee": { "nif": "99999999T", "suspension_cause": "02", "suspension_start_date": "2026-07-31" },
    "contributions": [ { "year": "2026", "month": "07", "days": 30, "base_cc": 2583.32, "base_unemployment": 2583.32 } ],
    "holidays": { "days": 0, "base_cc": 0, "base_unemployment": 0 },
    "totals": { "days": 180, "base_cc": 13499.97, "base_unemployment": 13499.97 }
  }
}

Además:

• GET /certifica (duplicado) añade data.detail con esa misma estructura. file no cambia.
• GET /certifica/data pasa a llamarse GET /certifica/list, que es lo que hace. El nombre antiguo sigue funcionando como alias, sin fecha de retirada por ahora; la herramienta MCP sepe_certifica_data queda igualmente como alias de sepe_certifica_list.

El duplicado de TA dice de qué movimiento es

GET /duplicate-ta devolvía el PDF del TA y, en data.data, todos los movimientos del NAF consultado, sin decir cuál de ellos era el del PDF. Con un trabajador que tiene varias altas, quien recibía el documento no podía comprobar a qué fecha correspondía.

Ahora la respuesta trae data.movement: el movimiento concreto del que se ha sacado el documento, con su date, su documentoTA y el resto de columnas de la pantalla.

{
  "success": true,
  "message": "OK",
  "data": {
    "data": [ /* todos los movimientos del NAF */ ],
    "employee": { "name": "...", "doc": "043468731L", "nss": "081524252915" },
    "movement": {
      "indice": 1,
      "documentoTA": "ALTA (SIT.ACTUAL)",
      "date": "2023-01-01",
      "st": "01"
    },
    "file": { "contentType": "application/pdf", "name": "document.pdf", "content": "base64" }
  }
}

Es un campo nuevo: data, employee y file no cambian.

Los errores de validación de llamamientos llegan en el mensaje

Cuando POST /llamamientos no pasaba nuestra validación, el message de la respuesta era siempre el mismo literal —validation_errors— y el detalle real solo estaba en errors. Quien mostraba el message tal cual a su usuario le enseñaba un texto que no dice nada.

{
  "success": false,
  "message": "Hubo un error al enviar la comunicación. validation_errors",
  "status": 422,
  "errors": {
    "employees.0.nss": [
      "El campo NSS del empleado n# 1 debe ser de 12 dígitos."
    ]
  }
}

Ahora el message lleva los errores de campo, separados por | cuando hay varios:

{
  "success": false,
  "message": "Hubo un error al enviar la comunicación. El campo NSS del empleado n# 1 debe ser de 12 dígitos.",
  "status": 422,
  "errors": {
    "employees.0.nss": [
      "El campo NSS del empleado n# 1 debe ser de 12 dígitos."
    ]
  }
}

errors no cambia: sigue indexado por la posición del trabajador dentro de employees, empezando en 0. El resto de endpoints del SEPE responde igual que antes.

El rechazo de un trabajador suelto sigue el mismo criterio: cuando el SEPE no lo tiene en su base de datos y faltan datos para darlo de alta, data.data[].message dice qué campo falta en vez de validation_errors.

Nuevo informe: datos de cotización y periodo de liquidación por trabajador

Nuevo endpoint Datos de cotización y periodo de liquidación (trabajador). Es el mismo informe que /idc-ccc, pero acotado a un único NSS dentro de la cuenta de cotización, sin tener que descargar el informe de la cuenta entera y buscar al trabajador dentro.

{
  "regimen": "0111",
  "ccc": "12345678901",
  "nss": "281234567890",
  "period": "2023-02"
}

• regimen: régimen, 4 dígitos.
• ccc: cuenta de cotización, 11 dígitos.
• nss: número de afiliación, 12 dígitos.
• period: periodo de liquidación, formato YYYY-MM.

Devuelve el PDF en data.file.content, en base64, igual que el resto de informes de la TGSS.

Datos del trabajador en las consultas de documentos TA

Obtener listado de TA y Duplicados de Documentos TA devuelven ahora los datos identificativos del trabajador, que hasta ahora había que buscar en una consulta aparte.

"employee": {
  "name": "MARIA PEREZ GOMEZ",
  "identity": "1",
  "doc": "012345678Z",
  "nss": "289999999999"
}

• name: nombre completo, tal y como lo devuelve la TGSS.
• identity: tipo de documento. 1 DNI, 6 NIE, 2 pasaporte.
• doc: número de documento.
• nss: número de Seguridad Social, 12 dígitos.

En /ta-info-for-nss la clave cuelga de la raíz de la respuesta, junto a data. En /duplicate-ta cuelga de data, junto a data.data y data.file.

Es un cambio aditivo: no cambia ningún campo existente ni consume una petición extra contra la TGSS, porque el dato ya viajaba en la misma pantalla de la que se extrae el listado.

Cabeceras de límite de consultas: Retry-After y X-Ratelimit-Reset

Ampliamos la información de límite de consultas que devuelve la API. Es un cambio aditivo: no cambia ningún límite ni el formato de las respuestas, solo añade cabeceras.

• Retry-After en las respuestas 429. Indica los segundos que debes esperar antes de reintentar. Hasta ahora las respuestas 429 no la incluían y no había forma de saber cuánto duraba el bloqueo.
• X-Ratelimit-Reset en todas las respuestas. Timestamp UNIX del momento en que la ventana se renueva y X-Ratelimit-Remaining vuelve a su máximo. Junto a X-Ratelimit-Remaining te permite espaciar las peticiones al acercarte al límite, en lugar de detenerte en seco o chocar contra el 429.

HTTP/1.1 429 Too Many Requests
X-Ratelimit-Limit: 80
X-Ratelimit-Remaining: 0
X-Ratelimit-Reset: 1786012860
Retry-After: 37

X-Ratelimit-Reset es un instante absoluto, no una cuenta atrás: se mantiene igual en todas las respuestas de la misma ventana y solo avanza cuando el cupo se renueva.

La tabla completa de cabeceras está en Límites de consultas.

Changelog público, feed RSS y política de versiones

• Estrenamos esta sección: a partir de ahora, todos los cambios relevantes de la API pública se anuncian aquí.
• El changelog puede seguirse por RSS desde feed.xml  (o feed.en.xml  en inglés).
• Publicamos la política de versiones de la API: qué es un cambio aditivo, qué es una ruptura de contrato y qué periodo de convivencia tiene cada versión mayor.

TGSS: consultas sin resultados, 404 en vez de 502

Hasta hoy, cuando el Sistema RED contestaba a una consulta diciendo que no hay nada, la API lo devolvía como 502, igual que un fallo del organismo. Por ejemplo:

• SISTEMA RED: Error: 3543* NO EXISTEN DATOS PARA ESTA CONSULTA
• SISTEMA RED: No hay registros para el movimiento seleccionado!
• SISTEMA RED: No se encontró el informe con la fecha solicitada.
• SISTEMA RED: No existe información para el período solicitado.
• SISTEMA RED: Error. El Empleado no está en situación de Alta. Consulte Situación de Empleado en la Empresa

Para una integración eso es indistinguible de una caída, así que lo razonable era reintentar — y reintentar una consulta sin resultados devuelve siempre lo mismo.

A partir de ahora:

El cuerpo de la respuesta no cambia: mismo success, message y errors.tgss con el texto del organismo. Solo cambia el código HTTP.

Afecta a las consultas, informes y duplicados de la TGSS, entre otros: Situación del empleado, Situación del CCC, IDC, Vida laboral del afiliado, Duplicados de documentos TA, Ficheros FIE, Duplicado de maternidad/paternidad, Consultar IT, Consulta de convenios y Formulario A1.

Qué revisar en tu integración: si tratas cualquier 5xx como “reintentar”, ahora los 404 salen de ese camino y dejas de repetir consultas que no van a cambiar.