Skip to main content

Guía general de APIs

Esta sección describe cómo consumir las APIs expuestas por la plataforma apolo-app-platcom-platform, los patrones comunes de autenticación, versionado, manejo de errores y herramientas de soporte (Swagger, Bruno y Postman).

Panorama general​

La plataforma expone múltiples servicios backend (NestJS) organizados en un monorepo Nx. Los más relevantes para consumo externo son:

  • bff-api: Backend for Frontend. Puerta de entrada principal para el portal web y consumidores internos.
  • auth-api: Autenticación y gestión de sesión.
  • applications-api: Gestión de aplicaciones/módulos.
  • core-api: Lógica de dominio central.
  • reports-api: Generación y consulta de reportes.
  • tenants-api: Multi-tenant y segmentación por compañía/país.

En entornos productivos, el acceso suele realizarse a través del BFF o de un API Gateway corporativo, mientras que en desarrollo se consumen servicios directamente por puerto.

Autenticación​

La autenticación principal se realiza mediante JWT enviado en el header Authorization:

Authorization: Bearer <token>

El flujo típico es:

  • Obtener token mediante auth-api (/auth/login o equivalente).
  • Usar ese token para consumir el resto de endpoints (BFF, core, applications, reports, etc.).

Algunos endpoints internos de `auth-api pueden usar tokens de ADFS / IAM, pero esto se gestiona de forma transparente desde los servicios backend.

Paginación​

Cuando aplica, se utilizan parámetros estándar:

  • page: número de página (base 1).
  • limit: cantidad de registros por página.
  • Opcionalmente: sort, order.

Entornos y URLs​

En desarrollo local, las URLs típicas son:

  • BFF: http://localhost:8080
  • Auth API: http://localhost:8082
  • Applications API: http://localhost:8084
  • Reports API: http://localhost:8086
  • Tenants API: http://localhost:8081
  • Core API: http://localhost:8089

Los valores reales se obtienen desde las variables de entorno (BFF_API_URL, `AUTH_API_URL, etc.) generadas por Seki.

Ejemplo rápido (cURL)​

Autenticarse:

curl -X POST http://localhost:8080/auth/login \
-H "Authorization: Bearer <tokenADFS>"

Consumir endpoint protegido (ejemplo, vía BFF):

curl http://localhost:8080/user-reports/user-events/search \
-H "Authorization: Bearer <tokenPlataformaRegional>"

Para detalle por herramienta, consulta: