Início rápido
Este guia leva você do nada a uma integração funcional em cerca de 30 minutos. Ao final, você terá:
- preços ao vivo para hotéis em uma cidade, pela Partner API,
- um link de reserva que credita as reservas para sua conta,
- uma reserva de teste e um webhook informando que ela ocorreu.
Tudo acontece em staging, nosso ambiente de testes. Você não precisa pedir acesso para nós, e migrar para produção depois também não precisa de aprovação.
Este é o guia certo para você?
Seção intitulada “Este é o guia certo para você?”| Você quer… | Comece aqui |
|---|---|
| Mostrar hotéis no seu app, site ou produto de IA e enviar viajantes para reservar, ganhando comissão | Este guia |
| Reservar em nome dos seus clientes como agência de viagens licenciada | Este guia até o Passo 5, depois Reservar como agência de viagens |
| Incorporar hotéis reserváveis sem escrever uma integração | Web Components |
| Permitir que um agente de IA pesquise e reserve | MCP Servers e Agentic Payments |
| Conectar um channel manager ou PMS | Adicione seu Channel Manager |
Como funciona
Seção intitulada “Como funciona”Você usa a Partner API para encontrar hotéis e seus preços ao vivo. Cada hotel vem com um urlName estável. Você o transforma em um link para o Wink Booking Engine, book.wink.travel, carregando seus IDs. O viajante reserva e paga lá, e a reserva é creditada para sua conta.
Antes de começar
Seção intitulada “Antes de começar”Você vai precisar de:
grpcurl, ou Postman ou Insomnia. A Partner API é gRPC, não REST.curl.
Passo 1: Crie uma conta em staging
Seção intitulada “Passo 1: Crie uma conta em staging”O staging é completamente separado da produção, com logins e contas próprios.
-
Vá para staging-app.wink.travel, clique em
Sign-In / Registere registre-se. -
Clique em
Accountsna barra lateral esquerda, depois emCreate, e escolha I am an Affiliate. As reservas que você enviar serão creditadas para esta conta. Veja Criar Conta.
Passo 2: Crie uma aplicação
Seção intitulada “Passo 2: Crie uma aplicação”A aplicação fornece as credenciais para seu código.
-
No cartão da sua conta, clique em
Actions>Manage account, depois na abaApplications. -
Clique em
Create new application, dê um nome e escolha Machine-to-machine como tipo de cliente. -
Em scopes, selecione Inventory & rates (leitura). A Partner API verifica
inventory.read. -
Clique em
Create applicatione 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.
Passo 3: Obtenha um token de acesso
Seção intitulada “Passo 3: Obtenha um token de acesso”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"Salve o access_token da resposta:
export WINK_TOKEN=<access_token>Tokens expiram. No seu próprio código, use uma biblioteca OAuth2 para buscá-los e renová-los. Veja Authentication.
Se a solicitação do token for rejeitada, a resposta é um corpo JSON com um código error:
error | Status HTTP | Causa comum |
|---|---|---|
invalid_client | 401 | Client ID ou secret errado, ou credenciais de produção usadas no staging-iam |
invalid_scope | 400 | A solicitação pede um scope para o qual a aplicação não está registrada |
unauthorized_client | 400 | A aplicação não tem permissão para usar o grant client_credentials |
invalid_request | 400 | Falta um parâmetro obrigatório, por exemplo quando o corpo é JSON em vez de formulário |
Passo 4: Encontre seu ID de conta
Seção intitulada “Passo 4: Encontre seu ID de conta”Cada chamada da Partner API nomeia a conta para a qual você está atuando no cabeçalho managing-entity-id. Liste as contas que seu token pode atuar:
grpcurl -H "authorization: Bearer $WINK_TOKEN" \ -d '{}' \ staging-partner.wink.travel:443 wink.partner.v1.Accounts/ListAccountsCopie o accountId da conta afiliada do Passo 1:
export WINK_ACCOUNT_ID=<accountId>Passo 5: Pesquise hotéis em uma cidade
Seção intitulada “Passo 5: Pesquise hotéis em uma cidade”O staging tem hotéis de teste com disponibilidade em Bangkok, então esta busca usa seu slug, bangkok-thailand:
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/SearchByCityUse uma data de check-in no futuro; datas passadas são rejeitadas. Cada resultado traz:
name,starRatingeheroImageUrl, suficientes para mostrar uma linha de resultado,roomTypes, as ofertas ao vivo, quarto mais barato primeiro,urlName, o slug que você 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, então 12500 é $125,00).
Não sabe o slug de uma cidade? Resolva 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.
Passo 6: Monte o link de reserva
Seção intitulada “Passo 6: Monte o link de reserva”https://staging-book.wink.travel/hotel/<urlName>?client-id=<YOUR_CLIENT_ID>&configuration-id=<YOUR_CUSTOMIZATION_ID><urlName>é ourlNamedo hotel do Passo 5.client-idé o Client ID da sua aplicação do Passo 2.configuration-idé seu ID de customização:Manage account>Customizations. Uma customização também define sua marca, idioma padrão e moeda na página de reserva.
Passe a busca do viajante
Seção intitulada “Passe a busca do viajante”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âmetro | Significado | Exemplo |
|---|---|---|
sd | Data do check-in | sd=2027-03-14 |
n ou ed | Número de noites, ou data do check-out | n=2 ou ed=2027-03-16 |
rc | Hóspedes por quarto | rc=a2 (2 adultos) |
l | Idioma de exibição | l=en |
c | Moeda de exibição | c=USD |
p | Código de promoção | p=ABC123 |
Esses parâmetros sobrescrevem os padrões definidos na sua customizaçã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; ele não pode pré-selecionar um quarto ou tarifa. O viajante escolhe o quarto na página do hotel, pelo preço ao vivo.
Veja Linkando diretamente para linkar para a página inicial do motor de reservas em vez de um hotel específico.
Passo 7: Faça uma reserva de teste
Seção intitulada “Passo 7: Faça uma reserva de teste”Abra 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; ele começa com WNK.
Passo 8: Receba notificações sobre reservas
Seção intitulada “Passo 8: Receba notificações sobre reservas”-
No Portal, vá para
Applications > Webhookse adicione um endpoint que aceite requisiçõesPOST. -
Inscreva-se em
booking.create, ou deixe a lista de eventos vazia para receber tudo enquanto desenvolve. -
Envie um evento de teste para você mesmo, depois faça outra reserva de teste e veja chegar.
Verifique a assinatura de cada entrega antes de confiar nela. Veja Integração de Webhook e o Catálogo de Eventos de Webhook.
Passo 9: Vá para produção
Seção intitulada “Passo 9: Vá para produção”Não há etapa de aprovação para desenvolvedores. (Contas de agência de viagens são certificadas primeiro; veja abaixo.) Quando sua integração funcionar em staging:
-
Crie uma conta e uma aplicação em app.wink.travel, como nos Passos 1 e 2. Credenciais não são transferidas entre ambientes.
-
Remova
staging-de todos os hosts:Staging Produção https://staging-iam.wink.travelhttps://iam.wink.travelstaging-partner.wink.travel:443partner.wink.travel:443https://staging-book.wink.travelhttps://book.wink.travel -
Consulte novamente seu ID de conta de produção (Passo 4) e ID de customização (Passo 6). Eles são diferentes do staging.
O uso da Partner API é medido em noites de hotel, com uma cota mensal gratuita. Veja Partner API para preços e limites.
Reservar como agência de viagens
Seção intitulada “Reservar como agência de viagens”Se sua conta for uma agência de viagens licenciada, você não precisa enviar viajantes para book.wink.travel: pode criar reservas diretamente com wink.partner.v1.Booking/CreateBooking e gerenciá-las com as outras chamadas Booking. Outras contas enviam viajantes para o link de reserva.
Contas de agência de viagens são certificadas: a Wink revisa o registro de cada agência antes que ela possa reservar. Agências que desejam cobrar diretamente seus clientes, como comerciante registrado, devem reservar via Partner API e obter aprovação por escrito da Wink. Veja Começando como Agência de Viagens e a referência da Partner API.
Próximos passos
Seção intitulada “Próximos passos”- Gere um cliente tipado a partir do esquema
.protoem vez de chamargrpcurlmanualmente. - Conecte o servidor MCP e use as AI Skills para que seu assistente de código escreva a integração contra a API ao vivo.
- Leia a lista completa de ambientes e hosts.
