SEPE

Conecta tus aplicaciones con funciones del SEPE.

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.

URL base

https://api.saltra.es/api/v4/sepe

Errores

Los errores recibidos en la API del SEPE o errores de validación.

• 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 del SEPE o errores de validación.
  • sepe: Errores relacionados con el SEPE.
  • regimen: Errores de validación.
• maintenance (booleano) : Cuando el SEPE 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": {
    "sepe": [
      "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

El código HTTP distingue si la consulta tiene respuesta, si el problema está en lo que nos has enviado o si el fallo es del SEPE. Úsalo para decidir si merece la pena reintentar.

Ejemplo de 503 (Certific@ en mantenimiento):

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 valor de Retry-After depende del caso. Cuando Saltra ya sabe que el SEPE 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. En el 503 con retryable: true (no hemos podido comunicarnos con el SEPE) es de 60 segundos por defecto.

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