Autenticação

Uma aplicação fornece-lhe um Client ID e uma Secret Key que precisa para criar uma sessão OAuth2 autenticada que pode usar para comunicar com as APIs da Wink e TripPay.

Aqui estão os passos para criar uma sessão autenticada.

Passo 1. Obtenha um token de acesso no ambiente de staging ou no nosso ambiente de produção:

Provavelmente, estará a trabalhar com uma biblioteca OAuth2 robusta para a sua linguagem, que fará todo o trabalho pesado por si. Os nossos exemplos mostrarão o uso mais básico a partir da linha de comandos usando curl.

Staging

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_SECRET_KEY>"

Produção

curl -X POST https://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_SECRET_KEY>"

Isto irá devolver um token de acesso, juntamente com outros dados da resposta OAuth2:

{
  "access_token": "abc123"
}

Quando fizer uma chamada a qualquer um dos nossos endpoints, inclua o seguinte no cabeçalho:

Wink-Version = 2.0 Última - Consulte a nossa documentação API para outras versões disponíveis.
Authorization = Bearer ${access_token} Insira o seu token de acesso.

Scopes

Um scope é uma permissão que o seu token de acesso transporta. Quando solicita um token, passa uma lista de scopes delimitada por espaços no parâmetro scope, e o token só pode aceder às áreas que esses scopes abrangem. Com o grant client_credentials define os scopes no seu pedido de token — veja os exemplos curl acima e o tutorial Postman.

Os scopes são nomeados section.action, onde a ação é uma das seguintes:

read — visualizar recursos (requisições seguras GET)
write — criar e atualizar recursos (POST / PUT / PATCH)
remove — eliminar recursos (DELETE)

A Wink agrupa permissões por área funcional. Solicite apenas os scopes que a sua integração necessita:

Grupo de scopes	Scopes	O que desbloqueiam	Risco
Account	`account.read` `account.write` `account.remove`	Gestão de entidades, membros da equipa, definições, aplicações	Baixo–Médio
Inventory	`inventory.read` `inventory.write` `inventory.remove`	Propriedades, tipos de quartos, planos de tarifas, tarifas, extras, disponibilidade, atividades, atrações	Baixo–Médio
Booking	`booking.read` `booking.write` `booking.remove`	Pesquisa, visualização, criação, cancelamento e reembolso de reservas; checkout; políticas de cancelamento	Baixo–Médio
Marketing	`marketing.read` `marketing.write` `marketing.remove`	Campanhas, benefícios, canais de venda, WinkLinks, social gerido, fidelização	Baixo–Médio
Content	`content.read` `content.write` `content.remove`	Descrições de propriedades, avaliações, media, mapas, índice verde	Baixo–Médio
Analytics	`analytics.read` `analytics.write` `analytics.remove`	Relatórios e análises — receitas, rankings	Baixo–Médio
Integrations	`integrations.read` `integrations.write` `integrations.remove`	Gestores de canais, sistemas externos de reservas, Google Hotel, endpoints de notificação, sincronização de reservas	Baixo–Médio
Payment	`payment.read` `payment.write` `payment.remove`	Processamento de pagamentos, Stripe, Revolut, pagamentos, subscrições	Médio–Alto
Accounting	`accounting.read` `accounting.write` `accounting.remove`	Contabilidade, livro de retiradas, reconciliação	Médio–Alto
MCP	`mcp.read` `mcp.write` `mcp.remove`	Abre o transporte MCP (`/mcp`) para agentes de IA	Baixo–Médio

Algumas coisas a ter em conta:

Solicite o mínimo. Peça apenas os scopes que a sua integração realmente usa — um token emitido com acesso mais amplo do que o necessário tem um raio de impacto maior se for comprometido.
Scopes desconhecidos são rejeitados. Solicitar um scope para o qual a sua aplicação não está registada, ou que não existe, falha na emissão do token.
mcp.* é apenas para clientes agentes de IA. Precisa dele para abrir o transporte MCP; não é necessário para chamadas REST API regulares. Veja Model Context Protocol.