Venda os tours da Ada Vegas no seu próprio site

1. Visão geral

A Partner API é uma API REST JSON sobre HTTPS. Tudo o que você faz no portal de clientes (ver tours, cotar, reservar, cancelar, consultar saldo) está disponível por programação.

• Seu preço é um único preço de atacado/agência por tour e temporada. Você decide quanto o seu cliente paga.
• Seu saldo paga cada venda. Se acabar, a reserva ainda é aceita, mas fica pendente até você recarregar (veja Crédito).
• A Ada Vegas é avisada de cada venda em tempo real: sua agência, o tour, a data, os passageiros e o valor.

2. Início rápido

1. No seu portal, abra API e integração → Chaves e crie uma chave. Crie primeiro uma chave Sandbox para testar sem nenhuma cobrança. O secret é exibido uma única vez.
2. Opcionalmente, restrinja a chave aos IPs do seu servidor (IPs confiáveis).
3. Chame a 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. Ainda sem conta? Teste tudo agora mesmo com as credenciais demo públicas: chave demo-key-adavegas, secret demo-secret-adavegas. Suas chaves próprias de produção e sandbox são emitidas quando sua conta é aprovada.

Exemplo completo: cotar, reservar, consultar

# 1. preço exato para 2 adultos + 1 criança
curl "$BASE/services/12/quote?date=2026-11-10&pax=2&children=1" -H "X-Api-Key: $KEY" -H "X-Api-Secret: $SECRET"

# 2. criar a reserva (pode ser repetida com segurança graças à chave de idempotência)
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. depois: status
curl "$BASE/bookings/AB-2026-8DB0391E" -H "X-Api-Key: $KEY" -H "X-Api-Secret: $SECRET"

3. Autenticação e segurança

• Chame a API somente a partir do seu servidor. Nunca coloque o secret em um navegador ou aplicativo móvel.
• É possível definir IPs confiáveis por chave (IPs isolados ou CIDR, como 203.0.113.0/24); os demais recebem 403.
• Uma chave ativa por ambiente (produção / sandbox). Gerar uma nova revoga a anterior.
• Sempre HTTPS. O corpo da requisição é limitado a 64 KB.

4. Convenções

5. Crédito e saldo

Cada venda é paga com o seu saldo pré-pago (na moeda da sua conta: TRY, USD ou EUR).

• Ao reservar: o total é debitado imediatamente (convertido para a moeda da sua conta pela cotação do dia, se o tour estiver em outra moeda).
• Sem saldo? O saldo fica negativo (dívida) e a reserva permanece pending com hold_reason: "insufficient_credit". Ela não é confirmada até que sua dívida esteja dentro do limite permitido.
• Recarga no portal (Saldo → Pagar com cartão, de 10 a 50.000) ou por transferência bancária (a Ada Vegas registra). As reservas pendentes são então confirmadas automaticamente se a aprovação automática estiver ativada para você; caso contrário, pela equipe da Ada Vegas.
• Cancelar uma reserva pendente: o valor integral volta ao seu saldo na hora.
• credit_limit é a dívida que a Ada Vegas permite a você (0 por padrão). available = balance + credit_limit.
• As reservas Sandbox nunca tocam no seu saldo.

6. Ciclo da reserva

Mudanças permitidas: pending → confirmed, pending → cancelled, confirmed → cancelled (cancelamentos de reservas confirmadas são tratados pela Ada Vegas; entre em contato). Cada mudança dispara um webhook.

Canais (campo channel): api (sua integração), portal (feitas no portal), site (feitas pelo seu próprio site, veja a seção 12; você as confirma no seu portal).

7. Preços e cotações

• Os preços são definidos por temporadas, com um único preço por adulto, um child_price opcional (vazio = igual ao do adulto) e min_pax / max_pax opcionais (contam adultos + crianças).
• Tours com hospedagem exigem occupancy (p. ex. single, double, triple) e rooms; a cotação lista as opções válidas por quarto.
• Sempre chame /quote antes de reservar. Ele executa exatamente o mesmo cálculo de POST /bookings. Em /services, unit_price e pricing.applicable mostram o preço de adulto para a data escolhida; crianças, limites de grupo e hospedagem só aparecem na cotação.

8. Endpoints

Sua conta, moeda, estado do webhook e resumo de crédito.

{"data":{"id":22,"name":"Sua Agência","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}}}

Taxas de câmbio usadas nas conversões (base TRY).

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

Categorias de tours disponíveis para você, com a definição de seus campos adicionais (key, label, type, required, options).

Tours que você pode vender, com o seu preço para uma data.

Cada tour contém:

Um tour, com a mesma estrutura. 404 service_not_found se não existir ou não estiver disponível para você.

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

Com hospedagem, options lista {occupancy,label,per_room} e accommodation devolve a opção escolhida com o detalhamento breakdown por hotel; total = tour + hospedagem. Erros: 422 com no_price_for_date, pax_below_min / pax_above_max (mais limit), invalid_occupancy, no_accommodation_price.

Retorna 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 é o valor debitado na moeda da sua conta. status é confirmed de imediato somente se a aprovação automática estiver ativada para você e o seu crédito for suficiente; caso contrário, pending (veja hold_reason).

Suas reservas, das mais recentes às mais antigas. Filtros: status (pending|confirmed|cancelled), customer_email, channel (api|portal|site), from / to (data de criação), page, per_page.

Uma reserva (mesma estrutura). 404 booking_not_found.

Cancela uma reserva pendente e devolve o valor integral ao seu saldo. Uma reserva confirmada retorna 409 not_cancellable: entre em contato com a Ada Vegas.

Resumo do saldo e últimos lançamentos (?limit=1..100, padrão 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 (±, correção manual da Ada Vegas).

Configuração do seu site como definida no portal (nome, idiomas, cores, páginas, quais tours são exibidos e a sua margem). Usada pelo pacote de site pronto para usar; 404 site_disabled até você publicar. Veja a seção 12.

9. Webhooks

Em vez de consultar periodicamente, defina uma URL de webhook no portal (API e integração → Webhook). Um secret de assinatura é gerado para você.

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 a assinatura

Assinatura = HMAC-SHA256(corpo bruto da requisição, secret do webhook), em hexadecimal, com o prefixo sha256=. Compare em tempo constante e use o corpo bruto, não um 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, com 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 com qualquer 2xx em até 10 segundos. Qualquer outra resposta é repetida até 5 vezes com espera crescente (cerca de 2, 4, 8 e 16 minutos). Depois disso o evento é descartado; use GET /bookings para conciliar.
• As entregas entram em fila e são enviadas em cerca de um minuto. Os eventos podem chegar repetidos ou fora de ordem: trate-os como "a reserva X mudou, consulte o estado dela" e torne o seu tratador idempotente.

10. Sandbox

Crie uma chave Sandbox no portal. Ela se comporta como a produção, mas: as reservas são marcadas com "sandbox": true, o seu saldo nunca é cobrado nem reembolsado, e a equipe da Ada Vegas não é avisada. Os webhooks são enviados normalmente (com sandbox: true) para você testar o seu receptor de ponta a ponta. Usa a mesma URL base da produção; só a chave muda. Para dar uma olhada sem conta, use a demo pública (dados de exemplo, nada é armazenado).

11. Integração 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'] é "confirmed" ou "pending"; mostre ao cliente o seu próprio preço e guarde $b['data']['booking_ref']
}

12. Vender no seu próprio site

Duas formas, ambas usam a mesma API:

A. Pacote de site pronto para usar ("Vitrin")

Um site de viagens somente front-end que você envia para a sua própria hospedagem (PHP 8.1+, sem banco de dados). No portal (Meu site) você gerencia nome, cores, textos (ES/EN/TR), páginas, quais tours ficam visíveis e a sua margem %. Os visitantes veem o seu preço = preço Ada Vegas + a sua margem, nunca o nosso. O pedido de um visitante vira uma reserva na sua conta (debitada ao preço da Ada Vegas) e aparece em Reservas → Meu site, onde você confirma ou cancela; o viajante recebe e-mails no seu idioma e uma página "Minhas reservas". As atualizações são aplicadas pelo portal com um clique.

B. Seu próprio site ou sistema

Crie as suas próprias páginas com /services e /quote e crie as reservas a partir do servidor. Para usar a margem e os e-mails da configuração publicada do seu site, adicione em POST /bookings:

13. Erros

Uma reserva aceita, mas aguardando crédito, não é um erro: você recebe 201 com status: "pending" e hold_reason: "insufficient_credit".

14. Boas práticas

• Cote logo antes de reservar; preços e temporadas podem mudar.
• Envie sempre um X-Idempotency-Key e, em caso de timeout, repita a mesma requisição com a mesma chave.
• Guarde em cache o conteúdo dos tours (/services) por alguns minutos para ficar longe do limite de uso; não chame a API a cada visita.
• Trate o pending: mostre "solicitação recebida" ao seu cliente até chegar o webhook booking.confirmed.
• Acompanhe credit.can_confirm e recarregue antes da alta temporada; ative com a Ada Vegas a aprovação automática para confirmações sem intervenção.
• Registre o booking_ref de cada chamada. O Registro de requisições do portal mostra cada chamada com hora, IP e status.
• Troque as chaves se um secret puder ter vazado (portal → gerar uma nova chave).

15. Suporte

Dúvidas, cancelamento de reservas confirmadas, aumento de limite, aprovação automática ou ajuda com a integração: fale com o seu gerente de conta na Ada Vegas. Informe o booking_ref e o horário da requisição.

Ada Vegas Partner API v1