API de Gestión

Esta API permite a las cuentas de tipo Propietario automatizar la creación y gestión de sus Agencias y Agentes. Todas las peticiones a estos endpoints deben estar autenticadas con la API Key del Propietario.

Autenticación

Todas las peticiones a la API de Gestión deben incluir la cabecera X-Owner-API-Key con la API Key del Propietario. Este API está pensado principalmente para integraciones server-to-server.

Ejemplo de Cabecera

X-Owner-API-Key: tu_api_key_de_propietario

Nota CORS: si vas a llamar estos endpoints desde un frontend en el navegador, asegúrate de que el servidor permite la cabecera X-Owner-API-Key en el preflight (CORS Access-Control-Allow-Headers). Para uso típico recomendado (server-to-server), no es necesario.

Endpoints de Agencias

POST /api/management/agencies

Crea una nueva cuenta de tipo Agencia bajo el Propietario autenticado.

Cuerpo de la Petición

application/json

{
    "name": "Agencia de Viajes Demo",
    "email": "contacto@agenciademo.com",
    "password": "una_contraseña_fuerte",
    "consumes_owner_tokens": true,
    "contact_person": "Ana García",
    "phone_number": "+34123456789",
    "address_line1": "Calle Falsa 123",
    "city": "Madrid",
    "postal_code": "28001",
    "country": "ES",
    "notes": "Observaciones opcionales"
}

Notas:

consumes_owner_tokens es booleano y por defecto true.
Los demás campos mostrados son opcionales y pueden omitirse.

Respuesta Exitosa (201 Created)

Devuelve el objeto completo de la agencia creada, incluyendo su propia API Key.

application/json

{
    "id": 15,
    "name": "Agencia de Viajes Demo",
    "email": "contacto@agenciademo.com",
    "api_key": "una_nueva_api_key_para_la_agencia",
    "account_type": "agencia",
    "owner_propietario_id": 1
    // ... otros campos
}

Errores comunes

400 – Validación (faltan campos obligatorios o tipos inválidos).
409 – Duplicado (email ya existe / “in use”).
500 – Error interno.

Endpoints de Agentes

POST /api/management/agents

Crea un Agente que depende directamente del Propietario autenticado (no de una Agencia).

Cuerpo de la Petición

application/json

{
    "name": "Agente Propietario",
    "username": "opcional_para_login",
    "password": "requerido_si_hay_username"
}

Respuesta Exitosa (201 Created)

application/json

{
    "id": 101,
    "name": "Agente Propietario",
    "username": "agente.prop",
    "token": "token_unico",
    "is_active": true,
    "created_at": "2025-05-12T10:15:30Z"
}

Errores comunes

400 – Falta name, o se envía username sin password.
409 – Duplicado (nombre de usuario “ya existe/in use”).
500 – Error interno.

POST /api/management/agencies/<agency_id>/agents

Crea un Agente (token de empleado) para una Agencia específica del Propietario. El agency_id debe pertenecer a una Agencia que sea propiedad del Propietario autenticado.

Cuerpo de la Petición

application/json

{
    "name": "Agente de Soporte (Agencia Demo)",
    "username": "agente.soporte.demo",
    "password": "password_para_el_agente"
}

Respuesta Exitosa (201 Created)

Devuelve el objeto del agente creado, incluyendo su token único.

application/json

{
    "id": 101,
    "name": "Agente de Soporte (Agencia Demo)",
    "username": "agente.soporte.demo",
    "token": "un_token_unico_para_este_agente",
    "is_active": true,
    "created_at": "2025-05-12T10:15:30Z",
    "agency_id": 15,
    "agency_name": "Agencia de Viajes Demo"
}

Errores comunes

400 – Validación (faltan campos o tipos inválidos).
404 – El agency_id no existe o no pertenece al Propietario autenticado.
409 – Duplicado (nombre de usuario “ya existe/in use”).
500 – Error interno.