Arquitectura de Conectividad

Suite Aerya B2B Integrators API

Plataforma canónica para que aerolíneas comerciales, agencias y sistemas de distribución consulten disponibilidad en tiempo real, coticen tarifas homologadas, emitan PNRs directamente en sus PSS (KIU / Amadeus / Propietarios) y cobren a través de PayHub.

Producción (Live)

https://api.suite-aerya.com

Emisión directa de PNRs reales y liquidación financiera PayHub.

Staging & Sandbox

https://staging-api.suite-aerya.com

Ambiente sandbox para pruebas de homologación y simulación de pagos.

Local Dev Runners

http://localhost:8001 (client)

Puerto 8001 para Backoffice/Client y 8000 para User Service.

Autenticación por Service Account

Todas las solicitudes B2B deben enviar el token Bearer en la cabecera estándar.

Cabecera de Autorización:

Authorization: Bearer sa_live_83b2a7d4e1c2b5...

Tenant Scoping Obligatorio:

X-Organization-Id: rutaca

El valor de X-Organization-Id asegura aislamiento estricto de catálogos de vuelos, tarifas, reservas y credenciales PSS entre aerolíneas.

Estándar de Errores RFC 7807 (Problem Details)

Respuestas predecibles y estructuradas con tipo MIME application/problem+json.

RFC 7807 / 9457

Ejemplo de respuesta devuelta ante un error de validación o conflicto:

{
  "type": "https://api.suite-aerya.com/errors/validation-error",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "El campo 'origin' debe ser un código IATA válido de 3 letras.",
  "instance": "/api/v1/integrators/flights/search",
  "code": "VALIDATION_ERROR",
  "trace_id": "9f83b2a7-d4e1-4c2b-9513-1b731ca356ed",
  "request_id": "req-05d8cfee910e",
  "timestamp": "2026-09-16T13:30:00Z",
  "invalid_params": [
    {
      "name": "origin",
      "reason": "Expected 3 uppercase letters matching airport database",
      "location": "body"
    }
  ]
}

Trazabilidad Distribuida (W3C & Request ID)

Monitoreo extremo a extremo de cada transacción a través de la infraestructura.

X-Request-Id

Identificador único correlacionado en logs estructurados JSON y respuestas de error.

X-Trace-Id

Identificador W3C Trace Context propagado hacia Google Cloud Trace / Cloud Logging.

X-API-Version

Retornado en todas las respuestas salientes como 1.0.

Idempotencia IETF en Operaciones Mutantes

Evita emisiones de PNR duplicadas o dobles cobros ante reintentos automáticos.

IETF Draft

Envíe un identificador único UUIDv4 en la cabecera Idempotency-Key para cualquier petición POST a /api/v1/integrators/reservations o /api/v1/integrators/payments/checkout.

Replay Automático

Respuestas previas cacheadas 24h con X-Cache-Lookup: HIT.

Bloqueo de Concurrencia

Llamadas concurrentes reciben 409 CONCURRENT_REQUEST.

Validación Payload

Reuso con payload alterado devuelve 422 MISMATCH.

Rate Limiting por Ventana Deslizante (RFC 429)

Protege la capacidad operativa del PSS y la infraestructura de cobro.

Cada respuesta HTTP incluye el estado de cuota en las cabeceras estándar:

Límite Total: X-RateLimit-Limit: 100

Cupo Restante: X-RateLimit-Remaining: 94

Tiempo de Reinicio: X-RateLimit-Reset: 1773719460

Webhooks con Firma HMAC-SHA256

Entrega garantizada de eventos de estado de reservas y confirmaciones de pago.

Anti-Replay 5m

Formato de Cabecera:

X-Aerya-Signature: t=1773719400,v1=5264b38d35f49ef47bc2a6f87d3a2410a8c2b7f32901c...

Código de Verificación

import hmac
import hashlib
import time

def verify_aerya_webhook(raw_body: bytes, sig_header: str, secret: str) -> bool:
    """Verifica autenticidad y previene ataques de repetición."""
    parts = dict(p.strip().split("=", 1) for p in sig_header.split(","))
    timestamp = int(parts["t"])
    signature = parts["v1"]

    # 1. Ventana de tolerancia anti-repetición de 5 minutos (300s)
    if abs(time.time() - timestamp) > 300:
        return False

    # 2. Computar HMAC sobre "{timestamp}.{body}"
    payload = f"{timestamp}.".encode("utf-8") + raw_body
    computed = hmac.new(secret.encode("utf-8"), payload, hashlib.sha256).hexdigest()

    # 3. Comparación en tiempo constante para mitigar timing attacks
    return hmac.compare_digest(computed, signature)

import * as crypto from 'crypto';

export function verifyAeryaWebhook(
  rawBody: Buffer | string,
  sigHeader: string,
  secret: string
): boolean {
  const parts = Object.fromEntries(
    sigHeader.split(',').map((p) => p.trim().split('=', 2))
  );
  const timestamp = parseInt(parts['t'], 10);
  const signature = parts['v1'];

  // 1. Ventana de tolerancia de 5 minutos
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > 300) {
    return false;
  }

  // 2. Computar HMAC SHA256
  const payload = Buffer.concat([
    Buffer.from(`${timestamp}.`),
    Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody)
  ]);
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');

  // 3. Comparación segura en tiempo constante
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Simulador y Validador HMAC en Vivo

Web Crypto API

Calcula en tiempo real la firma criptográfica para probar tu implementación local sin enviar solicitudes al servidor.

Webhook Secret:

Timestamp (Unix segundos):

Payload JSON (Raw Body):

Catálogo de Endpoints Canónicos

Especificación técnica interactiva con ejemplos de carga y respuesta.

POST /api/v1/integrators/flights/search — Consulta de disponibilidad en PSS

Consulta de itinerarios y vuelos disponibles consultando directamente el inventario vivo de la aerolínea (KIU, Amadeus o motor nativo).

Request Body (JSON):

{
  "origin": "CCS",
  "destination": "PMV",
  "departure_date": "2026-10-15",
  "passengers": {
    "adults": 2,
    "children": 1,
    "infants": 0
  },
  "cabin_class": "economy"
}

Response 200 OK:

{
  "search_id": "sch_98a7c2b5",
  "flights": [
    {
      "flight_number": "7V-302",
      "departure": "2026-10-15T08:30:00-04:00",
      "arrival": "2026-10-15T09:20:00-04:00",
      "available_seats": 9,
      "base_fare": 95.00,
      "currency": "USD"
    }
  ]
}

POST /api/v1/integrators/flights/quote — Desglose de impuestos, tasas y equipaje

Cotización vinculante con cálculo oficial de impuestos aeroportuarios, combustible e IATA.

Request Body:

{
  "flight_number": "7V-302",
  "departure_date": "2026-10-15",
  "fare_basis": "YSTD",
  "passengers": { "adults": 1, "children": 0, "infants": 0 }
}

Response 200 OK:

{
  "quote_id": "qte_48f1c9",
  "total": 115.40,
  "currency": "USD",
  "breakdown": {
    "base_fare": 95.00,
    "taxes": 12.40,
    "airport_fee": 8.00
  },
  "expires_in_seconds": 900
}

POST /api/v1/integrators/reservations — Creación de PNR en el PSS

Importante: Este endpoint requiere la cabecera obligatoria Idempotency-Key para garantizar que ningún PNR sea creado dos veces.

Request Body:

{
  "quote_id": "qte_48f1c9",
  "passengers": [
    {
      "first_name": "CARLOS",
      "last_name": "MENDEZ",
      "document_type": "passport",
      "document_number": "V18392019",
      "birth_date": "1990-05-12",
      "nationality": "VEN"
    }
  ],
  "contact": {
    "email": "carlos.mendez@example.com",
    "phone": "+584141234567"
  }
}

Response 201 Created:

{
  "reservation_id": "66e74f1b2c45e89a",
  "pnr": "HRWRZX",
  "status": "confirmed",
  "time_limit": "2026-09-16T18:00:00Z",
  "total_amount": 115.40,
  "currency": "USD"
}

GET /api/v1/integrators/reservations/{pnr_or_id} — Consulta de PNR y estado

POST /api/v1/integrators/reservations/cancel — Cancelación masiva o individual de PNRs

Permite a las aerolíneas u organizaciones integradas sincronizar la cancelación de reservas notificando códigos PNR cancelados en el PSS o mostrador. El endpoint valida el contexto de su organización y únicamente actualiza el estado a cancelled para las reservas registradas en Suite Aerya.

Procesamiento Tolerante: Los PNRs no encontrados no detienen el lote; se reportan en not_found_pnrs. Las reservas previamente canceladas se reportan en already_cancelled_pnrs (idempotente).

Carga Polimórfica: Puede enviar un arreglo de strings ["HRWRZX", "AVR982"], un arreglo de objetos [{"pnr": "HRWRZX"}], o un PNR individual en pnr: "HRWRZX".

Request Body:

{
  "pnrs": [
    "HRWRZX",
    "AVR982"
  ],
  "reason": "Cancelado en mostrador PSS",
  "cancelled_at": "2026-09-17T18:30:00Z"
}

Response 200 OK:

{
  "success": true,
  "total_received": 2,
  "cancelled_count": 1,
  "cancelled_pnrs": [
    "HRWRZX"
  ],
  "already_cancelled_pnrs": [],
  "not_found_pnrs": [
    "AVR982"
  ],
  "timestamp": "2026-09-17T18:30:05.123456Z"
}

POST /api/v1/integrators/payments/checkout — Generación de enlace de pago

CRUD /api/v1/integrators/webhooks — Registro, consulta y revocación de callbacks

Permite registrar URLs receptoras para recibir notificaciones HTTP en tiempo real firmadas con HMAC-SHA256 cuando ocurran eventos en la aerolínea (ej. confirmación de PNR, pago en PayHub o emisión de e-ticket).

Request Body — Registrar Webhook (POST):

{
  "target_url": "https://mi-sistema.com/api/webhooks/aerya",
  "events": [
    "reservation.confirmed",
    "payment.succeeded",
    "ticket.issued"
  ],
  "secret": "whsec_live_9a8b7c6d5e4f"
}

Response 201 Created:

{
  "subscription_id": "whsub_948f2c1b",
  "target_url": "https://mi-sistema.com/api/webhooks/aerya",
  "status": "active",
  "events": [
    "reservation.confirmed",
    "payment.succeeded",
    "ticket.issued"
  ],
  "created_at": "2026-09-16T14:30:00Z"
}

Operaciones CRUD Disponibles:

POST /webhooks Crear nueva suscripción

GET /webhooks Listar suscripciones del tenant

DELETE /webhooks/{id} Revocar suscripción