Seguridad Social

Conecta tus aplicaciones con funciones de la seguridad social.

Parámetros en la cabecera HTTP

• Authorization (caracteres): Autorización de la API. Ejemplo: Bearer {token}
• X-Cert-Secret (caracteres) : Clave secreta asociada al certificado del cliente.
• X-Saltra-Mode opcional (caracteres) : test (ficticio: no se comunica nada al organismo) o live (real). Sin la cabecera, el trámite es real en producción y ficticio en el entorno de pruebas. Ver Entornos y modo prueba.

URL base

https://api.saltra.es/api/v4/seg-social

Errores

Los errores recibidos en la API de Seguridad Social o errores de validación.

Parámetros de respuesta

• success (booleano) : La respuesta “true” cuando todo esta correcto, y “false” cuando hay errores.
• message (caracteres) : El mensaje de la respuesta.
• errors (arreglo) : Los errores capturados en la API, ya sea de la seguridad Social o errores de validación.
  • tgss: Errores relacionados con la Seguridad Social.
  • regimen: Errores de validación.
• maintenance (booleano) : Cuando la Seguridad Social se encuentra en mantenimiento.
• retry_after opcional (número entero) : En los 503 con maintenance: true o con retryable: true: los mismos segundos que la cabecera Retry-After. Si no viene, usa la cabecera.
• retryable opcional (booleano) : true en los 503 en los que no hemos podido comunicarnos con el organismo; reintenta después de Retry-After. No aparece en el 424 ni en el 503 de resultado desconocido de una escritura.

Respuesta

{
  "success": false,
  "message": "Página no operativa, inténtelo de nuevo más tarde. StatusCode: 500",
  "status": 500,
  "data": [],
  "errors": {
    "tgss": [
      "Página no operativa, inténtelo de nuevo más tarde. StatusCode: 500"
    ],
    "regimen": ["El campo regimen es obligatorio."]
  },
  "maintenance": true
}

Códigos de estado

Cuando el fallo está en el organismo (TGSS/Sistema RED, SEPE, DEHU, AEAT, Hacienda de Navarra) o en el sistema conectado, el código HTTP dice si merece la pena reintentar. El cuerpo es siempre el formato de error habitual (success, message, status, data, errors): léelo en cualquier código, el motivo está en message.

Los errores de validación de Saltra siguen siendo 422 (no reintentes hasta corregir los datos).

Ejemplo de 503 reintentable:

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Retry-After: 60
X-Saltra-Error: organism-unavailable

{
  "success": false,
  "message": "Error de conexión de SALTRA con el (SISTEMA RED).",
  "status": 503,
  "data": [],
  "errors": {
    "tgss": ["Error de conexión de SALTRA con el (SISTEMA RED)."]
  },
  "maintenance": false,
  "retryable": true,
  "retry_after": 60
}

Mantenimiento

Cuando la Seguridad Social o el Sistema RED están en mantenimiento o no operativos, la API responde 503 con maintenance: true y la cabecera Retry-After con los segundos que debes esperar. Reintentar antes devuelve el mismo 503.

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

{
  "success": false,
  "message": "SISTEMA RED: No operativo o en mantenimiento, inténtelo de nuevo más tarde.",
  "status": 503,
  "errors": {
    "tgss": ["SISTEMA RED: No operativo o en mantenimiento, inténtelo de nuevo más tarde."]
  },
  "maintenance": true,
  "retry_after": 300
}

Límites de consultas

Las peticiones autenticadas están limitadas a 80 por minuto en las consultas (GET) y 120 por minuto en las escrituras (POST). El límite se cuenta por certificado (si se envía X-Cert-Secret) o, en su defecto, por usuario autenticado, y por ruta. Las peticiones no autenticadas se limitan a 60 por minuto por IP. Los endpoints de integración pesada —GET /employee-situations y GET /ta-info-for-nss de Seguridad Social, y GET /contrata/data del SEPE— comparten un cupo combinado más bajo, de 30 peticiones por minuto por certificado (o usuario): consumir uno reduce el cupo de los otros dos.

Saltra publica el estado de tu cupo en las cabeceras de todas las respuestas, para que puedas regular el ritmo de tus llamadas antes de agotarlo.

Ejemplo de respuesta correcta:

HTTP/1.1 200 OK
X-Ratelimit-Limit: 80
X-Ratelimit-Remaining: 45
X-Ratelimit-Reset: 1786012860

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. Combinado con X-Ratelimit-Remaining es lo que te permite espaciar las peticiones cuando te acercas al límite, en vez de detenerte en seco.

Al superar el límite, la API responde 429 Too Many Requests y añade Retry-After:

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

El cuerpo sigue el formato de error habitual:

{
  "success": false,
  "status": 429,
  "message": "Too Many Requests"
}