Frontend Integration Handbook

Guia operativa del flujo del proyecto

Esta pagina resume el flujo funcional del backend para el equipo frontend: onboarding, autenticacion, creacion de perfil, vacantes, matching, planes y estados operativos. Swagger sigue siendo la fuente de contrato detallado, pero aqui tienes el paso a paso del flujo de negocio para implementar pantallas y llamadas.

Navegacion rapida

Lectura rapida de la API

1. Autenticacion

Todo arranca en /api/v1/auth. El login devuelve tokens y desde ahi el front opera por rol.

2. Metadata publica

El onboarding expone sectores, paises, regiones y skills sin token para construir formularios dinamicos.

3. Operacion protegida

Candidatos, planes, vacantes y matching requieren bearer token y validan rol.

Flujo paso a paso para candidato

1

Consultar metadata y catálogos de utilidades

Antes de renderizar los formularios de registro o vacantes, el front debe precargar catálogos desde /api/v1/utils/metadata o en llamadas separadas.

GET /api/v1/utils/metadata
GET /api/v1/utils/sectors
GET /api/v1/utils/countries
GET /api/v1/utils/regions?countryId=COUNTRY_ID
GET /api/v1/utils/skills?sectorId=SECTOR_ID
2

Registrar usuario base

El usuario candidato se crea primero en auth. Ese paso genera la identidad de acceso, no el perfil completo del candidato.

POST /api/v1/auth/register
{
  "email": "candidate1@example.com",
  "password": "Secret123",
  "role": "CANDIDATE"
}
3

Iniciar sesion y persistir tokens

El frontend debe guardar accessToken y refreshToken. El access token se usa en cada llamada protegida.

POST /api/v1/auth/login
{
  "email": "candidate1@example.com",
  "password": "Secret123"
}
4

Crear perfil del candidato

Con token y rol CANDIDATE, el frontend crea el perfil funcional con sector, region, experiencia y skills.

POST /api/v1/candidates
Authorization: Bearer <accessToken>
{
  "sectorId": "SECTOR_ID",
  "countryId": "COUNTRY_ID",
  "regionId": "REGION_ID",
  "name": "Juan Perez",
  "yearsOfExperience": 4,
  "videoSpanishUrl": "https://example.com/video-es.mp4",
  "videoEnglishUrl": "https://example.com/video-en.mp4",
  "photoUrls": ["https://example.com/photo1.jpg"],
  "skills": [
    { "skillId": "SKILL_1", "name": "JavaScript", "level": 4 },
    { "skillId": "SKILL_2", "name": "Node.js", "level": 3 }
  ]
}
5

Subir CV

La carga de CV usa multipart/form-data. El campo esperado es file.

POST /api/v1/candidates/:id/upload-cv
Authorization: Bearer <accessToken>
Content-Type: multipart/form-data
field: file
6

Consultar planes y suscribirse

El candidato puede listar planes y luego suscribirse con PATCH /api/v1/candidates/:id/subscribe.

GET /api/v1/plans
Authorization: Bearer <accessToken>

PATCH /api/v1/candidates/:id/subscribe
Authorization: Bearer <accessToken>
{
  "planId": "PREMIUM"
}

Flujo paso a paso para empresa y matching

1

Registrar o autenticar empresa

La empresa usa el mismo modulo auth, pero con rol COMPANY.

POST /api/v1/auth/register
{
  "email": "company@example.com",
  "password": "Secret123",
  "role": "COMPANY"
}
2

Crear vacante

La vacante es el origen del matching. El endpoint exige token y rol empresa.

POST /api/v1/job-positions
Authorization: Bearer <accessToken>
{
  "companyId": "COMPANY_ID",
  "sectorId": "SECTOR_ID",
  "title": "Backend Developer",
  "description": "Node.js, APIs y PostgreSQL",
  "requiredYearsOfExperience": 3,
  "skills": ["JavaScript", "Node.js", "PostgreSQL"],
  "skillWeight": 0.7,
  "experienceWeight": 0.3
}
3

Solicitar deck de matching

Una vez creada la vacante, el front de empresa consulta el deck para recibir candidatos compatibles.

GET /api/v1/matching/deck/:jobPositionId
Authorization: Bearer <accessToken>
4

Procesar swipe

El matching se confirma enviando la decision del swipe. El valor aceptado para swipeDirection es LEFT o RIGHT.

POST /api/v1/matching/swipe
Authorization: Bearer <accessToken>
{
  "jobPositionId": "JOB_POSITION_ID",
  "candidateId": "CANDIDATE_ID",
  "companyId": "COMPANY_ID",
  "swipeDirection": "RIGHT"
}
5

Consultar matches del candidato

El lado candidato puede revisar coincidencias usando su identificador.

GET /api/v1/candidates/:id/matches
Authorization: Bearer <accessToken>
6

Gestion de planes por admin

Los planes se crean y administran desde rol ADMIN. El frontend de administracion necesita este flujo separado.

POST /api/v1/plans
PATCH /api/v1/plans/:id
DELETE /api/v1/plans/:id
Authorization: Bearer <adminAccessToken>

Checklist de integracion frontend

Gestion de tokens

Guardar access y refresh token. Renovar con POST /api/v1/auth/refresh-token cuando el access token expire.

Roles

El front debe dirigir flujos por rol: CANDIDATE, COMPANY y ADMIN.

Estado operativo

Antes de flujos criticos, consultar /api/health. Si la BD esta desconectada, mostrar mantenimiento parcial.

Clientes HTTP REST del proyecto

Además del Swagger, hay una vista adicional para consultar los requests REST del proyecto y usarlos como base para fetch, axios o cualquier cliente del frontend. Esta vista centraliza los archivos .http del backend y refleja el mismo contrato que expone la API documentada en Swagger.

Vista centralizada

Abre /http-requests.html para ver todos los clientes.

Archivos incluidos

auth.http, candidate-onboarding.context.http, candidates.http, plans.http, job-positions.http y matching.http.

Mapa de endpoints del proyecto

POST /api/v1/auth/register

Registro base del usuario. Define el rol inicial.

POST /api/v1/auth/login

Login y obtencion de tokens.

POST /api/v1/auth/refresh-token

Renueva el access token.

POST /api/v1/auth/logout

Cierre de sesion.

GET /api/v1/onboarding/metadata

Catalogos agregados para formularios.

GET /api/v1/onboarding/sectors

Sectores disponibles.

GET /api/v1/onboarding/sectors/:id

Detalle de un sector.

GET /api/v1/onboarding/countries

Paises disponibles.

GET /api/v1/onboarding/regions?countryId=...

Regiones filtradas por pais.

GET /api/v1/onboarding/skills?sectorId=...

Skills filtradas por sector.

POST /api/v1/candidates

Creacion de perfil de candidato.

GET /api/v1/candidates

Listado de candidatos con filtros.

GET /api/v1/candidates/:id

Detalle de candidato.

GET /api/v1/candidates/:id/matches

Matches del candidato.

POST /api/v1/candidates/:id/upload-cv

Subida de CV.

PATCH /api/v1/candidates/:id

Actualizacion del perfil de candidato.

PATCH /api/v1/candidates/:id/subscribe

Suscripcion del candidato a un plan.

POST /api/v1/job-positions

Creacion de vacantes para empresa.

GET /api/v1/companies/:companyId/job-positions

Listado de vacantes creadas por la empresa.

GET /api/v1/utils/sectors

Listado de sectores de utilidad.

GET /api/v1/utils/skills

Listado de skills de utilidad.

GET /api/v1/matching/deck/:jobPositionId

Deck de candidatos para una vacante.

POST /api/v1/matching/swipe

Procesa decision de matching.

GET /api/v1/plans

Listado de planes activos o visibles.

GET /api/v1/plans/:id

Detalle de plan.

POST /api/v1/plans

Creacion de plan, solo ADMIN.

PATCH /api/v1/plans/:id

Actualizacion de plan, solo ADMIN.

DELETE /api/v1/plans/:id

Borrado de plan, solo ADMIN.

Patrones de request que el front debe contemplar

Request JSON autenticado

fetch("/api/v1/candidates", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${accessToken}`
  },
  body: JSON.stringify(payload)
})

Request multipart para CV

const formData = new FormData();
formData.append("file", file);

fetch(`/api/v1/candidates/${candidateId}/upload-cv`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`
  },
  body: formData
})

Renovacion de token

fetch("/api/v1/auth/refresh-token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ refreshToken })
})

Chequeo de salud

fetch("/api/health")
  .then((response) => response.json())
  .then((data) => {
    if (data.status === "degraded") {
      // Mostrar advertencia de BD desconectada
    }
  })

Notas operativas para frontend

Fuente de verdad

Usa esta guia para flujo y Swagger para payloads exactos, respuestas y cambios futuros de contrato.

Control por rol

No expongas UI de empresa o admin si el token corresponde a candidato. El backend valida rol, pero el front debe evitar flujos invalidos.

Limitacion actual

Si el backend responde degraded, la API sigue arriba pero las operaciones que dependan de la BD pueden fallar. Conviene bloquear acciones transaccionales.