Best practices

Gebruik deze patronen om partnerintegraties voorspelbaar, controleerbaar en veilig te houden voor faciliteiten.

Faciliteiten consequent identificeren

Kies de koppelmethode die voor je partneraccount is geconfigureerd en gebruik die consequent:

• Direct Link - gebruik het Performance Hub-facility_id dat door het facilities-endpoint wordt geretourneerd.
• Linking Identifier - gebruik je eigen locatie-identificatie, zoals een vestigings-ID, locatiecode of winkelnummer.

Stuur niet beide identificaties in hetzelfde verzoek. Performance Hub verwerkt verzoeken met de koppelmethode die voor je partneraccount is geconfigureerd.

Zie Koppelmethoden voor partners voor hulp bij de configuratie.

Schrijf zorgvuldig in batches

De Partner API accepteert JSON-request-bodies en is, waar gedocumenteerd, ontworpen voor synchronisatieprocessen in batches. Houd batches begrensd en geschikt voor nieuwe pogingen.

Standaardrichtlijnen:

• Gebruik maximaal 1000 items per batchverzoek voor optimale prestaties.
• Houd payloads onder 10MB.
• Blijf binnen 5 verzoeken per seconde per endpoint.

Snelheidslimieten zijn aanpasbaar en kunnen per geval worden geconfigureerd door je partneraccountmanager bij Performance Hub. Verwacht je imports met een groot volume, verkeer rond een lancering of rapportage-backfills, spreek dan vóór het wijzigingsvenster de benodigde doorvoer af.

Moet je een grote dataset synchroniseren, splits die dan op in deterministische delen en log aan jouw kant het ID van elk deel. Zo zijn mislukte nieuwe pogingen makkelijker te analyseren.

Probeer veilig opnieuw

Gebruik exponentiële backoff voor tijdelijke fouten zoals 429, 500, 502, 503 en 504.

Vermijd snelle lussen van nieuwe pogingen. Een goed uitgangspunt is:

1. Probeer het na 1 seconde opnieuw.
2. Probeer het na 2 seconden opnieuw.
3. Probeer het na 4 seconden opnieuw.
4. Stop en geef een waarschuwing als de bewerking nog steeds mislukt.

Corrigeer bij validatiefouten zoals 400 of 422 eerst het verzoek voordat je het opnieuw probeert.

Gebruik idempotentie waar dat wordt ondersteund

Het unlock-endpoint van de Door/Gate Controller ondersteunt een optionele idempotency_key. Als je dezelfde sleutel opnieuw gebruikt voor dezelfde partner, faciliteit en deur, wordt het bestaande resultaat geretourneerd wanneer dat beschikbaar is.

Gebruik een stabiele sleutel voor de uitgevoerde actie, bijvoorbeeld een check-in-ID of toegangsgebeurtenis-ID uit je systeem.

Ga er niet van uit dat elk schrijf-endpoint idempotentie ondersteunt, tenzij dat voor dat endpoint is gedocumenteerd.

Houd brongegevens schoon

Stuur waar mogelijk stabiele, genormaliseerde waarden:

• Gebruik consistente ID's voor leden, abonnementen, faciliteiten en check-ins uit je bronsysteem.
• Gebruik ISO 8601-tijdstempels voor datums en tijden.
• Stuur telefoonnummers waar mogelijk in internationale notatie.
• Stuur valuta via de velden die voor elk endpoint zijn gedocumenteerd.
• Overlaad vrije-tekstvelden niet met gegevens die in gestructureerde velden thuishoren.

Ontwerp voor incrementele en volledige synchronisaties

De meeste partnerintegraties hebben beide nodig:

• Incrementele synchronisaties voor dagelijkse wijzigingen.
• Volledige reconciliatiesynchronisaties om gemiste gebeurtenissen, historische imports of afwijkende gegevens te corrigeren.

Je integratie moet de huidige status van een lid, abonnement of rapportmomentopname opnieuw kunnen verzenden zonder afhankelijk te zijn van het slagen van een eerder verzoek.

Publiceer Access Time Windows veilig

Behandel de waarde access_time_windows van elk lid als een volledige momentopname met een eigen revisie:

• Coördineer één monotoon oplopende reeks access_time_windows_revision over de incrementele en reconciliatieworkers heen.
• Herhaal een onzekere of tijdelijk mislukte levering met dezelfde revisie en genormaliseerde payload.
• Laat access_time_windows weg wanneer je deze niet bijwerkt.
• Stuur [] alleen nadat een geslaagde, gezaghebbende ophaalactie bij de bron heeft aangetoond dat er geen vensters meer zijn. Laat een upstream time-out, een gedeeltelijk resultaat of een parseerfout nooit leiden tot intrekking.
• Houd external_id en scope_key stabiel en certificeer elke scopetoewijzing vóór productie.
• Bewaak de leeftijd van de brongegevens aan de hand van het actualiteitsbeleid dat voor die integratie is afgesproken.

Zie de gezaghebbende handleiding voor producenten van Access Time Windows voor volledige momentopnamen, tijdzones, zomertijd, annulering en testvectoren.

Behandel toegangsbeheer als veiligheidskritiek

Voor ontgrendelingen van een Door/Gate Controller geldt:

• Je systeem moet beslissen of iemand naar binnen mag voordat Performance Hub wordt aangeroepen.
• Performance Hub retourneert pas 200 nadat de controller ter plaatse bevestigt dat het relais fysiek is ontgrendeld.
• De meeste bevestigingen zijn binnen 3-5 seconden binnen.
• Een time-out is een expliciet mislukte ontgrendeling, geen succes op de achtergrond.
• Probeer het alleen opnieuw volgens je eigen toegangs- en veiligheidsregels.

Log altijd de event_id en command_id die het unlock-endpoint retourneert.

Bewaak je integratie

Gebruik de verzoeklogboeken in de Partner Console tijdens de ontwikkeling en lancering. Houd in productie ook je eigen logboeken bij met:

• Tijdstempel van het verzoek.
• Endpoint.
• Bronrecord-ID.
• Faciliteitidentificatie.
• HTTP-statuscode.
• Response-body of foutmelding van Performance Hub.

Met deze velden gaan ondersteuning en reconciliatie veel sneller wanneer een klant vraagt wat er is gebeurd.