Apps - Login handshake

En applikation der har følgende vigtige værdier, som I får i forbindelse med, at I får en App oprettet i BookingStudio:

• ApplicationId
• SharedKey
• ApplicationStartUrl - valgt af jer

Disse værdi skal vi bruge i vores kommunikation og login-handshake.
Når I har fået disse af BookingStudio, så kan I gå igang med at lave integrationen.

BookingStudio starter med at kalde Applikationens StartUrl med følgende mønster:

ApplicationStartUrl?login_url={LOGIN_URL}&domain={DOMAIN}&hash={HASH}

• LOGIN_URL: Den url som applikationen skal kalde for at logge brugeren ind
• DOMAIN: Det domæne som kalder applikationen - bruges til evt. at skeldne imellem forskellige BookingStudio installationer
• HASH: En værdi som skal bruges til at sikre at kaldet kommer fra BookingStudio

Når jeres applikation modtager dette kald, så skal I sikre at kaldet kommer fra os. Dette gør I ved at validere op i mod vores hash parameter:

function validate(login_url, domain, hash) { return hash == md5(login_url + domain + SharedKey) }

Derefter skal I sende brugeren til login_url’en. Dette gør I ved bygge en URL, hvor I tilføjer følgende querystring-parametre til login_url:

• application_id = Din ApplicationId som du har fået af BookingStudio
• redirect_url = hvor du gerne vil have at BookingStudio sender brugeren hen
• state (optional) = en værdi I kan sende med, som vi vil sende tilbage
• version = 2

Derefter vil brugeren blive bedt om at logge ind, eller hvis brugeren allerede er logget ind, vil de blive sendt tilbage til jeres return_url.

Jeres return url vil få følgende querystring-parametre parametre:

• code - En kode som I kan bruge til at få en API-Nøgle så I kan snakke med vores API i kontekst af brugeren.
• state - jeres state
• user_id - Brugerens global id i vores system
• api_url - Hvilken URL som API’en ligger på
• client_id - BookingStudio løsningens globale ID, som I evt. kan bruge til at segmentere data på.
• hash - en hash som skal valideres for at sikre at svaret kommer fra os

Jeres hash skal valideres på følgende måde:

function validate(code, state, user_id, api_url, client_id, hash) { return hash == md5(code + state + user_id + api_url + client_id + SharedKey) }

Derefter kan I regitere i jeres system at brugeren er logget ind.

Kommunikation med API’en

Efter at brugeren er logget ind, så vil I sikkert gerne snakke med API’et for at få flere informationer om BookingStudio systemet. Da brugeren loggede ind fik i jeres code parameter en såkaldt token, som kan bruges til at få en API-nøgle.

Dette gøres ved at lave et GET kald til API’et på følgende måde:

API_URL/v1/accesstoken.xml?client_id={CLIENT_ID}&client_secret={SharedKey}&code={CODE}

Dette vil give jer et svar i XML i følgende format:

<ApiToken token="API-Nøgle" expires="ANTAL-SEKUNDER-FØR-EXPIRE"> <UserInformation Id="BrugerID" Username="Brugernavn" /> </ApiToken>

Du kan nu bruger API-nøglen som står i Token til at snakke med API’et i følge vores dokumentation. Når API-nøglen udløber skal brugeren forbi vores side for at få en ny API-nøgle - eller I skal alternativt have en fast API nøgle af BookingStudio.
Bemærk at nøglen kun har de rettigheder, som er aftalt med BookingStudio.