Salta ai contenuti

Avvio rapido

Questa guida ti porta da zero a un’integrazione funzionante in circa 30 minuti. Alla fine avrai:

  • prezzi live per hotel in una città, dalla Partner API,
  • un link di prenotazione che accredita le prenotazioni al tuo account,
  • una prenotazione di prova e un webhook che ti informa che è avvenuta.

Tutto avviene in staging, il nostro ambiente di test. Non devi chiedere l’accesso e passare alla produzione in seguito non richiede approvazioni.

Vuoi…Inizia qui
Mostrare hotel nella tua app, sito o prodotto AI e inviare i viaggiatori a prenotare, guadagnando commissioniQuesta guida
Prenotare per conto dei tuoi clienti come agenzia di viaggi autorizzataQuesta guida fino al Passo 5, poi Prenotare come agenzia di viaggi
Incorporare hotel prenotabili senza scrivere un’integrazioneWeb Components
Permettere a un agente AI di cercare e prenotareMCP Servers e Agentic Payments
Collegare un channel manager o PMSAggiungi il tuo Channel Manager

Usi la Partner API per trovare hotel e i loro prezzi live. Ogni hotel ha un urlName stabile. Lo trasformi in un link verso il Wink Booking Engine, book.wink.travel, con i tuoi ID. Il viaggiatore prenota e paga lì, e la prenotazione viene accreditata al tuo account.

Ti serviranno:

  • grpcurl, oppure Postman o Insomnia. La Partner API è gRPC, non REST.
  • curl.

Lo staging è completamente separato dalla produzione, con login e account propri.

  1. Vai su staging-app.wink.travel, clicca su Sign-In / Register e registrati.

  2. Clicca su Accounts nella barra laterale sinistra, poi su Create e scegli I am an Affiliate. Le prenotazioni che invii saranno accreditate a questo account. Vedi Crea Account.

L’applicazione fornisce al tuo codice le credenziali.

  1. Sulla scheda del tuo account, clicca Actions > Manage account, poi la scheda Applications.

  2. Clicca Create new application, dagli un nome e scegli Machine-to-machine come tipo client.

  3. Sotto scopes, seleziona Inventory & rates (lettura). La Partner API verifica inventory.read.

  4. Clicca Create application e copia il Client ID e il Client secret. Il secret viene mostrato una sola volta e non può essere recuperato dopo.

Vedi Applications per gli altri tipi di client e scopes.

Finestra del terminale
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"

Salva il access_token dalla risposta:

Finestra del terminale
export WINK_TOKEN=<access_token>

I token scadono. Nel tuo codice, usa una libreria OAuth2 per recuperarli e rinfrescarli. Vedi Authentication.

Se la richiesta del token viene rifiutata, la risposta è un corpo JSON con un codice error:

errorStato HTTPCausa abituale
invalid_client401Client ID o secret errati, o credenziali di produzione usate su staging-iam
invalid_scope400La richiesta chiede uno scope per cui l’app non è registrata
unauthorized_client400L’app non è autorizzata a usare il grant client_credentials
invalid_request400Manca un parametro obbligatorio, ad esempio se il corpo è JSON invece di un form

Ogni chiamata alla Partner API indica l’account per cui agisci nell’header managing-entity-id. Elenca gli account per cui il tuo token può agire:

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

Copia il accountId dell’account affiliato del Passo 1:

Finestra del terminale
export WINK_ACCOUNT_ID=<accountId>

Lo staging ha hotel di test con disponibilità a Bangkok, quindi questa ricerca usa il suo slug, bangkok-thailand:

Finestra del terminale
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

Usa una data di check-in futura; una data passata viene rifiutata. Ogni risultato contiene:

  • name, starRating e heroImageUrl, sufficienti per mostrare una riga di risultato,
  • roomTypes, le offerte live, stanza più economica per prima,
  • urlName, lo slug necessario per il link di prenotazione.

I prezzi sono interi in unità minori: dividi per 10 elevato alla currencyExponent dalla risposta (2 per USD, quindi 12500 è $125,00).

Non conosci lo slug di una città? Risolvilo con wink.partner.v1.Lookup/Search. Per il contenuto completo di una proprietà, usa il servizio Content. La documentazione della Partner API descrive ogni chiamata.

https://staging-book.wink.travel/hotel/<urlName>?client-id=<YOUR_CLIENT_ID>&configuration-id=<YOUR_CUSTOMIZATION_ID>
  • <urlName> è il urlName dell’hotel dal Passo 5.
  • client-id è il Client ID della tua applicazione dal Passo 2.
  • configuration-id è il tuo ID di personalizzazione: Manage account > Customizations. Una personalizzazione imposta anche il branding, la lingua e la valuta predefiniti sulla pagina di prenotazione.

Aggiungi date, ospiti, lingua e valuta del viaggiatore allo stesso link così la pagina dell’hotel si apre con questi dati compilati:

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
ParametroSignificatoEsempio
sdData check-insd=2027-03-14
n o edNumero di notti, o data check-outn=2 o ed=2027-03-16
rcOspiti per stanzarc=a2 (2 adulti)
lLingua di visualizzazionel=en
cValuta di visualizzazionec=USD
pCodice promozionalep=ABC123

Questi parametri sovrascrivono i valori predefiniti impostati nella tua personalizzazione. La guida al pulsante Prenota Ora spiega il formato completo di rc, inclusi bambini e più stanze.

Il link apre la pagina dell’hotel; non può pre-selezionare una stanza o una tariffa. Il viaggiatore sceglie la stanza sulla pagina dell’hotel, al prezzo live.

Vedi Collegamento diretto per collegarti alla home page del booking engine invece che a un singolo hotel.

Apri il tuo link, scegli date e stanza, e paga con una carta di test Stripe, ad esempio 4242 4242 4242 4242 con qualsiasi data di scadenza futura e qualsiasi CVC. Nessuna carta reale viene addebitata in staging. Prendi nota del codice prenotazione sulla pagina di conferma; inizia con WNK.

  1. Nel Portal, vai su Applications > Webhooks e aggiungi un endpoint che accetti richieste POST.

  2. Iscriviti a booking.create, oppure lascia vuota la lista eventi per ricevere tutto durante lo sviluppo.

  3. Inviati un evento di prova, poi fai un’altra prenotazione di prova e verifica che arrivi.

Verifica la firma di ogni consegna prima di fidarti. Vedi Integrazione Webhook e il Catalogo Eventi Webhook.

Non c’è un passaggio di approvazione per gli sviluppatori. (Gli account agenzia di viaggi sono certificati prima; vedi qui sotto.) Quando la tua integrazione funziona in staging:

  1. Crea un account e un’applicazione su app.wink.travel, come nei Passi 1 e 2. Le credenziali non si trasferiscono tra ambienti.

  2. Rimuovi staging- da ogni host:

    StagingProduzione
    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. Cerca di nuovo il tuo ID account di produzione (Passo 4) e l’ID di personalizzazione (Passo 6). Sono diversi da quelli di staging.

L’uso della Partner API è misurato in notti-hotel, con una quota mensile gratuita. Vedi Partner API per prezzi e limiti.

Se il tuo account è un’agenzia di viaggi autorizzata, non devi inviare i viaggiatori a book.wink.travel: puoi creare prenotazioni direttamente con wink.partner.v1.Booking/CreateBooking e gestirle con le altre chiamate Booking. Gli altri account inviano i viaggiatori al link di prenotazione.

Gli account agenzia sono certificati: Wink verifica ogni registrazione prima che possa prenotare. Le agenzie che vogliono incassare direttamente dai clienti, come merchant of record, devono prenotare tramite la Partner API e ottenere l’approvazione scritta di Wink. Vedi Iniziare come agenzia di viaggi e la documentazione Partner API.