API en webhooks

Een ander systeem kan vandaag drie dingen met Noren: een melding krijgen bij elke wijziging (webhook), dezelfde meldingen ophalen (de feed), en een post op de rekening van een boeking zetten. Sleutels en webhooks beheer je zelf onder Koppelingen, Eigen koppelingen; daar staat ook de voorbeeldcode. Zie Eigen koppelingen.

Open Eigen koppelingen

Sleutels

• "Sleutel maken" vraagt een naam, het huis en "Wat mag deze sleutel?": "Gebeurtenissen lezen (de feed)" en/of "Op de rekening van een gast boeken". Eén sleutel per systeem.
• De sleutel staat één keer op het scherm. Kwijt is "Intrekken" en een nieuwe maken.
• Stuur hem mee als Authorization: Bearer <sleutel>. Limiet: 120 verzoeken per minuut, daarboven 429 met Retry-After.

Gebeurtenissen

Een gebeurtenis is dun: id (vast, ook bij een nieuwe poging), type, occurredAt, propertyId, object (booking, unit of day) en version, een volgnummer per object zonder gaten. Alleen folio.charged en folio.voided hebben ook data met de regel.

Soorten: booking.created, .confirmed, .modified, .cancelled, .room_assigned, .room_moved, .guest_updated, .online_checkin_completed, .checked_in, .checkin_reversed, .checked_out en .no_show; payment.received en .refunded; folio.charged en .voided; unit.housekeeping_changed; day.closed (middernacht in het huis). webhook.test komt alleen na "Testen".

Webhooks

• Een https-adres buiten een lokaal of intern netwerk, met de gekozen soorten. Het geheim (whsec_…) zie je één keer.
• Elke aflevering is een POST met de koppen x-noren-event, x-noren-event-id, x-noren-delivery, x-noren-timestamp en x-noren-signature. De handtekening is HMAC-SHA256 (hex) over tijdstip.body, met het geheim als sleutel. Weiger een tijdstip dat meer dan vijf minuten afwijkt.
• Levering is minstens één keer, en de volgorde ligt niet vast. Ontdubbel op id, negeer een version die niet hoger is dan wat je had.
• Antwoord binnen tien seconden met een 2xx. Anders volgen tot tien pogingen in ruim twee dagen. Het "Afleverlog" toont de laatste vijftig; "Opnieuw afspelen" stuurt dezelfde id.

De feed

GET /api/v1/events?cursor=…&count=… met een sleutel die gebeurtenissen mag lezen. Stuur de cursor uit het antwoord mee bij de volgende vraag. count is standaard 100, hoogstens 500; een kortere pagina betekent dat je bij bent. Gebeurtenissen blijven dertig dagen.

De rekening

GET /api/folio/{bookingId}/charge geeft de rekening; POST zet er één post op, met een verplichte Idempotency-Key. De body is een artikel (extraId, quantity) of een vrije regel (description, amountCents, vatRate, quantity, kind). Er beweegt geen geld.

Beveiliging

Eindigt je abonnement, dan gaan sleutels en webhooks direct uit. Hoe we beveiligen en waar je een zwakke plek meldt, staat op de pagina "Vertrouwen" van onze site en in security.txt.

Nog niet beschikbaar

• Een publieke API voor boekingen, beschikbaarheid, prijzen of gasten. Na een gebeurtenis kun je de stand van een boeking nog niet via de API ophalen.
• Een boeking opzoeken via de API.