Venda los tours de Ada Vegas en su propia web

1. Resumen

La Partner API es una API REST JSON sobre HTTPS. Todo lo que puede hacer en su portal de cliente (ver tours, cotizar, reservar, cancelar, consultar saldo) está disponible por programación.

• Su precio es un único precio mayorista/agencia por tour y temporada. Usted decide cuánto paga su cliente.
• Su saldo paga cada venta. Si se agota, la reserva se acepta igualmente pero queda pendiente hasta que recargue (vea Crédito).
• Ada Vegas recibe aviso de cada venta en tiempo real: su agencia, el tour, la fecha, los pasajeros y el importe.

2. Inicio rápido

1. En su portal abra API e integración → Claves y cree una clave. Cree primero una clave Sandbox para probar sin ningún cargo. El secreto se muestra una sola vez.
2. Opcionalmente restrinja la clave a las IP de su servidor (IP de confianza).
3. Llame a la API:

curl "https://api.adavegastravel.com/v1/services?date=2026-11-10&pax=2" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "X-Api-Secret: YOUR_SECRET" \
  -H "Accept-Language: es"

URL base: https://api.adavegastravel.com/v1. ¿Aún sin cuenta? Pruebe todo ahora mismo con las credenciales demo públicas: clave demo-key-adavegas, secreto demo-secret-adavegas. Sus claves propias de producción y sandbox se emiten al aprobar su cuenta.

Ejemplo completo: cotizar, reservar, consultar

# 1. precio exacto para 2 adultos + 1 niño
curl "$BASE/services/12/quote?date=2026-11-10&pax=2&children=1" -H "X-Api-Key: $KEY" -H "X-Api-Secret: $SECRET"

# 2. crear la reserva (se puede reintentar gracias a la clave de idempotencia)
curl -X POST "$BASE/bookings" \
  -H "X-Api-Key: $KEY" -H "X-Api-Secret: $SECRET" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-10045" \
  -d '{"service_id":12,"pax":2,"children":1,"service_date":"2026-11-10",
       "customer_name":"Ana Pérez","customer_email":"ana@example.com",
       "customer_phone":"+34600111222","notes":"Vegetariana"}'

# 3. después: estado
curl "$BASE/bookings/AB-2026-8DB0391E" -H "X-Api-Key: $KEY" -H "X-Api-Secret: $SECRET"

3. Autenticación y seguridad

• Llame a la API solo desde su servidor. Nunca ponga el secreto en un navegador o app móvil.
• Puede fijar IP de confianza por clave (IP sueltas o CIDR como 203.0.113.0/24); el resto recibe 403.
• Una clave activa por entorno (producción / sandbox). Generar una nueva revoca la anterior.
• Siempre HTTPS. El cuerpo de la petición está limitado a 64 KB.

4. Convenciones

5. Crédito y saldo

Cada venta se paga con su saldo prepagado (en la moneda de su cuenta: TRY, USD o EUR).

• Al reservar: el total se descuenta de inmediato (convertido a la moneda de su cuenta al cambio del día si el tour tiene otra moneda).
• ¿Sin saldo? El saldo pasa a negativo (deuda) y la reserva queda pending con hold_reason: "insufficient_credit". No se confirma hasta que su deuda esté dentro del límite permitido.
• Recarga en el portal (Saldo → Pagar con tarjeta, de 10 a 50.000) o por transferencia bancaria (Ada Vegas la registra). Las reservas pendientes se confirman entonces automáticamente si tiene activada la aprobación automática; si no, las confirma el personal de Ada Vegas.
• Cancelar una reserva pendiente: el importe completo vuelve a su saldo al instante.
• credit_limit es la deuda que Ada Vegas le permite (0 por defecto). available = balance + credit_limit.
• Las reservas Sandbox nunca tocan su saldo.

6. Ciclo de la reserva

Cambios permitidos: pending → confirmed, pending → cancelled, confirmed → cancelled (las cancelaciones de reservas confirmadas las gestiona Ada Vegas; contáctenos). Cada cambio dispara un webhook.

Canales (campo channel): api (su integración), portal (hechas en el portal), site (hechas desde su propia web, vea la sección 12; usted las confirma en su portal).

7. Precios y cotizaciones

• Los precios se definen por temporadas con un único precio por adulto, un child_price opcional (vacío = igual que adulto) y min_pax / max_pax opcionales (cuentan adultos + niños).
• Los tours con alojamiento requieren occupancy (p. ej. single, double, triple) y rooms; la cotización lista las opciones válidas por habitación.
• Llame siempre a /quote antes de reservar. Ejecuta el mismo cálculo exacto que POST /bookings. En /services, unit_price y pricing.applicable muestran el precio de adulto para la fecha elegida; niños, límites de grupo y alojamiento solo están en la cotización.

8. Endpoints

Su cuenta, moneda, estado del webhook y resumen de crédito.

{"data":{"id":22,"name":"Su Agencia","status":"active","currency":"EUR","sandbox":false,
 "contact":{"name":"...","email":"...","phone":null},"webhook_configured":false,
 "credit":{"balance":825.28,"currency":"EUR","credit_limit":0,"available":825.28,"can_confirm":true}}}

Tipos de cambio usados en las conversiones (base TRY).

{"data":{"base":"TRY","rates":{"USD":32.1,"EUR":35.2,"TRY":1},"supported":["TRY","USD","EUR"]}}

Categorías de tours disponibles para usted, con la definición de sus campos adicionales (key, label, type, required, options).

Tours que puede vender, con su precio para una fecha.

Cada tour contiene:

Un tour, con la misma estructura. 404 service_not_found si no existe o no está disponible para usted.

{"data":{"ok":true,"date":"2026-10-29","pax":2,"children":1,"min_pax":null,"max_pax":null,
 "currency":"EUR","season":"Otoño 2026",
 "tour":{"unit":58.24,"child_unit":58.24,"total":174.72},
 "options":[],"accommodation":null,"total":174.72}}

Con alojamiento, options lista {occupancy,label,per_room} y accommodation devuelve la opción elegida con el desglose breakdown por hotel; total = tour + alojamiento. Errores: 422 con no_price_for_date, pax_below_min / pax_above_max (más limit), invalid_occupancy, no_accommodation_price.

Devuelve 201:

{"data":{"booking_ref":"AB-2026-8DB0391E","service_id":1,"service_name":"Istanbul Classics",
  "pax":2,"children":1,"currency":"EUR","unit_price":58.24,"total_price":174.72,
  "service_date":"2026-10-29","customer_name":"Ana Pérez","status":"confirmed",
  "sandbox":false,"channel":"api","sale_total":null,"customer_lang":null,
  "credit_charged":"174.72","hold_reason":null,"created_at":"2026-10-26T10:44:12+00:00"},
 "credit":{"balance":825.28,"currency":"EUR","credit_limit":0,"available":825.28,"can_confirm":true}}

credit_charged es el importe descontado en la moneda de su cuenta. status es confirmed de inmediato solo si tiene activada la aprobación automática y su crédito alcanza; si no, pending (revise hold_reason).

Sus reservas, las más recientes primero. Filtros: status (pending|confirmed|cancelled), customer_email, channel (api|portal|site), from / to (fecha de creación), page, per_page.

Una reserva (misma estructura). 404 booking_not_found.

Cancela una reserva pendiente y devuelve el importe completo a su saldo. Una reserva confirmada devuelve 409 not_cancellable: contacte con Ada Vegas.

Resumen del saldo y últimos movimientos (?limit=1..100, por defecto 20).

{"data":{"balance":825.28,"currency":"EUR","credit_limit":0,"available":825.28,"can_confirm":true,
 "transactions":[
  {"type":"charge","amount":-174.72,"currency":"EUR","balance_after":825.28,"booking_ref":"AB-2026-8DB0391E","reference":null,"created_at":"..."},
  {"type":"topup","amount":1000,"currency":"EUR","balance_after":1000,"booking_ref":null,"reference":"BANK-2210","created_at":"..."}]}}

Tipos: topup (+), charge (−), refund (+), adjust (±, corrección manual de Ada Vegas).

Configuración de su web tal como la definió en el portal (nombre, idiomas, colores, páginas, qué tours se muestran y su margen). La usa el paquete web listo para usar; 404 site_disabled hasta que publique. Vea la sección 12.

9. Webhooks

En lugar de consultar periódicamente, configure una URL de webhook en el portal (API e integración → Webhook). Se genera un secreto de firma para usted.

POST https://your-site.example/hooks/adavegas
Content-Type: application/json
X-Agency-Webhook-Event: booking.confirmed
X-Agency-Webhook-Signature: sha256=3b1f...e9

{"event":"booking.confirmed","booking_ref":"AB-2026-8DB0391E","status":"confirmed",
 "service_id":1,"service_name":"Istanbul Classics","customer_name":"Ana Pérez","customer_email":"ana@example.com",
 "channel":"api","credit_charged":"174.72","pax":2,"children":1,"service_date":"2026-10-29",
 "currency":"EUR","total_price":174.72,"sandbox":false,"occurred_at":"2026-10-26T10:44:12+00:00"}

Verificar la firma

Firma = HMAC-SHA256(cuerpo crudo de la petición, secreto del webhook), en hexadecimal, con el prefijo sha256=. Compare en tiempo constante y use el cuerpo crudo, no un JSON recodificado.

// PHP
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_AGENCY_WEBHOOK_SIGNATURE'] ?? '')) { http_response_code(401); exit; }

// Node.js (Express, con express.raw({type:'application/json'}))
const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(req.body).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.get('X-Agency-Webhook-Signature') || ''));

Entrega

• Responda con cualquier 2xx en menos de 10 segundos. Cualquier otra respuesta se reintenta hasta 5 veces con espera creciente (aprox. 2, 4, 8 y 16 minutos). Después el evento se descarta; use GET /bookings para conciliar.
• Las entregas se encolan y se envían en aproximadamente un minuto. Los eventos pueden llegar repetidos o desordenados: trátelos como "la reserva X cambió, consulte su estado" y haga su manejador idempotente.

10. Sandbox

Cree una clave Sandbox en el portal. Se comporta como producción pero: las reservas se marcan con "sandbox": true, su saldo nunca se cobra ni se reembolsa, y el personal de Ada Vegas no recibe avisos. Los webhooks sí se envían (con sandbox: true) para que pruebe su receptor de principio a fin. Usa la misma URL base que producción; solo cambia la clave. Para echar un vistazo sin cuenta, use la demo pública (datos de ejemplo, no se guarda nada).

11. Integración típica (servidor)

// PHP 8, cURL
function av(string $method, string $path, ?array $body = null, array $headers = []): array {
    $ch = curl_init('https://api.adavegastravel.com/v1' . $path);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => $method, CURLOPT_TIMEOUT => 20,
        CURLOPT_HTTPHEADER => array_merge(['X-Api-Key: ' . getenv('AV_KEY'), 'X-Api-Secret: ' . getenv('AV_SECRET'),
            'Content-Type: application/json', 'Accept-Language: es'], $headers),
        CURLOPT_POSTFIELDS => $body ? json_encode($body, JSON_UNESCAPED_UNICODE) : null,
    ]);
    $out = curl_exec($ch); $code = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch);
    return [$code, json_decode((string) $out, true)];
}

[$c, $q] = av('GET', '/services/12/quote?date=2026-11-10&pax=2&children=1');
if ($c === 200) {
    [$c, $b] = av('POST', '/bookings', ['service_id' => 12, 'pax' => 2, 'children' => 1, 'service_date' => '2026-11-10',
        'customer_name' => 'Ana Pérez'], ['X-Idempotency-Key: order-10045']);
    // $b['data']['status'] es "confirmed" o "pending"; muestre a su cliente su propio precio y guarde $b['data']['booking_ref']
}

12. Vender en su propia web

Dos formas, ambas usan la misma API:

A. Paquete web listo para usar ("Vitrin")

Una web de viajes solo de front-end que sube a su propio hosting (PHP 8.1+, sin base de datos). Desde el portal (Mi web) gestiona su nombre, colores, textos (ES/EN/TR), páginas, qué tours son visibles y su margen %. Los visitantes ven su precio = precio Ada Vegas + su margen, nunca el nuestro. La solicitud de un visitante se convierte en una reserva de su cuenta (descontada al precio de Ada Vegas) y aparece en Reservas → Mi web, donde usted confirma o cancela; el viajero recibe correos en su idioma y una página "Mis reservas". Las actualizaciones se aplican desde el portal con un clic.

B. Su propia web o sistema

Cree sus propias páginas con /services y /quote y cree las reservas desde el servidor. Para usar el margen y los correos de la configuración publicada de su web, añada a POST /bookings:

13. Errores

Una reserva aceptada pero a la espera de crédito no es un error: recibe 201 con status: "pending" y hold_reason: "insufficient_credit".

14. Buenas prácticas

• Cotice justo antes de reservar; precios y temporadas pueden cambiar.
• Envíe siempre un X-Idempotency-Key y, ante un timeout, repita la misma petición con la misma clave.
• Guarde en caché el contenido de los tours (/services) unos minutos para mantenerse lejos del límite de uso; no llame a la API en cada visita.
• Gestione pending: muestre "solicitud recibida" a su cliente hasta que llegue el webhook booking.confirmed.
• Vigile credit.can_confirm y recargue antes de temporada alta; active con Ada Vegas la aprobación automática para confirmaciones sin intervención.
• Registre el booking_ref de cada llamada. El Registro de peticiones del portal muestra cada llamada con hora, IP y estado.
• Rote las claves si un secreto pudo filtrarse (portal → generar una clave nueva).

15. Soporte

Consultas, cancelación de reservas confirmadas, aumentos de límite, aprobación automática o ayuda con la integración: contacte con su responsable de cuenta en Ada Vegas. Indique el booking_ref y la hora de la petición.

Ada Vegas Partner API v1