Introducción

URLs base por entorno

Variable	Test	Producción
BASE_URL_IDP	https://backend.idp-test.eje.gob.bo	https://backend.idp.eje.gob.bo
BASE_URL_SPS	https://backend.sps-test.eje.gob.bo	https://backend.sps.eje.gob.bo

En las páginas siguientes, reemplace BASE_URL_IDP o BASE_URL_SPS por la URL del entorno objetivo.

Documentación OpenAPI

Ambos backends generan su especificación OpenAPI con drf-spectacular y la publican en las mismas rutas:

Ruta	Contenido
/api/schema/	Especificación OpenAPI (YAML; JSON con ?format=json)
/api/docs/	Swagger UI
/api/redoc/	ReDoc

Ejemplo: BASE_URL_SPS/api/docs/.

La especificación OpenAPI es la referencia completa de cada endpoint (campos de request y response, códigos de estado y ejemplos). Esta sección resume los endpoints disponibles y los requisitos para consumirlos.

Autenticación

Todas las APIs REST de /api/v1/ requieren un access token emitido por el IDP, enviado en la cabecera:

Authorization: Bearer <access_token>

• La audiencia del token es eje-idp-api.
• El cliente OAuth2 debe tener asignados los scopes que exige cada endpoint y solicitarlos al pedir el token.
• Para integraciones sistema a sistema se usa client_credentials; para acciones en nombre de un usuario, authorization_code + PKCE.

Cómo valida el token cada backend:

Backend	Validación
IDP	Contra su base de tokens emitidos: verifica que exista, que no esté revocado ni expirado y que tenga la audiencia esperada.
SPS	Localmente como JWT: firma con las claves del jwks_uri del IDP, issuer del discovery, audiencia eje-idp-api, claims obligatorios exp, iss, aud, sub y token_use=access_token. Los scopes se leen del claim scope.

INFO

Como el SPS valida el JWT localmente, un token revocado en el IDP sigue siendo aceptado por el SPS hasta que expira.

Respuestas de error

Código	Significado
400	Parámetros o cuerpo inválidos
401	Token ausente, inválido o expirado
403	El token no tiene el scope requerido
404	Recurso no encontrado (o no visible para el cliente)

El formato del cuerpo de error difiere entre backends; se detalla en la página de cada uno.

Raíz de la API

Cada grupo de recursos expone en su prefijo una vista raíz (generada por el DefaultRouter de Django REST Framework) que lista los recursos disponibles. Por ejemplo, GET BASE_URL_SPS/api/v1/.