Pular para o conteúdo

Início Rápido

Este guia leva-o do nada a uma integração funcional em cerca de 30 minutos. No final terá:

  • preços ao vivo para hotéis numa cidade, a partir da Partner API,
  • um link de reserva que credita as reservas à sua conta,
  • uma reserva de teste e um webhook a informar que aconteceu.

Tudo acontece em staging, o nosso ambiente de testes. Não precisa de pedir-nos acesso, e passar para produção mais tarde também não requer aprovação.

Quer…Comece aqui
Mostrar hotéis na sua app, site ou produto de IA e enviar viajantes para reservar, ganhando comissãoEste guia
Reservar em nome dos seus clientes como agência de viagens licenciadaEste guia até ao Passo 5, depois Reservar como agência de viagens
Incorporar hotéis reserváveis sem escrever uma integraçãoWeb Components
Permitir que um agente de IA pesquise e reserveMCP Servers e Agentic Payments
Ligar um channel manager ou PMSAdicionar o seu Channel Manager

Usa a Partner API para encontrar hotéis e os seus preços ao vivo. Cada hotel tem um urlName estável. Transforma-o num link para o Wink Booking Engine, book.wink.travel, com os seus IDs. O viajante reserva e paga lá, e a reserva é creditada à sua conta.

Vai precisar de:

  • grpcurl, ou Postman ou Insomnia. A Partner API é gRPC, não REST.
  • curl.

O staging é completamente separado da produção, com logins e contas próprios.

  1. Vá a staging-app.wink.travel, clique em Sign-In / Register e registe-se.

  2. Clique em Accounts na barra lateral esquerda, depois em Create, e escolha I am an Affiliate. As reservas que enviar são creditadas a esta conta. Veja Criar Conta.

A aplicação fornece as credenciais ao seu código.

  1. No cartão da sua conta, clique em Actions > Manage account, depois no separador Applications.

  2. Clique em Create new application, dê-lhe um nome e escolha Machine-to-machine como tipo de cliente.

  3. Em scopes, selecione Inventory & rates (leitura). A Partner API verifica inventory.read.

  4. Clique em Create application e copie o Client ID e o Client secret. O segredo é mostrado uma vez e não pode ser recuperado depois.

Veja Applications para os outros tipos de cliente e scopes.

Janela do terminal
curl -X POST https://staging-iam.wink.travel/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=<YOUR_CLIENT_ID>" \
-d "client_secret=<YOUR_CLIENT_SECRET>" \
-d "scope=inventory.read"

Guarde o access_token da resposta:

Janela do terminal
export WINK_TOKEN=<access_token>

Os tokens expiram. No seu próprio código, use uma biblioteca OAuth2 para os obter e renovar. Veja Authentication.

Se o pedido do token for rejeitado, a resposta é um corpo JSON com um código error:

errorEstado HTTPCausa habitual
invalid_client401Client ID ou segredo errado, ou credenciais de produção usadas no staging-iam
invalid_scope400O pedido pede um scope para o qual a aplicação não está registada
unauthorized_client400A aplicação não tem permissão para usar o grant client_credentials
invalid_request400Falta um parâmetro obrigatório, por exemplo quando o corpo é JSON em vez de formulário

Cada chamada da Partner API indica a conta para a qual está a atuar no cabeçalho managing-entity-id. Liste as contas para as quais o seu token pode atuar:

Janela do terminal
grpcurl -H "authorization: Bearer $WINK_TOKEN" \
-d '{}' \
staging-partner.wink.travel:443 wink.partner.v1.Accounts/ListAccounts

Copie o accountId da conta afiliada do Passo 1:

Janela do terminal
export WINK_ACCOUNT_ID=<accountId>

O staging tem hotéis de teste com disponibilidade em Bangkok, por isso esta pesquisa usa o seu slug, bangkok-thailand:

Janela do terminal
grpcurl -H "authorization: Bearer $WINK_TOKEN" \
-H "managing-entity-id: $WINK_ACCOUNT_ID" \
-d '{
"urlName": "bangkok-thailand",
"userSession": {
"itinerary": {
"startDate": "2026-12-01",
"nights": 2,
"room": { "adults": 2 }
},
"currencyCode": "USD",
"languageCode": "en"
}
}' \
staging-partner.wink.travel:443 wink.partner.v1.Search/SearchByCity

Use uma data de check-in no futuro; uma data passada é rejeitada. Cada resultado inclui:

  • name, starRating e heroImageUrl, suficientes para mostrar uma linha de resultado,
  • roomTypes, as ofertas ao vivo, quarto mais barato primeiro,
  • urlName, o slug que precisa para o link de reserva.

Os preços são inteiros em unidades menores: divida por 10 elevado ao currencyExponent da resposta (2 para USD, por isso 12500 é $125.00).

Não sabe o slug de uma cidade? Resolva-o com wink.partner.v1.Lookup/Search. Para o conteúdo completo de uma propriedade, use o serviço Content. A referência da Partner API documenta todas as chamadas.

https://staging-book.wink.travel/hotel/<urlName>?client-id=<YOUR_CLIENT_ID>&configuration-id=<YOUR_CUSTOMIZATION_ID>
  • <urlName> é o urlName do hotel do Passo 5.
  • client-id é o Client ID da sua aplicação do Passo 2.
  • configuration-id é o seu ID de personalização: Manage account > Customizations. Uma personalização define também a sua marca, idioma e moeda padrão na página de reserva.

Adicione as datas, hóspedes, idioma e moeda do viajante ao mesmo link para que a página do hotel abra com esses dados preenchidos:

https://staging-book.wink.travel/hotel/<urlName>?client-id=<YOUR_CLIENT_ID>&configuration-id=<YOUR_CUSTOMIZATION_ID>&sd=2027-03-14&n=2&rc=a2&l=en&c=USD
ParâmetroSignificadoExemplo
sdData de check-insd=2027-03-14
n ou edNúmero de noites, ou data de check-outn=2 ou ed=2027-03-16
rcHóspedes por quartorc=a2 (2 adultos)
lIdioma de exibiçãol=en
cMoeda de exibiçãoc=USD
pCódigo de promoçãop=ABC123

Estes parâmetros substituem os padrões definidos na sua personalização. O guia do botão Book Now cobre o formato completo de rc, incluindo crianças e vários quartos.

O link abre a página do hotel; não pode pré-selecionar um quarto ou tarifa. O viajante escolhe o quarto na página do hotel, ao preço ao vivo.

Veja Linking directly para ligar à página inicial do motor de reservas em vez de a um hotel específico.

Abra o seu link, escolha datas e um quarto, e finalize com um cartão de teste Stripe, por exemplo 4242 4242 4242 4242 com qualquer data de validade futura e qualquer CVC. Nenhum cartão real é cobrado em staging. Anote o código da reserva na página de confirmação; começa com WNK.

  1. No Portal, vá a Applications > Webhooks e adicione um endpoint que aceite pedidos POST.

  2. Subscreva booking.create, ou deixe a lista de eventos vazia para receber tudo enquanto desenvolve.

  3. Envie um evento de teste para si próprio, depois faça outra reserva de teste e veja-a chegar.

Verifique a assinatura de cada entrega antes de confiar nela. Veja Webhook Integration e o Catálogo de Eventos Webhook.

Não há passo de aprovação para desenvolvedores. (Contas de agências de viagens são certificadas primeiro; veja abaixo.) Quando a sua integração funcionar em staging:

  1. Crie uma conta e uma aplicação em app.wink.travel, como nos Passos 1 e 2. As credenciais não são transferidas entre ambientes.

  2. Remova staging- de todos os hosts:

    StagingProdução
    https://staging-iam.wink.travelhttps://iam.wink.travel
    staging-partner.wink.travel:443partner.wink.travel:443
    https://staging-book.wink.travelhttps://book.wink.travel
  3. Procure novamente o ID da sua conta de produção (Passo 4) e o ID de personalização (Passo 6). São diferentes dos de staging.

O uso da Partner API é medido em noites de hotel, com uma franquia mensal gratuita. Veja Partner API para preços e limites.

Se a sua conta for uma agência de viagens licenciada, não precisa de enviar viajantes para book.wink.travel: pode criar reservas diretamente com wink.partner.v1.Booking/CreateBooking e geri-las com as outras chamadas Booking. Outras contas enviam viajantes para o link de reserva.

As contas de agências de viagens são certificadas: a Wink revê o registo de cada agência antes de poder reservar. Agências que queiram cobrar diretamente aos seus clientes, como comerciante registado, devem reservar através da Partner API e obter aprovação escrita da Wink. Veja Começar como Agência de Viagens e a referência da Partner API.