Fjord- og Havhuse

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.

  1. 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.
  2. 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»).
  3. Gæsten booker hos jer, på jeres vilkår. Jeres system gemmer klik-ID’et sammen med bookingen, hvis det kan.
  4. Jeres system melder tilbage. Et kald til os med klik-ID’et og en status: booked eller cancelled (se «Meld en booking tilbage»).
  5. 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.

Eksempel med opdigtede data
https://www.example.com/sommerhus/1804
?utm_source=fjordoghavhuse
&utm_medium=referral
&utm_campaign=thy
&utm_content=FK-7K2M9QXA
&fh_click=FK-7K2M9QXA
utm_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.

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.

Skabelon (eksempel med opdigtede feltnavne)
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:

Linket gæsten får (eksempel)
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-7K2M9QXA

Kom i gang

  1. I siger ja til, at vi sender gæster til jeres huse med linket. Det er hele aftalen om standardlinket.
  2. Valgfrit: I giver os feltnavnene til et deeplink, så gæsten lander i bookingen med det udfyldt.
  3. 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.
  4. I gemmer klik-ID’et sammen med bookingen. Det står i utm_content og fh_click på jeres bookingside. Hvor det ender i jeres system, ved I bedre end os.
  5. 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

POSTmetode
https://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

Indhold (eksempel med opdigtede data)
{
  "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
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"}'
Node.js
// 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
<?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":"…"}}.

Svar, 200
{
  "ok": true,
  "clickId": "FK-7K2M9QXA",
  "status": "booked",
  "rent": 8950,
  "arrival": "2027-07-03",
  "departure": "2027-07-10",
  "reference": "BS-48213"
}

Svarkoder og fejl

StatusKodeBetyder
200okModtaget. 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.
400invalid_json / invalid_bodyIndholdet 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.
422stay_invalidFormen er rigtig, men opholdet kan ikke bruges: afrejsen ligger ikke efter ankomsten.
401unauthorizedAPI-nøglen mangler eller er forkert.
404not_foundKlik-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 / 415payload_too_large / unsupported_media_typeIndholdet er over 8 kB (kilobyte), eller det er ikke sendt som application/json.
429rate_limitedFor 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
curl https://fjordoghavhuse.dk/api/partner/v1/clicks/FK-7K2M9QXA \
  -H "Authorization: Bearer fh_live_..."
Svar, 200 (eksempel med opdigtede data)
{
  "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_content eller fh_click) står i en kolonne. Vi sætter klik-ID’erne i filen sammen med vores klik.
Klik-ID og tilbagemelding via API | Fjord- og Havhuse