Ontwikkelaar
Instructie
Moeilijkheidsgraad: Gemiddeld
Beheer > Integraties > Salto KS

De Salto KS-koppeling vereist configuratie aan twee kanten: eerst de Salto-installatie (Site + IQ + sloten + account), daarna de koppeling in i-Reserve, inclusief het activeren van de IQ-PIN.

1. Aan de Salto-kant

  1. Zorg dat er een Site bestaat en noteer de Site UID (bijv. NL6254340082).
  2. Zorg dat de IQ online gateway is gekoppeld aan de site en online is; noteer het IQ-id.
  3. Zorg dat de te bedienen sloten in de site zijn geregistreerd en bereikbaar via de IQ.
  4. Maak/gebruik een Salto KS-account (gebruikersnaam + wachtwoord) met voldoende rechten op de site.

De OAuth client-credentials voor Salto KS worden op platformniveau door i-Reserve beheerd; jij levert het account aan.

2. Aan de i-Reserve-kant — Authenticatie-tab

VeldWat in te vullen
OmgevingAcceptance (testen) of Production (live). Verplicht.
Site UIDDe leesbare site-code uit Salto (bijv. NL6254340082). Verplicht.
Site IDHet interne site-id (UUID). Klik op Resolve site ID om dit automatisch op te halen uit de Site UID. Alleen-lezen.
GebruikersnaamDe gebruikersnaam van het Salto KS-account. Verplicht.
WachtwoordHet wachtwoord van het Salto KS-account. Verplicht.

Klik op Test / toegang aanvragen om een token op te halen en de verbinding te controleren.

2.1 IQ OTP-setup (PIN activeren)

In het blok IQ OTP setup activeer je de IQ-gateway met een PIN. Dit is verplicht voordat sloten geopend kunnen worden.

  1. Vul het IQ-id in (UUID van de IQ-gateway).
  2. Klik op GET PIN om de huidige PIN van de IQ op te halen (verschijnt in current pin).
  3. Vul bij new pin de gewenste 4-cijferige PIN in.
  4. Klik op Set PIN: i-Reserve zet de nieuwe PIN op de IQ (ondertekend met een OTP op basis van de huidige PIN + het IQ-secret).
  5. Bij succes verandert de status naar “IQ is activated”. Vanaf nu kan i-Reserve geldige open-commando’s ondertekenen.

3. Details-tab

VeldWat het doet
Slot mag openen vanaf statusDe reserveringsstatus(sen) waarbij het openen van het slot is toegestaan. Meervoudige selectie.
Tijd vooraf (minuten)Aantal minuten vóór de starttijd dat openen al mag (0–1440).
Laatste open-actie opslaan in veldReserveringsveld waarin het tijdstip van openen wordt vastgelegd. Optioneel.
Status na openen (check-in)Reservering wordt na een geslaagde opening automatisch naar deze status gezet. Optioneel.

3.1 Mapping: object → slot

Op het Mapping-tabblad koppel je per i-Reserve-object (product) een slot. Kies links het product en rechts het slot uit de keuzelijst; die lijst vul je met de knop GET locks (haalt de sloten van de site op). Een object zonder eigen mapping kan op een standaardslot (wildcard) vallen.

Objecten én sub-objecten. De objecten-keuzelijst links toont nu zowel hoofdobjecten als hun sub-objecten. Zo kun je een mapping leggen op het niveau van een specifiek sub-object (bijvoorbeeld één studio binnen een verzamelobject), niet alleen op het hoofdobject. Bij een reservering op een sub-object draagt de boeking dat sub-object, waardoor de meest specifieke mapping wordt gebruikt. Bestaande hoofdobject-mappings blijven gewoon werken.

De koppeling verstuurt zelf niets: er gaat geen e-mail of code automatisch naar de klant, en een statuswijziging opent het slot niet. De klant opent het slot via een persoonlijke link. Die link neem je op in een e-mail- of sms-template met de variabele {OPENLOCKLINK} (zie Variabelen reservering).

  1. Kies het template waarmee de klant de link krijgt, bijvoorbeeld de bevestiging of een herinnering kort voor aanvang.
  2. Neem de link op, bijvoorbeeld: Bij aankomst open je de deur via deze link: {OPENLOCKLINK}
  3. De klant opent de link op de telefoon en ziet de pagina Open deur met de reservering. Bij de deur drukt de klant op de knop Open deur.

Bij het openen van de pagina en bij het klikken controleert i-Reserve het volgende. Klopt iets niet, dan toont de pagina de melding uit de rechterkolom en blijft het slot dicht.

ControleMelding als het niet klopt
De link (reserveringsnummer + hashkey) is geldig.Deze toegangslink is ongeldig.
Er is een actieve Salto KS-koppeling.Geen actieve slotintegratie gevonden voor deze reservering.
Het object van de reservering heeft een slot in de mapping (of er is een wildcard *).Geen slot-mapping gevonden voor het object van deze reservering.
De status van de reservering staat bij Slot mag openen vanaf status. Leeg = elke status.Deur openen is niet toegestaan voor de huidige reserveringsstatus (…).
Het is nu tussen starttijd min Tijd vooraf en de eindtijd van de reservering.Deur openen is beschikbaar vanaf … / Deur openen is niet meer beschikbaar (reservering eindigde om …).

Na een geslaagde opening zet i-Reserve het tijdstip in het open-actie-veld en zet de reservering op de check-in-status. Die statuswijziging loopt via de normale statusverwerking, net als een wijziging met de hand.

Tip voor testen: verstuur het template naar jezelf bij een testreservering en open de link in de browser. De melding op de pagina vertelt direct welke controle nog niet klopt.

4.1 Slotcontrole vanuit de reservering

Met een actieve Salto KS-koppeling staat in het actieblok van elke reservering de knop Salto KS slot. Die toont per criterium een groen vinkje of rood kruis, en geeft de klantlink om te kopiëren of te openen. Zie Slotcontrole vanuit de reservering.

4.2 Openen met pincode

Heeft een slot een toetsenbord, dan kan de klant het ook met een pincode openen. Zet daarvoor in de instellingen van de koppeling, onder Pincode op het toetsenbord, Pincode indien mogelijk op Ja (standaard Nee) en kies het reserveringsveld voor de pincode.

  • Of een slot een toetsenbord heeft, bepaalt i-Reserve aan het slottype in Salto. Het instellingenscherm toont onder Sloten met toetsenbord welke sloten dat zijn. Voeg je in Salto een slot toe, haal de sloten dan opnieuw op.
  • Krijgt een reservering een status uit Slot mag open bij status, dan maakt i-Reserve in Salto een eigen gebruiker met een pincode aan, geldig van de starttijd min Tijd ervoor tot het einde van de reservering. Dat gebeurt vóór de statusmail, dus de pincode kan in de bevestiging met {LOCKPIN}.
  • Bij een slot zonder toetsenbord blijft het de link. De link blijft ook bij een slot met pincode werken, bijvoorbeeld om hem los te sms’en.
  • Verplaats je de reservering (datum, tijd of object), dan schuift de toegang mee; de pincode blijft dezelfde. Krijgt de reservering een andere status of wordt hij verwijderd, dan wordt de pincode ingetrokken. Een dag na afloop ruimt i-Reserve de gebruiker in Salto op.
  • Op het slot toetst de klant de pincode in. Salto bepaalt de pincode zelf (6 cijfers).

5. Activeren en testen

Sla op en zet de koppeling op actief. Open een testreservering en controleer met Salto KS slot in het actieblok dat alle criteria groen zijn (zie Slotcontrole vanuit de reservering). Open daarna de link uit het template en druk op Open deur. Controleer dat het slot opent en dat (indien ingesteld) de open-tijd en de check-in-status worden bijgewerkt.

De IQ-gateway moet met een PIN zijn geactiveerd ("IQ is activated") voordat sloten geopend kunnen worden. De PIN + het IQ-secret vormen de OTP waarmee elk open-commando wordt ondertekend.
Wijzig je de IQ-PIN buiten i-Reserve om, dan moet je de koppeling opnieuw activeren (GET PIN / Set PIN). Anders kloppen de OTP-commando’s niet meer en gaat de deur niet open.
Acceptance en production zijn gescheiden omgevingen met een eigen account, site en IQ. Test eerst volledig in acceptance voordat je production inricht.