Especificación API - Pines Volotea Map

1. Contexto

La aplicación ya guarda los pines localmente en el dispositivo mediante localStorage. Ahora se necesita una API remota para sincronizar esos pines y recuperarlos de forma persistente.

La integración más sencilla para el frontend es que el backend respete el id que envía la app. Actualmente ese id se genera en frontend con crypto.randomUUID().

Importante: si el backend genera otro ID diferente, habrá que añadir una lógica extra de mapeo local/remoto. Para evitarlo, se recomienda usar el mismo id enviado por frontend como identificador principal del pin.

2. Modelo de datos del pin

{
  id: string;
  name: string;
  code?: string;
  lat: number;
  lng: number;
  country?: string;
  source: 'google';
  placeId?: string;
  createdAt: string;
  updatedAt: string;
}

Campos

Campo	Tipo	Obligatorio	Descripción
`id`	string	Sí	UUID generado por el frontend. Debe mantenerse igual en remoto.
`name`	string	Sí	Nombre visible del pin. Normalmente nombre del aeropuerto.
`code`	string	No	Código IATA del aeropuerto, por ejemplo `VGO`, `VIT`, `LHR`.
`lat`	number	Sí	Latitud del pin.
`lng`	number	Sí	Longitud del pin.
`country`	string	No	País del aeropuerto. Puede venir como código ISO, por ejemplo `ES`.
`source`	string	No	Actualmente en frontend está tipado como `google`, aunque los datos vienen de una base local de aeropuertos. Se puede mantener para evitar cambios.
`placeId`	string	No	Identificador del aeropuerto en la base local usada por frontend, por ejemplo `LEVX`.
`createdAt`	string ISO date	Sí	Fecha de creación en formato ISO.
`updatedAt`	string ISO date	Sí	Fecha de última modificación en formato ISO. En la implementación actual coincidirá normalmente con la fecha de creación, ya que los pines no se editan desde la interfaz.

Ejemplo de pin

{
  "id": "8b4e7d9b-6a3a-4d4f-9f2f-1d9d6a44c001",
  "name": "Vigo Airport",
  "code": "VGO",
  "lat": 42.2318,
  "lng": -8.6268,
  "country": "ES",
  "source": "google",
  "placeId": "LEVX",
  "createdAt": "2026-05-20T09:30:00.000Z",
  "updatedAt": "2026-05-20T09:30:00.000Z"
}

3. Endpoints necesarios

3.1. Listar todos los pines

GET/api/pins

Debe devolver todos los pines guardados para el contexto correspondiente.

[
  {
    "id": "8b4e7d9b-6a3a-4d4f-9f2f-1d9d6a44c001",
    "name": "Vigo Airport",
    "code": "VGO",
    "lat": 42.2318,
    "lng": -8.6268,
    "country": "ES",
    "source": "google",
    "placeId": "LEVX",
    "createdAt": "2026-05-20T09:30:00.000Z",
    "updatedAt": "2026-05-20T09:30:00.000Z"
  }
]

3.2. Crear un pin

PUT/api/pins/{id}

Debe crear el pin recibido usando como identificador el id enviado por frontend.

Actualmente los pines no se editan desde la aplicación. Solo se añaden o se eliminan, por lo que no es necesario implementar una actualización funcional.

Se recomienda que este endpoint sea idempotente: si se envía de nuevo un pin con el mismo id, puede devolver el pin existente o sobrescribirlo con los mismos datos, pero no debe duplicarlo.

Body enviado por frontend:

{
  "id": "8b4e7d9b-6a3a-4d4f-9f2f-1d9d6a44c001",
  "name": "Vigo Airport",
  "code": "VGO",
  "lat": 42.2318,
  "lng": -8.6268,
  "country": "ES",
  "source": "google",
  "placeId": "LEVX",
  "createdAt": "2026-05-20T09:30:00.000Z",
  "updatedAt": "2026-05-20T09:30:00.000Z"
}

Respuesta recomendada al crear correctamente:

{
  "success": true,
  "pin": {
    "id": "8b4e7d9b-6a3a-4d4f-9f2f-1d9d6a44c001",
    "name": "Vigo Airport",
    "code": "VGO",
    "lat": 42.2318,
    "lng": -8.6268,
    "country": "ES",
    "source": "google",
    "placeId": "LEVX",
    "createdAt": "2026-05-20T09:30:00.000Z",
    "updatedAt": "2026-05-20T09:30:00.000Z"
  }
}

Nota: si en el futuro se añade edición de nombre, coordenadas u otros datos, se podría reutilizar este mismo endpoint PUT /api/pins/{id} como actualización.

3.3. Eliminar un pin

DELETE/api/pins/{id}

Debe eliminar el pin correspondiente al id recibido.

{
  "success": true
}

4. Requisitos

La API debe responder siempre en formato JSON.
El backend debe respetar el id enviado por frontend.
El endpoint de listado debe devolver la lista completa de pines del contexto correspondiente.
El endpoint de creación debe aceptar todos los campos del modelo.
El endpoint de borrado debe funcionar por id.
Las fechas deben mantenerse en formato ISO string.

5. Información que necesitamos

Base URL final de la API.
Si hay autenticación o no.
En caso de autenticación, headers necesarios.
Formato exacto de errores.
Confirmación de si los pines son globales para todos los dispositivos o si dependen de dispositivo, sala, usuario o instalación.

Punto pendiente importante: hay que confirmar si la lista de pines es global para todos los dispositivos o si cada dispositivo debe tener su propia lista. Esto afecta directamente a cómo el backend debe almacenar y devolver los datos.

6. Lógica prevista en frontend

Al iniciar la app: llamar a GET /api/pins y guardar la respuesta en local.
Al crear un pin: guardar localmente y llamar a PUT /api/pins/{id}.
Al borrar un pin: borrar localmente y llamar a DELETE /api/pins/{id}.