Teknisk vejledning for udlejningsbureauer
Klik-ID og tilbagemelding via API
Hver gæst, vi sender til jer, har et klik-ID i linket. Her står, hvordan linket ser ud, og hvordan jeres system kan melde tilbage, når klikket blev til en booking. Det er valgfrit: uden API melder I tilbage med en opgørelse eller en CSV-fil.
- Det får I: hvert klik fra os har et klik-ID. Med API melder jeres system selv tilbage, når klikket blev til en booking, i stedet for en opgørelse en gang om måneden. API betyder, at to computersystemer taler sammen uden et menneske imellem.
- Det skal I gøre: gemme klik-ID’et sammen med bookingen og få en udvikler til at sende et kald til os, når bookingen er lavet. Vi giver jer en API-nøgle. Et link med datoer og gæster udfyldt er valgfrit.
- Det ændrer ikke noget for jer: kontrakt, kunde og betaling er jeres. Der er ingen betaling gennem os.
Sådan virker det
Hver gang en gæst trykker «Book nu» på et af jeres huse, sender vi gæsten videre til jer med et klik-ID i linket. Klik-ID’et er kvitteringen: det binder en booking hos jer til et klik hos os.
- Gæsten trykker «Book nu» hos os. Vi gemmer klikket: hvilket hus, hvilket ophold gæsten har valgt, hvor på vores side gæsten klikkede, og hvornår. Klikket gemmes uden cookies og uden IP-adresse.
- Vi sender gæsten til jer. Linket går til jeres egen side og har fem mærker på, hvoraf to bærer klik-ID’et (se «Linket til jeres side»).
- Gæsten booker hos jer, på jeres vilkår. Jeres system gemmer klik-ID’et sammen med bookingen, hvis det kan.
- Jeres system melder tilbage. Et kald til os med klik-ID’et og en status:
bookedellercancelled(se «Meld en booking tilbage»). - Vi afregner efter opholdet, for gennemførte ophold, ud fra det, I har meldt tilbage.
Det er valgfrit at bruge API. Uden det melder I tilbage på en af to andre måder (se «Uden API»). Vi kan ikke se jeres bookinger, så jeres tilbagemelding er grundlaget, uanset hvordan I giver den.
Linket til jeres side
Standard: husets side med mærker
Vi sender gæsten til husets side hos jer, på den adresse vi allerede har, og lægger fem mærker på linket. Står der allerede utm_-mærker i linket, erstatter vi dem, så et link aldrig har to kilder. Det er de almindelige UTM-mærker, som webstatistik læser. Klik-ID’et står i utm_content, så jeres statistik kan vise det.
https://www.example.com/sommerhus/1804
?utm_source=fjordoghavhuse
&utm_medium=referral
&utm_campaign=thy
&utm_content=FK-7K2M9QXA
&fh_click=FK-7K2M9QXAutm_sourcefjordoghavhuse- Hvor gæsten kom fra: os.
utm_mediumreferral- Typen af besøg: en henvisning fra en anden side.
utm_campaignthy- Området, gæsten kiggede på, for eksempel thy. Er gæsten ikke inde på et område, står der sommerhus.
utm_contentFK-7K2M9QXA- Klik-ID'et: et nummer, der kun hører til dette ene klik.
fh_clickFK-7K2M9QXA- Det samme klik-ID en gang til, til bookingsystemer, der kun gemmer ét af de to felter.
Klik-ID’et er «FK-» efterfulgt af otte tegn: cifrene 2 til 9 og de store bogstaver undtagen I, L og O, som kan forveksles med tal. Eksempel: FK-7K2M9QXA.
Valgfrit: deeplink
Vil I have gæsten helt ind i bookingen med hus, datoer og gæster udfyldt, giver I os adressen på jeres bookingside og navnene på de felter, siden læser. Vi skriver dem som en skabelon, hvor klik-ID’et står som {ref}. Et deeplink er et link, der går direkte ind i jeres kasse med det udfyldt.
https://www.example.com/booking
?hus={externalId}
&fra={arrival}
&til={departure}
&voksne={adults}
&boern={children}
&dyr={pets}
&ref={ref}{url}- Husets adresse hos jer, som vi allerede har.
{externalId}- Husets nummer hos jer.
{arrival}- Ankomstdato. Som standard ÅÅÅÅ-MM-DD; skriv for eksempel {arrival:DD-MM-YYYY} for et andet format.
{departure}- Afrejsedato, samme formater som ankomst.
{nights}- Antal nætter.
{adults}- Antal voksne.
{children}- Antal børn.
{persons}- Voksne og børn lagt sammen.
{pets}- Antal husdyr.
{ref}- Klik-ID'et.
Er en oplysning ikke valgt endnu, for eksempel datoerne, udelader vi hele feltet fra linket, så der aldrig står en tom pladsholder. Linket får de samme fem mærker som standardlinket. Skabelonen ovenfor giver:
https://www.example.com/booking
?hus=1804
&fra=2027-07-03
&til=2027-07-10
&voksne=4
&boern=0
&dyr=0
&ref=FK-7K2M9QXA
&utm_source=fjordoghavhuse
&utm_medium=referral
&utm_campaign=thy
&utm_content=FK-7K2M9QXA
&fh_click=FK-7K2M9QXAKom i gang
- I siger ja til, at vi sender gæster til jeres huse med linket. Det er hele aftalen om standardlinket.
- Valgfrit: I giver os feltnavnene til et deeplink, så gæsten lander i bookingen med det udfyldt.
- I får en API-nøgle, hvis I vil melde tilbage via API. Nøglen fungerer som en adgangskode til vores side: I sender den i headeren
Authorization: Bearer. Den vises én gang, når vi laver den. Mister I den, laver vi en ny, og den gamle holder op med at virke. - I gemmer klik-ID’et sammen med bookingen. Det står i
utm_contentogfh_clickpå jeres bookingside. Hvor det ender i jeres system, ved I bedre end os. - I kalder os, når en booking er lavet, og igen, hvis den bliver aflyst.
Meld en booking tilbage
Har en gæst, der kom fra os, booket hos jer, sender jeres system et POST-kald (internettets ord for at sende noget af sted) til vores adresse med klik-ID’et i enden. Beskeden er tekst i JSON-format, et fast tekstformat, som næsten alle programmeringssprog kan læse.
Kaldet
POSTmetodehttps://fjordoghavhuse.dk/api/partner/v1/clicks/<klik-ID>. Adressen er en HTTPS-adresse, en almindelig, krypteret internetadresse.AuthorizationAuthorization: Bearer fh_live_...- Jeres API-nøgle. Uden den, eller med en forkert, svarer vi 401.
Content-Typeapplication/json- Fortæller, at indholdet er JSON, skrevet i UTF-8, så æ, ø og å kommer rigtigt igennem.
Indholdet
{
"status": "booked",
"rent": 8950,
"arrival": "2027-07-03",
"departure": "2027-07-10",
"reference": "BS-48213"
}Felterne i indholdet
statusskal med- booked når klikket blev til en booking, cancelled hvis bookingen blev aflyst. Aflyste bookinger tæller ikke med.
rentskal med ved booked- Lejen for opholdet i hele kroner, før rengøring og tillæg og uden moms. Et tal, ikke tekst: 8950, ikke «8.950 kr.».
arrivalskal med ved booked- Ankomst, som bookingen blev lavet med, som ÅÅÅÅ-MM-DD. Den kan være en anden end den, gæsten valgte hos os.
departureskal med ved booked- Afrejse, samme format. Gebyret gælder først, når afrejsedagen er passeret.
referencevalgfri- Jeres eget bookingnummer. Vi gemmer det, så I kan finde bookingen igen i opgørelsen.
Blev bookingen aflyst, efter I har meldt den, sender I {"status":"cancelled"} med samme klik-ID. Vi afregner kun for gennemførte ophold, så en aflyst booking tæller ikke med. I kan kun melde på klik-ID’er, der hører til jeres egne huse.
Eksempler
curl -X POST https://fjordoghavhuse.dk/api/partner/v1/clicks/FK-7K2M9QXA \
-H "Authorization: Bearer fh_live_..." \
-H "Content-Type: application/json" \
-d '{"status":"booked","rent":8950,"arrival":"2027-07-03","departure":"2027-07-10","reference":"BS-48213"}'// Når bookingen er oprettet i jeres system, og klik-ID'et står på den.
// loadApiKey() henter nøglen dér, hvor I opbevarer jeres nøgler.
async function reportBooking(clickId, booking) {
const res = await fetch("https://fjordoghavhuse.dk/api/partner/v1/clicks/" + clickId, {
method: "POST",
headers: { Authorization: "Bearer " + loadApiKey(), "Content-Type": "application/json" },
body: JSON.stringify({ status: "booked", rent: booking.rentKr, arrival: booking.arrival, departure: booking.departure, reference: booking.number }),
});
if (!res.ok) throw new Error("Fjord- og Havhuse svarede " + res.status + ": " + (await res.text()));
}<?php
$clickId = 'FK-7K2M9QXA'; // fra utm_content eller fh_click på bookingen
$body = json_encode(['status' => 'booked', 'rent' => 8950, 'arrival' => '2027-07-03', 'departure' => '2027-07-10', 'reference' => 'BS-48213']);
$ch = curl_init('https://fjordoghavhuse.dk/api/partner/v1/clicks/' . $clickId);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('FJORDHUSE_API_KEY'), 'Content-Type: application/json'],
CURLOPT_RETURNTRANSFER => true,
]);
$answer = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);curl er et program til at sende kald fra kommandolinjen. I Node.js-eksemplet henter loadApiKey() nøglen dér, hvor I opbevarer jeres nøgler, og i PHP-eksemplet står den i en miljøvariabel. Læg den ikke i selve koden.
Svaret
Vi svarer altid i JSON. Gik det godt, ser svaret sådan ud. En fejl ser ud som {"ok":false,"error":{"code":"…","message":"…"}}.
{
"ok": true,
"clickId": "FK-7K2M9QXA",
"status": "booked",
"rent": 8950,
"arrival": "2027-07-03",
"departure": "2027-07-10",
"reference": "BS-48213"
}Svarkoder og fejl
| Status | Kode | Betyder |
|---|---|---|
| 200 | ok | Modtaget. Sender I den samme melding igen, er svaret også 200 med "unchanged": true, og intet ændres. Sender I en anden melding, for eksempel cancelled efter booked eller en ny leje, gælder den nye, og svaret har "updated": true. |
| 400 | invalid_json / invalid_body | Indholdet er ikke JSON eller har ikke den form, der står ovenfor, for eksempel booked uden rent. Svaret nævner det felt, der er galt. |
| 422 | stay_invalid | Formen er rigtig, men opholdet kan ikke bruges: afrejsen ligger ikke efter ankomsten. |
| 401 | unauthorized | API-nøglen mangler eller er forkert. |
| 404 | not_found | Klik-ID'et findes ikke hos jer. Vi skelner ikke mellem et ID, der ikke findes, og et, der hører til en anden udlejers hus. |
| 413 / 415 | payload_too_large / unsupported_media_type | Indholdet er over 8 kB (kilobyte), eller det er ikke sendt som application/json. |
| 429 | rate_limited | For mange kald. Der er plads til 120 kald i minuttet pr. udlejer. Svaret har headeren Retry-After, som fortæller, hvornår I kan prøve igen. |
Tjek et klik-ID
Vil I vide, om et klik-ID er ægte og hører til et af jeres huse, før I melder tilbage, kan I hente det med et GET-kald (internettets ord for at hente noget). Det er samme adresse og samme nøgle.
curl https://fjordoghavhuse.dk/api/partner/v1/clicks/FK-7K2M9QXA \
-H "Authorization: Bearer fh_live_..."{
"ok": true,
"click": {
"clickId": "FK-7K2M9QXA",
"clickedAt": "2027-05-03T10:14:22.000Z",
"house": {
"slug": "eksempelhuset-ved-fjorden",
"name": "Eksempelhuset ved fjorden",
"externalId": "1804"
},
"stay": {
"arrival": "2027-07-03",
"departure": "2027-07-10",
"adults": 4,
"children": 0,
"pets": 0
},
"booking": {
"status": "booked",
"rent": 8950,
"arrival": "2027-07-03",
"departure": "2027-07-10",
"reference": "BS-48213",
"reportedAt": "2027-05-04T08:02:10.000Z"
}
}
}Svaret viser huset, det ophold gæsten havde valgt, og hvad vi har registreret indtil nu: clicked (intet meldt endnu), booked eller cancelled. Der står ingen oplysninger om gæsten, for dem gemmer vi ikke. Er klik-ID’et ukendt, eller hører det til en anden udlejer, er svaret 404.
Uden API: opgørelse og CSV
Vil I ikke bygge noget, melder I tilbage på en af to andre måder. De bruger de samme klik-ID’er.
- En månedlig opgørelse. Hver måned får I et link uden login til en liste over månedens klik på jeres huse. I sætter kryds ved «Blev booket» og skriver lejen.
- Jeres bookingeksport som CSV. I sender en fil med jeres bookinger, hvor klik-ID’et (
utm_contentellerfh_click) står i en kolonne. Vi sætter klik-ID’erne i filen sammen med vores klik.