API REST del SPS

Backend: backend-seleccion-postulantes (app interoperabilidad). URL base: BASE_URL_SPS/api/v1/.

API de solo lectura para que sistemas externos consulten información de los procesos de selección. No expone operaciones de creación, modificación ni eliminación.

Convenciones

• Autenticación: Authorization: Bearer <access_token> emitido por el IDP (ver Introducción). Se aceptan tokens obtenidos con client_credentials o authorization_code + PKCE.

• Alcance de los datos: solo se exponen convocatorias con resultados publicados.

• Paginación: por desplazamiento (limit / offset).

  Recurso	Default limit	Máximo
  General	20	100
  postulaciones	10	50
  historial-postulaciones	Sin paginación	—

• Formato de error (Django REST Framework):

  { "detail": "..." }

  Para parámetros requeridos faltantes: { "<parametro>": "Parámetro requerido." }.

Endpoints

Método	Ruta	Descripción	Parámetros	Scope
GET	convocatorias/	Lista convocatorias con resultados publicados	limit, offset	seleccion:convocatorias:read
GET	convocatorias/{codigo}/	Obtiene una convocatoria	codigo (path)	seleccion:convocatorias:read
GET	ofertas-departamentales/	Plazas ofertadas por departamento	convocatoria (requerido), limit, offset	seleccion:convocatorias:read
GET	postulantes-admitidos/	Postulantes admitidos de una convocatoria	convocatoria (requerido), limit, offset	seleccion:admitidos:read
GET	postulaciones/	Historial de postulaciones de una persona	usuario_base (requerido, idp_sub), limit, offset	seleccion:postulaciones:read
GET	usuarios-base/{idp_sub}/	Datos de identidad y contacto de un postulante	idp_sub (path)	seleccion:postulaciones:read
GET	historial-postulaciones/	Búsqueda en postulaciones actuales e históricas	termino (requerido)	seleccion:historialpostulaciones:read

Notas:

• convocatorias/ es el punto de entrada: de allí se obtienen los codigo que usan los demás recursos. El codigo puede contener /.
• historial-postulaciones/: termino acepta un número de documento o un nombre de al menos 3 caracteres.
• usuarios-base/ no tiene listado; solo consulta por idp_sub (el sub del usuario en el IDP). Es el identificador para correlacionar a una persona entre sistemas.
• postulantes-admitidos/ y postulaciones/ incluyen el usuario anidado con su idp_sub, email y celular.

Flujo típico de consulta

Referencia completa

Campos de cada respuesta: BASE_URL_SPS/api/docs/.