Adicione o Seu Channel Manager
Este guia orienta os desenvolvedores de channel manager e PMS por todo o processo de integração com a Wink — desde a criação das suas contas até ao mapeamento do inventário e execução do seu primeiro teste end-to-end.
Ambientes
Seção intitulada “Ambientes”A API do Channel Manager (Integrações) está disponível em dois ambientes. Utilize o staging para todo o desenvolvimento e certificação; mude para produção apenas no lançamento.
| Ambiente | URL Base |
|---|---|
| Produção | https://integrations.wink.travel |
| Staging | https://staging-integrations.wink.travel |
Referência da API
Seção intitulada “Referência da API”A API do Channel Manager segue os padrões do protocolo OTA (SOAP/XML) para compatibilidade com sistemas hoteleiros existentes. Comece por rever a documentação dos endpoints para parceiros:
Channel Manager API — Endpoints para parceiros
Passos de integração
Seção intitulada “Passos de integração”-
Crie uma conta de utilizador Wink
Registe-se em staging-app.wink.travel. Todos os passos abaixo usam o ambiente staging — terá de repetir o processo completo em produção antes do lançamento.
-
Crie a sua conta de Afiliado / Channel Manager
Sob o seu novo utilizador, crie uma conta e selecione o tipo de conta Afiliado / Channel Manager. Esta é a conta com que a sua integração irá autenticar.
-
Registe uma aplicação e gere o seu primeiro token
Crie uma Aplicação e associe-a à conta de channel manager do passo 2. Escolha MACHINE_2_MACHINE como tipo de cliente — esta é uma integração servidor-servidor sem utilizador final para redirecionar. Copie imediatamente o Client ID e a Secret Key; a chave secreta é mostrada apenas uma vez e não pode ser recuperada novamente.
A aplicação é o que gera o token bearer que todas as chamadas deste guia transportam como
Authorization: Bearer <access_token>. Troque as suas credenciais por um token usando o grantclient_credentialscontrahttps://staging-iam.wink.travel/oauth2/token, solicitando os scopesintegrations.read integrations.write. Faça isto antes de avançar — não pode consultar identificadores de conta nem aceder a qualquer endpoint do Channel Manager sem um token. Veja Autenticação para o fluxo completo, o host de produção e o catálogo completo de scopes. -
Crie uma conta de Hotel
Sob o mesmo utilizador, crie uma segunda conta e selecione o tipo de conta Hotel. Isto dá-lhe uma propriedade que pode usar para testes sem envolver um hotel real.
-
Confirme que ambas as contas estão aprovadas
Nenhuma conta pode ser usada até estar aprovada: uma conta de channel manager não aprovada não aparece na lista de channel managers de nenhum hotel, e um hotel não aprovado não é retornado pela API.
- Staging — a aprovação é automática. Ambas as contas ficam utilizáveis assim que as cria, e não há nada a solicitar.
- Produção — a aprovação é manual. Envie ao seu contacto de integrações Wink os nomes de ambas as contas e o utilizador a que pertencem, e aguarde confirmação antes de continuar.
-
Ligue as duas contas
Inicie sessão na conta de Hotel e navegue para Canais → Channel manager. Selecione a sua conta de channel manager da lista — isto liga a propriedade à sua integração. Se a sua conta não estiver na lista, ainda não foi aprovada; veja o passo 5.
-
Crie um tipo de quarto básico e um plano tarifário
Dentro da conta de Hotel, crie pelo menos um tipo de quarto e um plano tarifário. Estes são necessários antes que a sua integração possa enviar atualizações de tarifas e disponibilidade ou obter reservas.
-
Mapeie e teste
No seu próprio sistema, mapeie os identificadores do tipo de quarto e plano tarifário retornados pela API. Envie uma atualização de tarifa e uma de disponibilidade, depois faça uma reserva de teste e verifique se o endpoint de obtenção de reservas a retorna corretamente.
Encontrar os identificadores das suas contas
Seção intitulada “Encontrar os identificadores das suas contas”Cada caminho da API do Channel Manager está limitado à sua própria conta:
/api/managing-entity/{managingEntityIdentifier}/channel-manager/...{managingEntityIdentifier} é o ID da conta (um UUID) da sua conta de channel manager — não do hotel. Recupere-o, juntamente com o ID e o estado atual de todas as outras contas que o seu utilizador possui, através da Platform API:
curl -s -X GET \ "https://staging-api.wink.travel/api/managing-entity/list" \ -H "Authorization: Bearer <access_token>" \ -H "Wink-Version: 2.0" \ -H "Accept: application/json"A resposta é um array das contas que possui:
[ { "id": "3f1c8e42-7b90-4d55-a1e2-6c8d09b4f731", "type": "CHANNEL_MANAGER", "name": "O Seu Channel Manager", "status": "ACTIVE" }, { "id": "d5b8a3c2-9e6f-4a1b-8d34-7c2e1f0a5b69", "type": "HOTEL", "name": "A Sua Propriedade de Teste", "urlName": "your-test-property", "status": "ACTIVE" }]- O
idda entrada channel manager é o seu{managingEntityIdentifier}. - O
idda entradaHOTELé o seu{propertyIdentifier}. - O
statusé onde confirma que cada conta está aprovada — mais útil em produção, onde a aprovação é manual. O hotel deve estar com o estadoACTIVEantes de ser reservável ou visível para a API do Channel Manager. A sua conta de channel manager continuará a mostrarPENDING_APPROVALaté passar a Certificação; isso é esperado e não bloqueia o desenvolvimento.
Certificação
Seção intitulada “Certificação”A certificação é como prova — e como a Wink confirma — que a sua integração mapeia corretamente o inventário, envia tarifas e disponibilidade, e recebe reservas de ponta a ponta. Foi desenhada para ser self-service: você conduz cada passo a partir do seu próprio sistema e submete um único pacote de evidências no final. A Wink analisa o pacote e, se aprovado, promove a sua conta de Afiliado / Channel Manager de PENDING_APPROVAL para ACTIVE.
A certificação é feita inteiramente no ambiente staging (https://staging-integrations.wink.travel). Nada nesta secção toca a produção.
O que irá provar
Seção intitulada “O que irá provar”-
Autenticação. O seu cliente OAuth2 consegue obter um token de acesso e chamar com sucesso o endpoint
/pingcontra a sua conta de Afiliado / Channel Manager. -
Mapeamento do inventário. Consegue listar o(s) hotel(s) ligados à sua conta, recuperar a tarifa mestre (tipo de quarto × plano tarifário) que configurou, e identificar corretamente o
masterRateIdentifierque o seu sistema irá usar. -
Envio de tarifa e disponibilidade. Consegue atualizar independentemente os sete dias de uma semana de certificação — uma combinação diferente de valor, quantidade, flags de fechamento na chegada / partida, e limites mínimos/máximos de estadia em cada dia — e ler os valores exatos de volta da Wink.
-
Obtenção de reservas. Consegue recuperar uma reserva real de staging feita contra a sua propriedade de teste, apresentá-la na sua própria interface PMS/CM com o quarto, hóspede e total corretos, e refletir um cancelamento assim que a Wink marcar a reserva como cancelada.
Pré-requisitos
Seção intitulada “Pré-requisitos”Antes de começar a certificação, complete os passos 1–7 de Passos de integração para que tenha:
- Um utilizador Wink em staging com uma conta Afiliado / Channel Manager e uma conta Hotel ligada a esta (Canais → Channel manager). As contas de staging são aprovadas automaticamente, por isso não há nada a solicitar aqui.
- Pelo menos um tipo de quarto e um plano tarifário criados dentro da conta de Hotel. Publique o hotel para que seja reservável em
https://staging-book.wink.travel/hotel/<your-slug>. - Uma aplicação registada sob a sua conta de Afiliado / Channel Manager com um Client ID, Secret Key, e os scopes
integrations.read integrations.write(veja Autenticação). - O
managingEntityIdentifierda sua conta de Afiliado / Channel Manager e opropertyIdentifierda sua conta de Hotel (ambos são UUIDs — veja Encontrar os identificadores das suas contas).
Convenções comuns de pedido
Seção intitulada “Convenções comuns de pedido”Cada pedido nesta secção usa estes cabeçalhos:
Authorization: Bearer <access_token>Wink-Version: 2.0Accept: application/json<access_token>vem do grantclient_credentialscontrahttps://staging-iam.wink.travel/oauth2/token— veja Autenticação.- O cabeçalho
Wink-Versioné obrigatório; omiti-lo não encaminhará para a API JSON v2. Content-Type: application/jsoné adicionado em pedidosPUTque transportam corpo.
Ao longo dos exemplos abaixo, os espaços reservados correspondem aos valores que recolheu em Pré-requisitos:
| Espaço reservado | Significado |
|---|---|
{managingEntityIdentifier} | O ID da sua conta de Afiliado / Channel Manager (UUID) — veja Encontrar os identificadores das suas contas. |
{propertyIdentifier} | O ID da conta de Hotel (propriedade) que ligou à conta CM. |
{masterRateIdentifier} | A tarifa mestre (combinação tipo de quarto × plano tarifário) que irá certificar. |
{bookingIdentifier} | O ID da reserva de staging retornado pela chamada de lista de reservas. |
Passo A — Ping
Seção intitulada “Passo A — Ping”Confirme que as suas credenciais resolvem para a conta de Afiliado / Channel Manager que espera.
curl -s -X GET \ "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/ping" \ -H "Authorization: Bearer <access_token>" \ -H "Wink-Version: 2.0" \ -H "Accept: application/json"Resposta esperada:
{ "apiVersion": "2.0", "name": "Nome da Sua Conta Channel Manager", "status": "PENDING_APPROVAL"}Uma resposta 200 com um name correspondente é o sinal de que a autenticação e resolução da conta estão corretas. O status mostrará PENDING_APPROVAL até a Wink o certificar.
Passo B — Listar propriedades
Seção intitulada “Passo B — Listar propriedades”Recupere a lista paginada de hotéis ligados à sua conta e confirme que a sua propriedade de teste está presente.
curl -s -X GET \ "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/list?page=0&size=25" \ -H "Authorization: Bearer <access_token>" \ -H "Wink-Version: 2.0" \ -H "Accept: application/json"A resposta é uma Page do Spring de entradas ChannelManagerProperty. Localize a entrada cujo identifier corresponde ao seu {propertyIdentifier} e registe o seu currencyCode — irá precisar dele para interpretar as atualizações de tarifa em Passo D.
Passo C — Obter tarifas mestres
Seção intitulada “Passo C — Obter tarifas mestres”Recupere a propriedade juntamente com todas as tarifas mestres (combinação tipo de quarto × plano tarifário) que publica. Escolha aquela contra a qual pretende certificar e registe o seu identifier como o seu {masterRateIdentifier}.
curl -s -X GET \ "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}" \ -H "Authorization: Bearer <access_token>" \ -H "Wink-Version: 2.0" \ -H "Accept: application/json"O envelope da resposta é PropertyWithRoomRateList: um bloco property mais um array rooms de entradas PropertyRoomRate. Cada entrada expõe o tipo de quarto, plano tarifário, limites de ocupação, tarifa base e os modificadores de tarifa que deverá preservar ao enviar tarifas diárias.
Passo D — Carregar a semana de certificação
Seção intitulada “Passo D — Carregar a semana de certificação”Carregue um calendário de tarifas de sete dias cobrindo os primeiros sete dias do mês seguinte ao mês em que inicia a certificação. Por exemplo, se começar a certificação a 21 de agosto, direcione de 1 a 7 de setembro.
Irá enviar sete chamadas PUT separadas — uma por dia — onde startDate == endDate. Cada dia tem uma combinação deliberadamente diferente de valor, quantidade, flags de fechamento na chegada / partida, e limites mínimos/máximos de estadia para que cada campo editável seja exercitado pelo menos uma vez. Os valores estão na moeda da propriedade (registada no Passo B); omita currencyCode e ele será definido corretamente por omissão.
| Dia | Valor | Quantidade | closedOnArrival | closedOnDeparture | minLengthOfStay | maxLengthOfStay | O que prova |
|---|---|---|---|---|---|---|---|
| 1 | 100,00 | 5 | false | false | 1 | 30 | Dia base. |
| 2 | 125,00 | 4 | false | false | 1 | 14 | Alteração de valor + quantidade + maxLengthOfStay. |
| 3 | 150,00 | 3 | true | false | 1 | 30 | Inversão de closedOnArrival. |
| 4 | 175,00 | 2 | false | true | 2 | 7 | Inversão de closedOnDeparture + janela de estadia mais restrita. |
| 5 | 200,00 | 0 | false | false | 1 | 30 | Quantidade esgotada. |
| 6 | 225,00 | 5 | false | false | 3 | 5 | Janela de estadia restritiva. |
| 7 | 250,00 | 1 | false | false | 1 | 30 | Última disponibilidade de quarto. |
O corpo do pedido para o Dia 1 é este. Repita, ajustando startDate / endDate / valores por linha, para os Dias 2 a 7.
curl -s -X PUT \ "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/master-rate/{masterRateIdentifier}" \ -H "Authorization: Bearer <access_token>" \ -H "Wink-Version: 2.0" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "startDate": "2026-09-01", "endDate": "2026-09-01", "amount": 100.00, "master": true, "closedOnArrival": false, "closedOnDeparture": false, "quantity": 5, "minLengthOfStay": 1, "maxLengthOfStay": 30 }'Cada PUT responde com 200 e o array de entradas PropertyRate atualizadas para o intervalo enviado (uma entrada quando startDate == endDate). Guarde essa resposta — fará parte das suas evidências.
Passo E — Ler a semana de certificação
Seção intitulada “Passo E — Ler a semana de certificação”Recupere a semana inteira numa única chamada e confirme que os valores armazenados de cada dia correspondem à linha que enviou no Passo D — incluindo os flags booleanos e a janela de estadia.
curl -s -X GET \ "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/master-rate/{masterRateIdentifier}?startDate=2026-09-01&endDate=2026-09-07" \ -H "Authorization: Bearer <access_token>" \ -H "Wink-Version: 2.0" \ -H "Accept: application/json"A resposta é um PropertyRoomRateWithRateList. O seu array rates deve conter sete entradas, uma por dia, cada uma com os valores amount, quantity, closedOnArrival, closedOnDeparture, minLengthOfStay e maxLengthOfStay que carregou. Qualquer discrepância em algum campo significa que o PUT correspondente no Passo D não foi aplicado como esperado — corrija e verifique novamente antes de avançar.
Passo F — Faça uma reserva de teste
Seção intitulada “Passo F — Faça uma reserva de teste”Abra a seguinte URL num navegador, substituindo <your-slug> pelo slug da conta de Hotel que publicou nos Pré-requisitos:
https://staging-book.wink.travel/hotel/<your-slug>Selecione uma data de chegada e partida que caia inteiramente dentro da sua semana de certificação, escolha a combinação de tipo de quarto + plano tarifário que certificou, e complete a reserva. O staging usa um caminho de pagamento de teste — nenhum cartão real é cobrado.
Quando a página de confirmação aparecer, registe o código da reserva (formato WNKxxxxx) mostrado ao hóspede.
Passo G — Obtenha a reserva
Seção intitulada “Passo G — Obtenha a reserva”Recupere todas as reservas criadas para a sua propriedade de teste dentro de uma janela que abranja o timestamp da reserva.
curl -s -X GET \ "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/booking/list?startDate=2026-09-01T00:00:00&endDate=2026-09-08T00:00:00" \ -H "Authorization: Bearer <access_token>" \ -H "Wink-Version: 2.0" \ -H "Accept: application/json"Encontre a entrada cujo bookingCode corresponde ao código que registou no Passo F. Registe o seu bookingIdentifier. Depois, obtenha essa reserva individual:
curl -s -X GET \ "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/booking/{bookingIdentifier}" \ -H "Authorization: Bearer <access_token>" \ -H "Wink-Version: 2.0" \ -H "Accept: application/json"A resposta é um PropertyBooking. Importe-a para o seu próprio PMS / interface de channel manager e confirme que cada um dos seguintes elementos é apresentado corretamente a um operador:
bookingCode,bookingIdentifier,createdDate- Hóspede:
firstName,lastName,email totalAmount+currencyCode(o valor líquido que o hotel recebe por todos os quartos)paymentMethodType,paymentMethodStatus,salesChannelName- Cada entrada em
roomStays:guestRoomName,ratePlanName,adults,children,startDate,endDatee oamountpor quarto
Faça uma captura de ecrã da reserva como aparece na sua interface — essa captura é uma das evidências necessárias.
Passo H — Cancele a reserva e verifique
Seção intitulada “Passo H — Cancele a reserva e verifique”Peça à equipa Wink para cancelar a reserva de certificação em seu nome (ou cancele você mesmo a partir do Extranet da conta de Hotel se tiver essa permissão). Depois, recupere a mesma reserva com a chamada do Passo G.
Confirme que a resposta agora mostra:
cancelled: true- Um timestamp
cancelDatepreenchido - Um
paymentMethodStatusrefletindo o ciclo de cancelamento (CANCELLED,PARTIALLY_REFUNDEDouFULLY_REFUNDEDdependendo da política de reembolso)
Importe essa reserva atualizada para a sua interface e confirme que o cancelamento é visível para o operador — estado, timestamp de cancelamento e qualquer indicador de reembolso suportado pela sua UI. Faça uma segunda captura de ecrã da reserva cancelada na sua interface. Este é o artefacto final de evidência.
Passo I — Submeta o seu pacote de evidências
Seção intitulada “Passo I — Submeta o seu pacote de evidências”Empacote o seguinte num único arquivo (.zip) chamado wink-cert-<your-channel-manager-name>-<yyyy-mm-dd>.zip:
-
Transcrição da API. Para cada pedido emitido nos Passos A a H, capture o pedido HTTP completo (método, URL, cabeçalhos do pedido com o valor
Authorizationoculto, e o corpo JSON para chamadasPUT) e a resposta HTTP completa (código de estado, cabeçalhos da resposta e corpo JSON). Estruture a transcrição para que cada par pedido/resposta esteja claramente identificado com o passo a que pertence (step-a-ping.json,step-d-day-3-put.json,step-g-list-bookings.json, etc.). Ficheiros.httpem texto simples ou uma exportação.harúnica são formatos aceitáveis. -
Captura de ecrã da UI: reserva ativa. A captura do Passo G mostrando a reserva de certificação apresentada na sua própria interface PMS / channel manager, com hóspede, datas, tipo de quarto, plano tarifário e total claramente legíveis.
-
Captura de ecrã da UI: reserva cancelada. A captura do Passo H mostrando a mesma reserva na sua interface após o cancelamento, com o estado cancelado e timestamp claramente legíveis.
-
Resumo da certificação. Um curto
README.mddentro do arquivo listando:- O nome e versão do seu channel manager / PMS.
- Os identificadores
managingEntityIdentifier,propertyIdentifier,masterRateIdentifierebookingIdentifierusados. - O slug do hotel de staging (o
<your-slug>emhttps://staging-book.wink.travel/hotel/<your-slug>). - O intervalo de datas da semana de certificação (Dia 1 → Dia 7 em ISO-8601).
- O nome e email do engenheiro que realizou a certificação.
Envie o arquivo ao seu contacto de integrações Wink. A Wink irá rever, seguir qualquer discrepância e — se aprovado — alterar o estado da sua conta de Afiliado / Channel Manager de PENDING_APPROVAL para ACTIVE. A sua integração fica então elegível para onboarding em produção.
Notificações via webhook
Seção intitulada “Notificações via webhook”Pode subscrever eventos webhook do channel manager para receber notificações em tempo real:
channel-manager.update.rate— Atualização de tarifa recebida.channel-manager.update.availability— Atualização de disponibilidade recebida.channel-manager.update— Atualização geral do channel manager.
Veja o Catálogo de Eventos Webhook para detalhes.
Leitura adicional
Seção intitulada “Leitura adicional”- Channel Manager API — Documentação completa dos endpoints da API.
- Channel manager — Gestão de fornecedores de tarifas no Extranet.
- Catálogo de Eventos Webhook — Todos os eventos subscritíveis.
- Construir na Wink — Visão geral da plataforma para desenvolvedores.
