{"info":{"contact":{"email":"info@ketelhuismonster.nl","name":"Het Ketelhuis Monster","url":"https://www.ketelhuismonster.nl"},"description":"Offici\u00eble machine-to-machine API voor Het Ketelhuis (Westlandse Bierbrouwerij ZWOL in Monster).\n\nHiermee kunnen AI agents en applicaties:\n1. Beschikbare bierproeverij-arrangementen en prijzen p.p. ophalen (`/api/products`).\n2. Realtime beschikbare tijdsloten controleren o.b.v. actuele openingstijden en groepsgrootte (`/api/availability`).\n3. Reserveringen definitief vastleggen namens gasten (`/api/book`), inclusief idempotentie-beveiliging.\n\n**Belangrijk:** Betaling vindt altijd ter plekke plaats aan de bar bij Het Ketelhuis (Pin of contant). Er is geen online betaalverificatie vereist, waardoor AI-agents boekingen autonoom kunnen afronden.","title":"Het Ketelhuis - Bierproeverijen & Reserveringen API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/availability":{"get":{"description":"Controleert realtime of Het Ketelhuis geopend is op de gekozen datum en welke tijdsloten van een half uur beschikbaar zijn voor de duur van het arrangement.","operationId":"checkAvailability","parameters":[{"description":"ID van het arrangement uit `/api/products` (bijv. 1 of 2)","example":2,"in":"query","name":"product_id","required":true,"schema":{"type":"integer"}},{"description":"Gewenste datum in ISO-formaat (YYYY-MM-DD)","example":"2026-10-10","in":"query","name":"date","required":true,"schema":{"format":"date","type":"string"}},{"description":"Optionele afwijkende duur in minuten (standaard de duur van het gekozen product)","example":90,"in":"query","name":"duration","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"close_time":{"example":"02:00","type":"string"},"date":{"example":"2026-10-10","type":"string"},"earliest_booking_date":{"example":"2026-10-09","type":"string"},"is_open":{"example":true,"type":"boolean"},"min_booking_days":{"example":5,"type":"integer"},"open_time":{"example":"12:00","type":"string"},"slots":{"items":{"properties":{"available":{"example":true,"type":"boolean"},"reason":{"example":null,"nullable":true,"type":"string"},"time":{"example":"15:00","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"success":{"example":true,"type":"boolean"}},"type":"object"}}},"description":"Beschikbaarheidsoverzicht per tijdslot"},"400":{"description":"Ongeldige invoer (bijv. ontbrekende datum of product_id)"}},"summary":"Controleer beschikbare tijdsloten voor een datum","tags":["Beschikbaarheid"]}},"/api/book":{"post":{"description":"Legt een definitieve reservering vast in het systeem.\n\n**Idempotentie:** Stuur optioneel een `Idempotency-Key` header of veld mee (bijv. een unieke UUID). Bij een herhaalde aanroep (retry loop) retourneert de API veilig de bestaande boeking zonder dubbele boeking.\n\n**Betaling:** Betaling geschiedt ter plekke aan de bar (Pin/contant).","operationId":"createBooking","parameters":[{"description":"Unieke idempotentie sleutel (UUID) om dubbele boekingen door agent retries te voorkomen.","in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string"}},{"description":"Naam van de AI agent die de boeking uitvoert (bijv. 'ChatGPT', 'Claude-Assistant', 'Project-Astra').","in":"header","name":"X-Agent-Name","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"agent_name":{"description":"Naam van de AI agent","example":"ChatGPT","type":"string"},"booking_date":{"description":"Datum van reservering (YYYY-MM-DD)","example":"2026-10-10","format":"date","type":"string"},"customer_email":{"description":"Geldig e-mailadres voor de bevestiging","example":"jan@example.nl","format":"email","type":"string"},"customer_name":{"description":"Volledige naam van de hoofdgast","example":"Jan Jansen","type":"string"},"customer_phone":{"description":"Nederlands 10-cijferig telefoonnummer (bijv. 06-12345678)","example":"06-12345678","type":"string"},"idempotency_key":{"description":"Optionele idempotentiesleutel (als alternatief voor header)","example":"uuid-1234-5678","type":"string"},"notes":{"description":"Optionele opmerkingen, dieetwensen of verjaardagen","example":"Graag een plekje dicht bij het raam","type":"string"},"persons_count":{"description":"Aantal personen (1 t/m 10)","example":4,"maximum":10,"minimum":1,"type":"integer"},"product_id":{"description":"ID van de proeverij","example":2,"type":"integer"},"source":{"description":"Bron van de boeking ('agent', 'web', 'mcp')","example":"agent","type":"string"},"start_time":{"description":"Starttijd in formaat HH:MM (per half uur)","example":"15:30","type":"string"}},"required":["product_id","persons_count","booking_date","start_time","customer_name","customer_email","customer_phone"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"booking":{"properties":{"booking_code":{"example":"KH-ZW-8421","type":"string"},"booking_date":{"example":"2026-10-10","type":"string"},"customer_name":{"example":"Jan Jansen","type":"string"},"end_time":{"example":"17:00","type":"string"},"ics_url":{"example":"https://boekingen.ketelhuismonster.nl/api/booking/KH-ZW-8421/ics","format":"uri","type":"string"},"idempotent_replayed":{"example":false,"type":"boolean"},"manage_url":{"example":"https://boekingen.ketelhuismonster.nl/reservering/beheren/tok_xyz123","format":"uri","type":"string"},"payment_info":{"example":"Betalen ter plekke aan de bar bij Het Ketelhuis (Pin of contant).","type":"string"},"persons_count":{"example":4,"type":"integer"},"product_name":{"example":"ZWOL Bierproeverij - 4 bieren (incl. hapjes)","type":"string"},"start_time":{"example":"15:30","type":"string"},"total_price":{"example":96.0,"type":"number"}},"type":"object"},"message":{"example":"Reservering succesvol geplaatst!","type":"string"},"success":{"example":true,"type":"boolean"}},"type":"object"}}},"description":"Boeking succesvol aangemaakt (of veilig herhaald via idempotentie)"},"400":{"description":"Validatiefout (ongeldig tijdslot, datum te kort van tevoren, ongeldig telefoonnummer)"}},"summary":"Plaats een definitieve reservering (Agentic Buying)","tags":["Reserveren"]}},"/api/booking/{booking_code}/ics":{"get":{"description":"Genereert een iCalendar agenda-bestand voor Apple Agenda, Google Agenda of Outlook.","operationId":"getBookingIcs","parameters":[{"example":"KH-ZW-8421","in":"path","name":"booking_code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"text/calendar":{}},"description":"iCalendar bestand"}},"summary":"Download iCalendar (.ics) bestand","tags":["Reserveren"]}},"/api/bookings/manage/{token}":{"get":{"description":"Geeft de details van de boeking terug aan de hand van de geheime manage_token. Conform data-minimalisatie en API-hygi\u00ebne worden interne integratie-identifiers (zoals `m365_event_id` en `google_event_id`) niet ge\u00ebxposeerd.","operationId":"getBookingByToken","parameters":[{"description":"Geheime `manage_token` uit de bevestigingsmail of boekingsrespons","in":"path","name":"token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"booking":{"properties":{"booking_code":{"example":"KH-ZW-8421","type":"string"},"booking_date":{"example":"2026-10-10","type":"string"},"can_modify_online":{"example":true,"type":"boolean"},"customer_email":{"example":"jan@example.nl","type":"string"},"customer_name":{"example":"Jan Jansen","type":"string"},"customer_phone":{"example":"06-12345678","type":"string"},"end_time":{"example":"17:00","type":"string"},"id":{"example":42,"type":"integer"},"is_past":{"example":false,"type":"boolean"},"is_within_2_hours":{"example":false,"type":"boolean"},"notes":{"example":"Graag een rustige tafel","type":"string"},"persons_count":{"example":4,"type":"integer"},"product_id":{"example":2,"type":"integer"},"product_name":{"example":"ZWOL Bierproeverij - 4 bieren (incl. hapjes)","type":"string"},"start_time":{"example":"15:30","type":"string"},"status":{"example":"confirmed","type":"string"},"total_price":{"example":96.0,"type":"number"}},"type":"object"},"success":{"example":true,"type":"boolean"}},"type":"object"}}},"description":"Reserveringsgegevens gevonden"},"404":{"description":"Reservering niet gevonden of ongeldige token"}},"summary":"Haal actuele status van een reservering op","tags":["Reserveren"]}},"/api/bookings/manage/{token}/cancel":{"post":{"description":"Annuleert de boeking tot maximaal 2 uur voor aanvang. Verwijdert de afspraak ook automatisch uit de Microsoft 365 agenda. Interne agenda-identificatiecodes worden niet ge\u00ebxposeerd.","operationId":"cancelBooking","parameters":[{"in":"path","name":"token","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"reason":{"example":"Verhinderd door ziekte","type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"description":"Boeking succesvol geannuleerd"},"400":{"description":"Kan niet annuleren (bijv. binnen 2 uur voor aanvang)"}},"summary":"Annuleer een bestaande reservering","tags":["Reserveren"]}},"/api/bookings/manage/{token}/update":{"post":{"description":"Wijzigt datum, starttijd, aantal personen, arrangement of opmerkingen van een reservering (tot 2 uur voor aanvang). Synchroniseert automatisch met de interne Microsoft 365 agenda.","operationId":"updateBooking","parameters":[{"description":"Geheime `manage_token`","in":"path","name":"token","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"booking_date":{"example":"2026-10-11","format":"date","type":"string"},"notes":{"example":"1 extra persoon sluit aan","type":"string"},"persons_count":{"example":5,"type":"integer"},"product_id":{"example":2,"type":"integer"},"start_time":{"example":"16:00","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"description":"Boeking succesvol gewijzigd"},"400":{"description":"Validatiefout (bijv. binnen 2 uur cutoff of tijdslot niet beschikbaar)"}},"summary":"Wijzig een bestaande reservering","tags":["Reserveren"]}},"/api/products":{"get":{"description":"Geeft een overzicht van de 4 offici\u00eble ZWOL proeverijen, inclusief duur (90 of 150 min), beschrijving, en prijsstaffels per aantal personen (1 t/m 10).","operationId":"getTastingProducts","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"earliest_booking_date":{"example":"2026-10-09","format":"date","type":"string"},"min_booking_days":{"description":"Minimaal aantal openingsdagen vooraf vereist om te boeken","example":5,"type":"integer"},"products":{"items":{"properties":{"category":{"example":"Proeverijen","type":"string"},"description":{"type":"string"},"duration_formatted":{"example":"1.5 uur","type":"string"},"duration_minutes":{"example":90,"type":"integer"},"id":{"example":1,"type":"integer"},"image_url":{"format":"uri","type":"string"},"min_price":{"example":24.0,"format":"float","type":"number"},"name":{"example":"ZWOL Bierproeverij - 4 bieren (incl. hapjes)","type":"string"},"variations":{"items":{"properties":{"persons_count":{"example":4,"type":"integer"},"price":{"example":96.0,"format":"float","type":"number"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"success":{"example":true,"type":"boolean"}},"type":"object"}}},"description":"Succesvol overzicht van arrangementen"}},"summary":"Haal alle actieve bierproeverij arrangementen op","tags":["Arrangementen"]}}},"servers":[{"description":"Productie & Staging Boekingen Server","url":"https://boekingen.ketelhuismonster.nl"}],"tags":[{"description":"Bierproeverij catalogus, prijzen en details","name":"Arrangementen"},{"description":"Realtime tijdsloten en openingstijden","name":"Beschikbaarheid"},{"description":"Boekingen aanmaken, inzien en beheren","name":"Reserveren"}]}