{ "openapi": "3.1.0", "info": { "title": "La Truite d'Argent Booking API", "version": "1.0.0", "description": "Publieke REST API voor AI agents om beschikbaarheid, prijzen en\nboekingslinks van La Truite d'Argent op te vragen. Adults-only\nmini-resort in de Belgische Ardennen met 7 accommodatietypes,\neen weekend-restaurant en camperplaatsen.\n\n**Gebruik:** de lees-endpoints (`/info`, `/accommodaties`,\n`/beschikbaarheid`, `/restaurant`, `/camper-beschikbaarheid`) zijn\npubliek toegankelijk zonder API-sleutel, met een rate-limit van 60\nrequests per uur per IP. `POST /quote` vereist wél een `X-API-Key`\nheader (recht `lezen`), aan te vragen via `contact@la-truite.com`.\n\n**Boekingen:** de API is alleen-lezen. Boekingen gebeuren via de\n`booking_url` die in iedere response wordt meegestuurd — deze wijst\ndirect naar de online boekingsengine op la-truite.com en opent het\nboekingspaneel met datum, type en personenaantal al ingevuld.\n\n**AI-attributie:** elke `booking_url` bevat UTM-parameters\n(`utm_source=api&utm_medium=ai`) zodat conversies vanuit AI-agents\nin onze analytics zichtbaar zijn.\n\n**Bij een 429-statuscode:** de rate-limit is bereikt. Vertel de gebruiker\ndat het systeem even druk is, wacht het aantal seconden uit de\n`X-RateLimit-Reset` header en probeer het daarna opnieuw — niet sneller.\n", "contact": { "name": "La Truite d'Argent", "email": "contact@la-truite.com", "url": "https://www.la-truite.com" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://www.la-truite.com/api/v1", "description": "Productie" } ], "security": [], "tags": [ { "name": "Informatie", "description": "Statische resort- en accommodatie-informatie (locatie, concept, types, kenmerken)." }, { "name": "Beschikbaarheid", "description": "Live beschikbaarheid, prijzen en restricties per periode. Begin een boekingsflow hier." }, { "name": "Boeken", "description": "Prijsofferte + directe boekingslink (deeplink naar la-truite.com met UTM-tags). Read-only — boeking voltooit de gast zelf op de site." } ], "paths": { "/info": { "get": { "tags": [ "Informatie" ], "operationId": "getResortInfo", "summary": "Algemene resort-informatie", "description": "Publiek endpoint (geen API-sleutel vereist). Geeft locatie, concept, contact en pointers naar andere endpoints.", "security": [], "parameters": [ { "$ref": "#/components/parameters/LangParam" } ], "responses": { "200": { "description": "Resort info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InfoResponse" } } } } } } }, "/accommodaties": { "get": { "tags": [ "Informatie" ], "operationId": "getAccommodations", "summary": "Lijst van accommodatietypes", "description": "Retourneert alle actieve accommodatietypes met prijs-vanaf, kenmerken en directe boekingslinks.", "parameters": [ { "$ref": "#/components/parameters/LangParam" }, { "name": "slug", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter op specifiek type (bv. `lodge`, `cabane`, `vallei`)." } ], "responses": { "200": { "description": "Lijst accommodaties", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccommodatiesResponse" } } } }, "404": { "description": "Onbekende slug", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/beschikbaarheid": { "get": { "tags": [ "Beschikbaarheid" ], "operationId": "getAvailability", "summary": "Beschikbaarheid en prijzen voor een periode", "description": "Controleer beschikbaarheid voor een verblijfsperiode. Retourneert\nalle beschikbare accommodaties met prijs (inclusief eventuele\nkortingen) en directe booking_url.\n\nRetourneert óók de NIET-beschikbare accommodaties in `niet_beschikbaar`,\nelk met een `restriction_reason` (bijv. \"minimum verblijf niet behaald\"\nof \"volgeboekt\"). **Communiceer die reden altijd aan de gebruiker** —\nzo weet die wat aan te passen (andere datum, langer verblijf).\n\n**Belangrijk voor 1-nacht boekingen:** alleen Vallei Suite,\nDroom Suite en Wellness Suite zijn 1 nacht boekbaar op vr/za/zo,\nals Stay + Dine arrangement (3-gangen diner en ontbijt inbegrepen).\n", "parameters": [ { "name": "aankomst", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "example": "2026-07-15" }, { "name": "vertrek", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "example": "2026-07-18" }, { "name": "personen", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 6, "default": 2 } }, { "$ref": "#/components/parameters/LangParam" } ], "responses": { "200": { "description": "Beschikbaarheid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeschikbaarheidResponse" } } } }, "400": { "description": "Ongeldige parameters (bv. datum in verleden, verkeerd formaat)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/restaurant": { "get": { "tags": [ "Beschikbaarheid" ], "operationId": "getRestaurantAvailability", "summary": "Restaurant-beschikbaarheid (weekend-diner)", "description": "Retourneert beschikbare datums voor diner bij The Kingdom of Dreams.\nRestaurant is open op vr/za/zo om 19:00. Voorschot €45 p.p. via Mollie.\n", "parameters": [ { "name": "datum", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Check één specifieke datum. Alternatief voor `van`/`tot`." }, { "name": "van", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Startdatum range (default= morgen)." }, { "name": "tot", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Einddatum range (default= +14 dagen)." }, { "$ref": "#/components/parameters/LangParam" } ], "responses": { "200": { "description": "Restaurant beschikbaarheid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestaurantResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/camper-beschikbaarheid": { "get": { "tags": [ "Beschikbaarheid" ], "operationId": "getCamperAvailability", "summary": "Camp & Dinner beschikbaarheid voor een periode", "description": "Controleer beschikbaarheid van een camperplaats (Camp & Dinner) voor een\nperiode. Retourneert vrije plaatsen, verblijfprijs, de verplichte\ndineravonden (vr/za/zo) met vrije tafels, ontbijtdagen en een directe\nbooking_url.\n\n**Diner is verplicht** bij Camp & Dinner: er moet minstens één vrije\ndineravond in de periode vallen, anders is de periode niet boekbaar.\n\nBij `beschikbaar: false` staat de reden in `restriction_reason`.\n**Communiceer die reden altijd aan de gebruiker.**\n", "parameters": [ { "name": "aankomst", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "example": "2026-07-17" }, { "name": "vertrek", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "example": "2026-07-19" }, { "$ref": "#/components/parameters/LangParam" } ], "responses": { "200": { "description": "Camperbeschikbaarheid (ook bij beschikbaar=false met restriction_reason)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CamperResponse" } } } }, "400": { "description": "Ongeldige parameters (bv. datum in verleden, verkeerd formaat)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/quote": { "post": { "tags": [ "Boeken" ], "operationId": "calculateQuote", "summary": "Prijsofferte + boekingslink voor één type", "description": "Genereert een prijsofferte en directe boekingslink voor één\naccommodatietype (of `camper`). Stateless: er wordt niets opgeslagen.\nDe `booking_url` is een deeplink naar de boekingsengine die bij openen\nzelf live de beschikbaarheid hercheckt.\n\n**Authenticatie vereist** (`X-API-Key`, recht `lezen`) — deze endpoint\ngenereert links en is daarom beschermd tegen scraping.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" } } } }, "responses": { "200": { "description": "Offerte (ook bij beschikbaar=false met restriction_reason)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } }, "400": { "description": "Ongeldige of ontbrekende parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Onbekend accommodatietype", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "parameters": { "LangParam": { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "nl", "en", "fr", "de" ], "default": "nl" } } }, "responses": { "Unauthorized": { "description": "Ongeldige of ontbrekende API-sleutel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Rate limit bereikt. Vertel de gebruiker dat het systeem druk is en wacht het aantal seconden uit de X-RateLimit-Reset header voordat je het opnieuw probeert.\n", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Seconden tot reset" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "Meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time" }, "lang": { "type": "string" } } }, "ErrorResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "MISSING_API_KEY" }, "message": { "type": "string" }, "hint": { "type": "string", "description": "Actiegerichte suggestie voor de gebruiker." } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "Accommodatie": { "type": "object", "properties": { "slug": { "type": "string", "example": "lodge" }, "naam": { "type": "string", "example": "The Lodge" }, "beschrijving": { "type": "string" }, "min_personen": { "type": "integer" }, "max_personen": { "type": "integer" }, "aantal_eenheden": { "type": "integer" }, "waarborg_euro": { "type": "number" }, "prijs_vanaf_euro": { "type": "number", "nullable": true }, "foto_url": { "type": "string", "nullable": true }, "foto_urls": { "type": "array", "items": { "type": "string" } }, "kenmerken": { "type": "array", "items": { "type": "string" } }, "pakket_1nacht": { "type": "object", "nullable": true, "properties": { "beschikbaar": { "type": "boolean" }, "beschrijving": { "type": "string" }, "diner_prijs_pp": { "type": "number" }, "ontbijt_inbegrepen": { "type": "boolean" } } }, "booking_url": { "type": "string", "format": "uri" }, "info_url": { "type": "string", "format": "uri" } } }, "AccommodatiesResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "accommodaties": { "type": "array", "items": { "$ref": "#/components/schemas/Accommodatie" } }, "aantal": { "type": "integer" }, "resort": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "BeschikbaarAccommodatie": { "type": "object", "properties": { "slug": { "type": "string" }, "naam": { "type": "string", "description": "Kan vervangen zijn door bezettingskorting-label (bv. \"Lodge voor 2 personen\")." }, "naam_origineel": { "type": "string" }, "beschikbaar": { "type": "boolean", "example": true }, "vrije_eenheden": { "type": "integer" }, "max_personen": { "type": "integer" }, "prijs": { "type": "object", "properties": { "per_nacht_euro": { "type": "number" }, "totaal_bruto_euro": { "type": "number" }, "totaal_na_korting_euro": { "type": "number" }, "waarborg_euro": { "type": "number" }, "totaal_te_betalen_euro": { "type": "number" } } }, "kortingen": { "type": "object", "properties": { "verblijfskorting": { "type": "object", "nullable": true }, "bezettingskorting": { "type": "object", "nullable": true } } }, "pakket_1nacht": { "type": "object", "nullable": true }, "foto_url": { "type": "string", "nullable": true }, "kenmerken": { "type": "array", "items": { "type": "string" } }, "booking_url": { "type": "string", "format": "uri", "description": "Directe link naar IBE met vooringevulde datum." }, "info_url": { "type": "string", "format": "uri" } } }, "OnbeschikbareAccommodatie": { "type": "object", "properties": { "slug": { "type": "string" }, "naam": { "type": "string" }, "beschikbaar": { "type": "boolean", "example": false }, "max_personen": { "type": "integer" }, "restriction_reason": { "type": "string", "description": "Menselijk leesbare reden waarom niet beschikbaar." }, "info_url": { "type": "string", "format": "uri" } } }, "BeschikbaarheidResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "aankomst": { "type": "string", "format": "date" }, "vertrek": { "type": "string", "format": "date" }, "nachten": { "type": "integer" }, "personen": { "type": "integer" }, "aantal_types_beschikbaar": { "type": "integer", "description": "Aantal accommodatie-TYPES dat beschikbaar is (niet het aantal units). Voor units per type, zie accommodaties[].vrije_eenheden." }, "accommodaties": { "type": "array", "items": { "$ref": "#/components/schemas/BeschikbaarAccommodatie" } }, "niet_beschikbaar": { "type": "array", "items": { "$ref": "#/components/schemas/OnbeschikbareAccommodatie" } }, "algemene_boeking_url": { "type": "string", "format": "uri" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "RestaurantDag": { "type": "object", "properties": { "datum": { "type": "string", "format": "date" }, "dag": { "type": "string", "example": "zaterdag" }, "beschikbaar": { "type": "boolean" }, "vrije_tafels": { "type": "integer" }, "max_tafels": { "type": "integer" }, "restriction_reason": { "type": "string", "nullable": true }, "boeking_url": { "type": "string", "format": "uri", "nullable": true } } }, "RestaurantResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "restaurant": { "type": "object", "properties": { "naam": { "type": "string", "example": "The Kingdom of Dreams" }, "geopend_op": { "type": "array", "items": { "type": "string" } }, "aanvangstijd": { "type": "string", "example": "19:00" }, "voorschot_pp_euro": { "type": "number" }, "personen_per_tafel": { "type": "integer" } } }, "periode": { "type": "object", "properties": { "van": { "type": "string", "format": "date" }, "tot": { "type": "string", "format": "date" } } }, "dagen": { "type": "array", "items": { "$ref": "#/components/schemas/RestaurantDag" } }, "algemene_boeking_url": { "type": "string", "format": "uri" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "CamperDinerDag": { "type": "object", "properties": { "datum": { "type": "string", "format": "date" }, "beschikbaar": { "type": "boolean" }, "vrije_tafels": { "type": "integer" }, "max_tafels": { "type": "integer" }, "restriction_reason": { "type": "string", "nullable": true } } }, "CamperResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "beschikbaar": { "type": "boolean" }, "aankomst": { "type": "string", "format": "date" }, "vertrek": { "type": "string", "format": "date" }, "nachten": { "type": "integer" }, "vrije_plaatsen": { "type": "integer", "description": "Vrije camperplaatsen (max 3)." }, "max_plaatsen": { "type": "integer", "example": 3 }, "restriction_reason": { "type": "string", "nullable": true, "description": "Aanwezig wanneer beschikbaar=false." }, "prijs": { "type": "object", "properties": { "per_nacht_euro": { "type": "number" }, "verblijf_euro": { "type": "number" }, "waarborg_euro": { "type": "number" } } }, "diner": { "type": "object", "properties": { "verplicht": { "type": "boolean", "example": true }, "voorschot_euro": { "type": "number" }, "beschikbaarheid": { "type": "array", "items": { "$ref": "#/components/schemas/CamperDinerDag" } } } }, "ontbijt": { "type": "object", "properties": { "prijs_euro": { "type": "number" }, "dagen": { "type": "array", "items": { "type": "string", "format": "date" } } } }, "booking_url": { "type": "string", "format": "uri" }, "info_url": { "type": "string", "format": "uri" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "QuoteRequest": { "type": "object", "required": [ "type_slug", "aankomst", "vertrek" ], "properties": { "type_slug": { "type": "string", "example": "cabane", "description": "Slug uit /accommodaties, of 'camper'." }, "aankomst": { "type": "string", "format": "date", "example": "2026-07-15" }, "vertrek": { "type": "string", "format": "date", "example": "2026-07-18" }, "personen": { "type": "integer", "minimum": 1, "maximum": 6, "default": 2, "description": "Genegeerd voor camper." }, "lang": { "type": "string", "enum": [ "nl", "en", "fr", "de" ], "default": "nl" } } }, "QuoteResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "beschikbaar": { "type": "boolean" }, "type_slug": { "type": "string" }, "type_naam": { "type": "string" }, "aankomst": { "type": "string", "format": "date" }, "vertrek": { "type": "string", "format": "date" }, "nachten": { "type": "integer" }, "personen": { "type": "integer" }, "restriction_reason": { "type": "string", "nullable": true, "description": "Aanwezig wanneer beschikbaar=false." }, "prijs": { "type": "object", "properties": { "per_nacht_euro": { "type": "number" }, "totaal_bruto_euro": { "type": "number" }, "totaal_na_korting_euro": { "type": "number" }, "waarborg_euro": { "type": "number" }, "totaal_te_betalen_euro": { "type": "number" } } }, "booking_url": { "type": "string", "format": "uri", "description": "Deeplink die de boekingsengine voorvult." } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "InfoResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "naam": { "type": "string" }, "tagline": { "type": "string" }, "beschrijving": { "type": "string" }, "concept": { "type": "string" }, "adres": { "type": "object" }, "coordinaten": { "type": "object" }, "contact": { "type": "object" }, "restaurant": { "type": "object" }, "aantal_accommodatietypes": { "type": "integer", "example": 7, "description": "Aantal accommodatietypes (slugs)." }, "aantal_accommodaties": { "type": "integer", "example": 13, "description": "Bookbare accommodatie-eenheden, exclusief Camp & Dinner." }, "aantal_camperplaatsen": { "type": "integer", "example": 3 }, "aantal_eenheden_totaal": { "type": "integer", "example": 16, "description": "Alle eenheden incl. Camp & Dinner." }, "talen": { "type": "array", "items": { "type": "string" } }, "minimum_leeftijd": { "type": "integer", "example": 18 }, "api_endpoints": { "type": "object" }, "booking_url_root": { "type": "string", "format": "uri" }, "authenticatie": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }