Inleiding

Met de Performance Hub Partner API kunnen externe partnerplatforms naadloos integreren met de kernmodules van Performance Hub. De API ondersteunt computer vision, analyses, registratie van toegang door leden en inzichten in faciliteiten.

Indeling van verzoeken

De API accepteert JSON-gecodeerde request-bodies en retourneert JSON-gecodeerde responses.

Snelheidsbeperking

Voor eerlijk gebruik en een stabiel systeem beginnen Partner API-accounts met standaardlimieten:

• 5 verzoeken per seconde per endpoint
• Aanbevolen: maximaal 1000 items per batchverzoek voor optimale prestaties
• Maximaal 10MB payloadgrootte

Snelheidslimieten zijn aanpasbaar en kunnen per geval worden geconfigureerd door je partneraccountmanager bij Performance Hub. Heeft je integratie een hogere doorvoer nodig voor een lancering, migraties, rapportage-backfills of faciliteiten met veel verkeer, geef dit dan aan tijdens de onboarding of vóór het geplande wijzigingsvenster.

Authenticatie

Voor toegang tot de Partner API is authenticatie met geheime API-sleutels vereist. Genereer en beheer je sleutels via de Partner Console.

API-sleutels zijn je inloggegevens voor toegang tot partnerresources. Elke sleutel heeft beperkte toegang tot specifieke organisatiegegevens en kan indien nodig direct worden gedeactiveerd.

Ga zorgvuldig om met je API-sleutels: ze geven volledige toegang tot je account! Stel deze sleutels nooit bloot in openbare repository's, client-side applicaties of op andere plaatsen waar ze kunnen worden misbruikt.

Authenticeer verzoeken met HTTP Basic Auth door je API-sleutel als gebruikersnaam mee te geven. Laat het wachtwoord leeg.

De API accepteert alleen beveiligde HTTPS-verbindingen. Gewone HTTP-verzoeken worden geweigerd, net als verzoeken zonder geldige authenticatiegegevens.

Checklist voor livegang

Gebruik deze checklist voordat je een partnerintegratie inschakelt voor faciliteiten in productie.

Configuratie van de Partner Console

• Je partnerprofiel is volledig.
• Je logo-URL, website, categorie en beschrijving kloppen.
• Je koppelmethode voor gegevens is geconfigureerd: Direct Link of Linking Identifier.
• De koppeling met faciliteiten is getest met minstens één echte faciliteit.
• Het juiste sleuteltype wordt gebruikt:
  • Dryrun voor niet-destructieve schrijftests.
  • Read-only voor veilig gebruik van gegevens.
  • Live alleen wanneer je klaar bent om productiegegevens te beïnvloeden.

Authenticatie en sleutelbeheer

• Geheime sleutels worden alleen aan de serverzijde opgeslagen.
• Sleutels zijn niet opgenomen in client-side applicaties, mobiele apps, openbare repository's of supporttickets.
• Rotatie en intrekking van sleutels zijn getest.
• Je team weet welke sleutel in welke omgeving wordt gebruikt.

Gegevensvalidatie

• Verplichte velden zijn aanwezig voor elk endpoint dat je aanroept.
• Faciliteitidentificaties komen overeen met je geconfigureerde koppelmethode.
• ID's uit je systeem zijn stabiel en veranderen niet tussen synchronisaties.
• Grote imports worden opgesplitst in batches binnen de gedocumenteerde limieten.
• Mislukte items in een batch kunnen worden herkend en opnieuw worden verzonden.

Endpoints testen

Test vóór de lancering elk endpoint waarvan je integratie afhankelijk is:

• Organisaties en faciliteiten kunnen worden gelezen.
• Leden kunnen worden opgeslagen en bijgewerkt.
• Abonnementen, toegangszones en toegangsuren worden correct gesynchroniseerd.
• Check-ins worden geaccepteerd en kunnen worden herleid naar je systeem.
• Rapportmomentopnamen gebruiken de verwachte rapportageperiode en metrics.
• Processen met de Door/Gate Controller zijn waar van toepassing op echte hardware getest.

Gereedheid voor Access Time Windows

Als de integratie Access Time Windows aanlevert:

• Absolute en wekelijkse voorbeelden doorstaan de certificeringschecklist voor producenten.
• Epochs zijn gehele getallen in Unix-seconden zonder aanhalingstekens; exacte grenzen van [from, to) zijn getest.
• UTC-standaarden, de aangepaste IANA-tijdzones van de integratie en relevante overgangen naar en van zomertijd zijn gecontroleerd.
• Eén duurzame, monotone revisiereeks per lid/bron coördineert incrementele updates, reconciliatie en nieuwe pogingen.
• Beheerders begrijpen het gedrag bij weggelaten, volledig vervangende, idempotente, conflicterende, verouderde en expliciete []-waarden.
• Elke scope_key, inclusief default, heeft een goedgekeurde toewijzing in Performance Hub; er is getest dat onbekende sleutels tot weigering leiden (fail-closed).
• De verwachte verversingsfrequentie, de maximale leeftijd van brongegevens, het gedrag bij verouderde bronnen en de waarschuwingen van de integratie zijn geconfigureerd.
• Er is aangetoond dat een mislukte upstream ophaalactie geen lege of gedeeltelijke momentopname verzendt.
• Convergentie van de reeks in de testomgeving, annulering/intrekking en begin- en eindgrenzen bij de fysieke deur voldoen aan de afgesproken doelen.
• Reguliere regels en permanente toegangsrechten zijn gecontroleerd als terugvalroutes, en vensters kunnen het uitschakelen van gebruikers, blockAllAccess, onderhoud of geofencing niet omzeilen.

Gereedheid voor toegangsbeheer

Voor integraties met toegangsbeheer:

• Je systeem neemt de toegangsbeslissing voordat Performance Hub wordt aangeroepen.
• De integratie verwerkt device_offline, maintenance_mode_active en unlock_confirmation_timeout.
• Beheerders begrijpen dat een time-out betekent dat de ontgrendeling niet is bevestigd.
• Je logboeken bewaren de geretourneerde event_id en command_id.
• Je hebt een handmatige terugvalprocedure voor medewerkers van de faciliteit.

Foutafhandeling en nieuwe pogingen

• Responses met 400, 401, 403, 404, 409 en 422 worden aan beheerders of supportteams gemeld in plaats van blindelings opnieuw geprobeerd.
• Responses met 429, 500, 502, 503 en 504 gebruiken begrensde logica voor nieuwe pogingen met backoff.
• Herhaalde fouten leiden tot een waarschuwing in je systeem.
• De integratie laat mislukte records nooit stilletjes vallen.

Observeerbaarheid

• Je logboeken bevatten het endpoint, de tijdstempel, de faciliteitidentificatie, het bronrecord-ID, de uitkomst van het verzoek en de response-body.
• Je supportteam kan zoeken op lid-ID, faciliteit-ID, check-in-ID of ID van de ontgrendelgebeurtenis.
• Je kunt mislukte synchronisaties opnieuw afspelen of reconciliëren.

Productielancering

• Performance Hub heeft je productietoegang bevestigd.
• Minstens één faciliteit in productie heeft je integratie ingeschakeld.
• Je productiesleutel is actief.
• Je operationele en technische contactpersonen zijn actueel.
• Je ondersteuningsproces is voor klanten gedocumenteerd.

Nadat deze controles zijn afgerond, verschijnt je geconfigureerde integratie in de Performance Hub-partnerdirectory binnen het centrale Performance Hub-platform.

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.

Organisaties

Vertegenwoordigt de bedrijfsentiteit op het hoogste niveau die een of meer faciliteiten exploiteert die met het Performance Hub-platform zijn geïntegreerd.

Het organisatieobject

Attributen

• org_id string verplicht

  Unieke identificatie van de organisatie.

• name string verplicht

  Naam van de organisatie.

Alle organisaties opvragen

Retourneert een lijst van organisaties die toegankelijk zijn voor je partneraccount.

Retourwaarde

Retourneert een JSON-object met een eigenschap data die een array van organisatieobjecten bevat.

Faciliteiten

Vertegenwoordigt een fysieke locatie, zoals een kantoor, winkel, evenementenlocatie, campus, kliniek of sportschool, waar leden gebruik kunnen maken van diensten.

Het faciliteitobject

Attributen

• facility_id string verplicht

  Unieke identificatie van de faciliteit.

• org_id string verplicht

  Unieke identificatie van de bovenliggende organisatie.

• name string verplicht

  Naam van de faciliteit.

• brand string optioneel

  Merknaam die de faciliteit gebruikt.

• website_url string optioneel

  URL van de website van de faciliteit.

• place_data object optioneel

  Locatiegegevens uit de Google Places API met land, opgemaakt adres, Google Place ID, provincie en plaats.

• social_links object optioneel

  Links naar sociale media van de faciliteit.

• timezone string optioneel

  IANA-tijdzone-identificatie (bijvoorbeeld "Australia/Sydney", "America/New_York").

Alle faciliteiten opvragen

Retourneert een lijst van faciliteiten die toegankelijk zijn voor je partneraccount.

Retourwaarde

Retourneert een JSON-object met een eigenschap data die een array van faciliteitobjecten bevat.

Abonnementen

Definieert een aanbod van een organisatie of faciliteit dat kan worden gekocht, inclusief diensten, rechten, planning en prijzen.

Het Membership Plan-object

Attributen

• membership_plan_id string verplicht

  Unieke identificatie van het abonnement.

• facility_id string een van beideGeef het type faciliteitidentificatie op dat voor je integratie is geconfigureerd: gebruik facility_id voor integraties met Direct Link of linking_identifier voor integraties met een Linking Identifier. Stuur ze niet allebei: de API gebruikt het identificatietype dat voor je partneraccount is geconfigureerd en negeert het andere. Meer informatie

  Unieke identificatie van de faciliteit uit Performance Hub.

• linking_identifier string een van beideGeef het type faciliteitidentificatie op dat voor je integratie is geconfigureerd: gebruik facility_id voor integraties met Direct Link of linking_identifier voor integraties met een Linking Identifier. Stuur ze niet allebei: de API gebruikt het identificatietype dat voor je partneraccount is geconfigureerd en negeert het andere. Meer informatie

  Unieke identificatiewaarde die de partner voor elke locatie gebruikt (bijvoorbeeld "Branch ID", "Location Code", "Store Number"). Meer informatie

• name string verplicht

  Leesbare naam van het abonnement (bijvoorbeeld "Office tenant – business hours", "Student – term access", "Hotel guest", "10 Class Pack").

• billing_cycle string optioneel

  Factureringsfrequentie. Een van weekly, fortnightly, monthly, annually of one_time.

• price integer optioneel

  Basisprijs in de kleinste munteenheid (centen voor USD/AUD).

• currency string optioneel

  ISO 4217-valutacode (bijvoorbeeld "AUD", "USD").

• description string optioneel

  Optionele marketing- of interne beschrijving.

• active_members integer optioneel

  Aantal actieve leden met dit abonnement

• is_recurring boolean optioneel

  Of het abonnement automatisch wordt verlengd.

• is_trial boolean optioneel

  Of dit een proefaanbod is.

• visible_to_public boolean optioneel

  Of het abonnement via selfservice kan worden gekocht.

• duration_days integer optioneel

  Aantal dagen dat het abonnement geldig is.

• access_zones array optioneel

  Array van toegangszones die in het abonnement zijn inbegrepen. Elke zone kan eigen toegangsuren definiëren. Zie Toegangszones voor meer informatie.

• class_limit integer optioneel

  Maximaal toegestaan aantal lessen (null voor onbeperkt).

Toegangszones

Toegangszones definiëren specifieke delen van een faciliteit waartoe een abonnement toegang geeft. Elke zone kan eigen toegangsuren hebben, zodat er per deel verschillende tijdsbeperkingen kunnen gelden.

Structuur

Elke toegangszone bevat:

• name string verplicht

  De naam van de zone (bijvoorbeeld "Level 3 Tenancy", "Library", "Guest Floors", "Main Gym Floor").

• description string optioneel

  Beschrijving van wat er in die zone is inbegrepen.

• access_hours object optioneel

  Toegangsuren die specifiek voor deze zone gelden. Zie Toegangsuren voor de notatie van tijdsbereiken.

Toegangsuren

Toegangsuren geven aan wanneer leden op elke dag van de week toegang hebben tot een specifieke zone. Toegangsuren worden per toegangszone gedefinieerd, zodat er voor verschillende delen van een faciliteit verschillende tijdsbeperkingen kunnen gelden.

Een abonnement opslaan

Maakt abonnementsrecords aan of werkt ze bij. De API bepaalt op basis van membership_plan_id of een record wordt aangemaakt of bijgewerkt.

Parameters

• membership_plans array verplicht

  Array van Membership Plan-objecten om op te slaan. Aanbevolen maximum: 1000 items per verzoek voor optimale prestaties. De API verdeelt items automatisch in batches voor verwerking. Elk item moet facility_id (verplicht als je linking_identifier niet gebruikt) of linking_identifier (verplicht als je facility_id niet gebruikt) bevatten.

Retourwaarde

Retourneert een eenvoudig bericht dat de synchronisatie bevestigt.

Leden

Vertegenwoordigt een individuele klant van een faciliteit. Dit kan een lead, prospect, terugkerende klant, verlopen lid of geblokkeerde gebruiker zijn.

Upserts van leden kunnen ook een volledige access_time_windows-momentopname met revisie bevatten, met absolute en wekelijks terugkerende toegang. Lees Access Time Windows voordat je deze velden aanlevert. Het zijn aanvullende rechten die de reguliere regels of permanente toegangsrechten van de faciliteit niet vervangen.

Het Member-object

Attributen

• member_id string verplicht

  Unieke identificatie van het lid.

• facility_id string een van beideGeef het type faciliteitidentificatie op dat voor je integratie is geconfigureerd: gebruik facility_id voor integraties met Direct Link of linking_identifier voor integraties met een Linking Identifier. Stuur ze niet allebei: de API gebruikt het identificatietype dat voor je partneraccount is geconfigureerd en negeert het andere. Meer informatie

  Unieke identificatie van de faciliteit uit Performance Hub.

• linking_identifier string een van beideGeef het type faciliteitidentificatie op dat voor je integratie is geconfigureerd: gebruik facility_id voor integraties met Direct Link of linking_identifier voor integraties met een Linking Identifier. Stuur ze niet allebei: de API gebruikt het identificatietype dat voor je partneraccount is geconfigureerd en negeert het andere. Meer informatie

  Unieke identificatiewaarde die de partner voor elke locatie gebruikt (bijvoorbeeld "Branch ID", "Location Code", "Store Number"). Meer informatie

• first_name string verplicht

  Voornaam van het lid.

• last_name string verplicht

  Achternaam van het lid.

• email string optioneel

  E-mailadres.

• mobile_phone string optioneel

  Mobiel telefoonnummer in E.123-notatie (bijvoorbeeld "+1 415 555 2671").

• address object optioneel

  Object met het fysieke adres en de volgende eigenschappen:

  • address_line_1 (string) - Primair straatadres
  • address_line_2 (string, optioneel) - Tweede adresregel
  • city (string) - Plaatsnaam
  • state (string) - Code van staat/provincie
  • postal_code (string) - Postcode
  • country (string) - ISO 3166-1 alpha-2-landcode (bijvoorbeeld "AU", "US")
  • country_name (string, optioneel) - Volledige landnaam

• date_of_birth string optioneel

  Geboortedatum in de notatie YYYY-MM-DD.

• gender string optioneel

  Een van male, female, non_binary, prefer_not_to_say of unknown.

• type string optioneel

  Type lid (bijvoorbeeld staff, member, prospect).

• tags array optioneel

  Korte hulptekenreeksen of teksten om specifieke leden in te delen en te herkennen (bijvoorbeeld ["vip", "personal-training", "student"]).

• membership_status string optioneel

  Huidige lidmaatschapsstatus (bijvoorbeeld active, expired, on_hold).

• membership_plans array optioneel

  Array van abonnementen die aan het lid zijn gekoppeld.

• profile_picture string optioneel

  Base64-gecodeerde profielfoto (optioneel).

• created string optioneel

  ISO 8601-tijdstempel van het moment waarop het lid is aangemaakt.

• updated string optioneel

  ISO 8601-tijdstempel van het moment waarop het lid voor het laatst is bijgewerkt.

• access_time_windows array optioneel

  Volledige momentopname van de bron met absolute en/of wekelijks terugkerende Access Time Windows. Laat het veld weg om de momentopname ongewijzigd te laten; stuur een lege array met een nieuwere revisie om deze in te trekken. Zie Access Time Windows voor de vormen, validatie, scopetoewijzing en vervangingssemantiek.

• access_time_windows_revision integer verplicht met access_time_windows

  Monotoon oplopend, niet-negatief JSON-veilig geheel getal voor de reeks van dit lid/deze bron. Verplicht wanneer access_time_windows aanwezig is.

Toegangstijdvensters

Met Access Time Windows kan een Partner Member tijdelijke of terugkerende toegang meekrijgen die door een extern systeem wordt aangeleverd. Deze pagina is de gezaghebbende handleiding voor producenten van access_time_windows en access_time_windows_revision.

Access Time Windows zijn aanvullende rechten die alleen toegang kunnen toestaan. Een actief venster kan toegang toestaan, maar een inactief, verlopen, verouderd of niet-toegewezen venster weigert geen toegang die een reguliere regel of een permanent toegangsrecht al toestaat. Het uitschakelen van gebruikers, expliciete deurblokkering, de onderhoudsmodus, geofencing, snelheidslimieten en de beschikbaarheid van controllers blijven van toepassing.

Implementaties voor specifieke upstream systemen zijn afzonderlijke adapters. Ze moeten hun brongegevens vertalen naar dit leverancierneutrale contract zonder de betekenis van de velden te veranderen.

Velden van de momentopname van een lid

• access_time_windows array optioneel

  De volledige momentopname van Access Time Windows voor dit lid en deze partnerbron. Een momentopname kan absolute- en weekly-vensters combineren. Laat het veld weg om de opgeslagen momentopname ongewijzigd te laten; stuur [] om elk venster van deze bron in te trekken.

• access_time_windows_revision integer verplicht met access_time_windows

  Een monotoon oplopend, niet-negatief JSON-veilig geheel getal voor de revisiereeks van dit lid/deze bron. Het is verplicht wanneer access_time_windows aanwezig is en mag niet groter zijn dan 9007199254740991.

Elke momentopname accepteert maximaal 50 vensters. external_id, scope_key en label accepteren maximaal 120 tekens. Absolute vensters kunnen maximaal 90 dagen beslaan. Een weekdag accepteert maximaal acht niet-overlappende blokken. Ongeldige gegevens worden geweigerd in plaats van ingekort of geraden.

Vormen van vensters

Een absoluut venster geeft één exact interval aan:

Volledig gecombineerd verzoek

Dit verzoek vervangt de vorige momentopname van de bron voor het lid door één absoluut en één wekelijks venster:

Regels voor tijden en grenzen

from, to, active_from en active_until zijn JSON-gehele getallen in Unix-seconden die UTC-tijdstippen aangeven:

• Stuur een JSON-geheel getal zonder aanhalingstekens. Numerieke tekenreeksen, drijvendekommagetallen, RFC 3339-tekenreeksen en Unix-milliseconden worden geweigerd.
• Elk interval is halfopen: [from, to). Toegang kan precies op from beginnen; precies op to is die niet meer actief.
• from moet kleiner zijn dan to. Als beide wekelijkse grenzen aanwezig zijn, moet active_from kleiner zijn dan active_until.
• Leid epochs niet af van een lokale datum/tijd zonder tijdzone. Zet de brontijd eerst om naar een UTC-tijdstip, deel daarna de Unix-milliseconden door 1000 en controleer of het resultaat een geheel getal is.

Tijdzones en zomertijd

timezone moet een geldige IANA-tijdzone zijn, zoals UTC, Australia/Perth of America/New_York. Als dit veld wordt weggelaten, is de standaardwaarde UTC.

• Absolute vensters: from en to geven al exacte UTC-tijdstippen aan. timezone is alleen metadata voor weergave en audit; een wijziging ervan verschuift geen van beide tijdstippen.
• Wekelijkse vensters: timezone bepaalt de lokale kloktijd en de zomertijdregels waarmee access_hours wordt geëvalueerd. Zet wekelijkse blokken niet vooraf om naar UTC.
• Bij de overgang naar zomertijd komt een lokale tijd die de tijdzone overslaat nooit voor.
• Bij de overgang naar wintertijd vallen beide echte tijdstippen met de herhaalde lokale tijd binnen het wekelijkse blok.
• active_from en active_until blijven UTC-tijdstippen, ook wanneer een wekelijks venster een andere tijdzone dan UTC gebruikt.

access_hours gebruikt sun tot en met sat in kleine letters. Elke waarde is een array van [start, end]-paren in 24-uursnotatie HH:mm met voorloopnullen. Blokken mogen niet leeg zijn, moeten op volgorde staan en mogen niet overlappen. end is exclusief. Een blok kan niet over middernacht heen lopen; splits een nachtelijk broninterval in een laat blok op de eerste dag en een vroeg blok op de volgende dag.

Stabiele ID's en scopetoewijzing

external_id moet stabiel zijn gedurende de levensduur van een logisch venster en uniek binnen de momentopname van het lid. Houd het stabiel wanneer tijden of labels veranderen, zodat beheerders en auditrecords revisies aan elkaar kunnen koppelen. Gebruik het niet opnieuw voor een venster dat er niets mee te maken heeft.

scope_key is je stabiele logische toegangsdoel. De standaardwaarde is default. Een beheerder van de faciliteit wijst elke toegestane sleutel toe aan doelen in Performance Hub: de hele faciliteit, een deur of een Toegangsbereik:

Volledige momentopnamen en revisies

Behandel de twee velden als een afzonderlijk geversioneerde partitie binnen de upsert van een lid:

Een momentopname is volledig, geen patch. Als revisie 1842 de vensters A en B bevat, verwijdert revisie 1843 met alleen B het venster A.

Houd per partner/lid één gecoördineerde revisiereeks bij over webhookworkers, polling, herhaling en volledige reconciliatie heen. Een duurzame databasesequentie heeft de voorkeur. Een waarde in Unix-milliseconden kan alleen als revisie worden gebruikt wanneer alle schrijvers zich coördineren en een strikte volgorde en uniciteit garanderen; het is een revisiewaarde, geen epochveld.

Bewaar het exacte verzoek en de revisie totdat de API-response bekend is. Probeer na een time-out of tijdelijke fout dezelfde genormaliseerde momentopname opnieuw met dezelfde revisie. Ken geen nieuwe revisie toe alleen omdat de aflevering onzeker is.

Annulering, verloop en upstream fouten

• Eén venster annuleren: haal met succes de gezaghebbende status bij de bron op, verwijder dat venster en stuur de resterende volledige momentopname met een nieuwere revisie.
• Alle vensters annuleren: stuur access_time_windows: [] met een nieuwere revisie.
• Een absoluut venster laten verlopen: het staat vanaf to geen toegang meer toe; stuur later een reconciliatie zonder het verlopen item om momentopnamen schoon te houden.
• Een wekelijks venster beëindigen: verwijder het in een nieuwere momentopname, of gebruik active_until wanneer de bron een bekend eindtijdstip heeft.
• Ophalen bij de bron mislukt of is onvolledig: stuur geen [] en publiceer geen gedeeltelijke momentopname. Geef een waarschuwing en probeer het ophalen opnieuw. Een upstream fout omzetten in een lege momentopname betekent een onbedoelde intrekking van toegang.
• Verzoek aan de Partner API mislukt bij validatie: corrigeer de gegevens en stuur alleen een nieuwere revisie als de genormaliseerde momentopname verandert. Probeer tijdelijke fouten opnieuw met de oorspronkelijke revisie.

De actualiteit van de bron wordt per integratie geconfigureerd op basis van de toegezegde frequentie van aflevering en reconciliatie. Spreek vóór activering af wat de maximale leeftijd van de brongegevens is, wat er gebeurt als die wordt overschreden, wat de drempels voor waarschuwingen zijn en of beheerders mogen bevestigen dat alleen op de eigen grenzen van elk venster wordt vertrouwd. Een verouderd bronvenster wordt nooit een weigeringsregel; reguliere regels en permanente toegangsrechten blijven terugvalroutes.

Algoritme voor producenten

Gebruik dit taalonafhankelijke proces voor elke update van een lid:

Certificeringschecklist

Voer deze controles uit in een testfaciliteit met de definitieve scope_key-toewijzing:

• Een absoluut venster zonder tijdzone wordt geaccepteerd en als UTC geëvalueerd.
• Een absoluut venster met een aangepaste IANA-tijdzone behoudt dezelfde from/to-tijdstippen.
• Een wekelijks venster met een aangepaste IANA-tijdzone volgt de lokale kloktijd bij de overgangen naar zomer- en wintertijd.
• Een gecombineerde absolute/wekelijkse momentopname vervangt de vorige momentopname volledig.
• Toegang begint precies op from en stopt precies op to; de einden van wekelijkse blokken zijn ook exclusief.
• Het bijwerken van tijden onder dezelfde external_id met een nieuwere revisie wordt van kracht.
• Het weglaten van access_time_windows wijzigt andere velden van het lid zonder de vensters te wijzigen.
• Het herhalen van dezelfde revisie/payload is idempotent.
• Dezelfde revisie met een andere payload geeft een conflict en wijzigt de momentopname niet.
• Een oudere revisie die in de verkeerde volgorde binnenkomt, wordt als verouderd gemeld en kan de status niet terugdraaien.
• Een nieuwere [] trekt de vensters van de bron in; bij een mislukte upstream ophaalactie wordt niets verzonden.
• Een onbekende of niet-toegewezen scope_key leidt tot weigering (fail-closed) en geeft een waarschuwing die beheerders kunnen zien.
• Waarschuwingen over de leeftijd van brongegevens en het geconfigureerde beleid voor verouderde bronnen werken bij de afgesproken drempel.
• De webhookroute en de route voor volledige reconciliatie komen uit op dezelfde momentopname en revisievolgorde.
• Aflevering van de reeks bereikt Door & Gate Access binnen het afgesproken doel.
• Een actief venster kan toegang geven tot de toegewezen fysieke deur, maar kan het uitschakelen van gebruikers, blockAllAccess, onderhoud of geofencing niet omzeilen.
• Vóór, buiten en na een venster geven reguliere regels en permanente toegangsrechten nog steeds toegang aan gebruikers die daar anders recht op hebben.

Gerelateerde richtlijnen

• Het Member-object
• Een lid opslaan
• Best practices
• Fouten
• Checklist voor livegang

Een lid opslaan

Maakt ledenrecords aan of werkt ze bij. De API bepaalt op basis van member_id of een record wordt aangemaakt of bijgewerkt.

Parameters

• members array verplicht

  Array van Member-objecten om op te slaan. Aanbevolen maximum: 1000 items per verzoek voor optimale prestaties. De API verdeelt items automatisch in batches voor verwerking. Elk item moet facility_id (verplicht als je linking_identifier niet gebruikt) of linking_identifier (verplicht als je facility_id niet gebruikt) bevatten.

  Wanneer een lid access_time_windows bevat, moet het ook access_time_windows_revision bevatten. De array is een volledige momentopname van de bron, geen patch. Laat de array weg om de bestaande momentopname te behouden, of stuur [] met een nieuwere revisie om alle vensters van de bron in te trekken. Lees de handleiding voor Access Time Windows voordat je dit veld inschakelt.

Retourwaarde

Retourneert een eenvoudig bericht dat de synchronisatie bevestigt.

Profielvelden van leden blijven gewone upserts, ook wanneer een momentopname van vensters wordt gemeld als idempotente herhaling of als verouderd en overgeslagen. Een conflicterende momentopname met dezelfde revisie en een andere payload kan niet ongewijzigd opnieuw worden geprobeerd; reconcilieer de status bij de bron en stuur een nieuwere revisie.

Check-ins

Vertegenwoordigt een registratie van de aanwezigheid van een persoon in een faciliteit, les of activiteit. Wordt gebruikt om aanwezigheid bij te houden, gebruiksanalyses te maken en de nauwkeurigheid van visuele detectie te verbeteren.

Het Check-In-object

Attributen

• check_in_id string optioneel

  Unieke identificatie van de check-in. Optioneel: wordt automatisch gegenereerd uit het paar member_id en timestamp als dit niet wordt opgegeven.

• member_id string verplicht

  Unieke identificatie van het lid.

• facility_id string een van beideGeef het type faciliteitidentificatie op dat voor je integratie is geconfigureerd: gebruik facility_id voor integraties met Direct Link of linking_identifier voor integraties met een Linking Identifier. Stuur ze niet allebei: de API gebruikt het identificatietype dat voor je partneraccount is geconfigureerd en negeert het andere. Meer informatie

  Unieke identificatie van de faciliteit uit Performance Hub.

• linking_identifier string een van beideGeef het type faciliteitidentificatie op dat voor je integratie is geconfigureerd: gebruik facility_id voor integraties met Direct Link of linking_identifier voor integraties met een Linking Identifier. Stuur ze niet allebei: de API gebruikt het identificatietype dat voor je partneraccount is geconfigureerd en negeert het andere. Meer informatie

  Unieke identificatiewaarde die de partner voor elke locatie gebruikt (bijvoorbeeld "Branch ID", "Location Code", "Store Number"). Meer informatie

• check_in_type string optioneel

  Type bezoek. Een van member, class, staff, guest of trial.

• source string optioneel

  Hoe de check-in is vastgelegd. Veelvoorkomende waarden zijn manual, tag, rfid, kiosk en app. Aanvullende waarden zoals door_reader of booking kunnen ook worden gebruikt.

• class_id string optioneel

  Optioneel. Als de check-in aan een lesboeking of lesaanwezigheid is gekoppeld.

• timestamp string verplicht

  Tijdstempel in ISO 8601-notatie van het moment waarop de check-in plaatsvond.

Check-ins opslaan

Maakt check-inrecords aan. De API ontdubbelt automatisch op basis van lid, faciliteit en tijdstempel.

Parameters

• check_ins array verplicht

  Array van Check-In-objecten om op te slaan. Aanbevolen maximum: 1000 items per verzoek voor optimale prestaties. De API verdeelt items automatisch in batches voor verwerking. Elk item moet facility_id (verplicht als je linking_identifier niet gebruikt) of linking_identifier (verplicht als je facility_id niet gebruikt) bevatten.

Retourwaarde

Retourneert een eenvoudig bericht dat de synchronisatie bevestigt.

Toegangsbeheer

De Partner API kan de hardware van de Performance Hub Door/Gate Controller aansturen voor faciliteiten waar je integratie is ingeschakeld.

Gebruik deze API wanneer je ledenbeheersysteem al heeft bepaald dat iemand naar binnen mag. Performance Hub beoordeelt geen lidmaatschapsstatus, toegangsuren, regels voor deurzones, fraudecontroles of opschortingslogica. Jouw systeem blijft verantwoordelijk voor die beslissingen.

Het ontgrendelverzoek is synchroon. Performance Hub stuurt de opdracht in realtime naar de controller ter plaatse en retourneert pas 200 nadat het apparaat heeft bevestigd dat het relais fysiek is ontgrendeld. De meeste bevestigingen zijn binnen 3-5 seconden binnen. Als er binnen de time-outperiode geen bevestiging wordt ontvangen, retourneert de API een expliciete fout.

Je kunt ook een toegangspoging of weigering vastleggen die de controller nooit heeft bereikt. Die aanroep ontgrendelt de deur niet. Er wordt een gebeurtenis geschreven naar de Toegangslogboeken van Door & Gate Access.

Het Door/Gate Controller-object

Attributen

• door_id string verplicht

  Unieke identificatie van de Door/Gate Controller. Sla deze na het opvragen op in je systeem en gebruik deze bij het aanroepen van het unlock-endpoint.

• facility_id string verplicht

  Faciliteit-ID in Performance Hub.

• linking_identifier string optioneel

  Faciliteitidentificatie van de partner wanneer je integratie Linking Identifiers gebruikt. Meer informatie

• name string verplicht

  Leesbare apparaatnaam die in Performance Hub is geconfigureerd.

• zone string optioneel

  Deurzone of locatie, zoals Entrance.

• status string verplicht

  online of offline.

• relay_state string optioneel

  Laatst bekende status van het relais, zoals locked of unlocked.

• maintenance_mode string verplicht

  Huidige onderhoudsmodus. Een van off, force-open of force-closed.

• hold_time_seconds integer verplicht

  Standaard openhoudtijd na ontgrendeling die voor de deur is geconfigureerd.

• last_seen string optioneel

  ISO-tijdstempel van de meest recente update van de apparaatmetadata.

Door/Gate Controllers opvragen

Retourneert de Door/Gate Controllers die voor je integratie beschikbaar zijn.

Als je facility_id noch linking_identifier opgeeft, retourneert de API de Door/Gate Controllers van alle faciliteiten die aan je partneraccount zijn gekoppeld.

Parameters

• facility_id string optioneel een van beideGeef het type faciliteitidentificatie op dat voor je integratie is geconfigureerd: gebruik facility_id voor integraties met Direct Link of linking_identifier voor integraties met een Linking Identifier. Stuur ze niet allebei: de API gebruikt het identificatietype dat voor je partneraccount is geconfigureerd en negeert het andere. Meer informatie

  Faciliteit-ID in Performance Hub. Gebruik dit voor integraties met Direct Link.

• linking_identifier string optioneel een van beideGeef het type faciliteitidentificatie op dat voor je integratie is geconfigureerd: gebruik facility_id voor integraties met Direct Link of linking_identifier voor integraties met een Linking Identifier. Stuur ze niet allebei: de API gebruikt het identificatietype dat voor je partneraccount is geconfigureerd en negeert het andere. Meer informatie

  Je eigen identificatie van de faciliteit/locatie. Gebruik dit wanneer je integratie is geconfigureerd voor Linking Identifiers.

Retourwaarde

Retourneert een array van Door/Gate Controller-objecten.

Status van een Door/Gate Controller opvragen

Haalt de laatst bekende status en de basisconfiguratie van één Door/Gate Controller op.

Geef een faciliteitidentificatie op, zodat Performance Hub kan controleren of de deur hoort bij een faciliteit waartoe je integratie toegang heeft.

Parameters

• door_id string verplicht

  ID van de Door/Gate Controller dat door het list-endpoint wordt geretourneerd.

• facility_id string een van beideGeef het type faciliteitidentificatie op dat voor je integratie is geconfigureerd: gebruik facility_id voor integraties met Direct Link of linking_identifier voor integraties met een Linking Identifier. Stuur ze niet allebei: de API gebruikt het identificatietype dat voor je partneraccount is geconfigureerd en negeert het andere. Meer informatie

  Faciliteit-ID in Performance Hub. Verplicht voor integraties met Direct Link.

• linking_identifier string een van beideGeef het type faciliteitidentificatie op dat voor je integratie is geconfigureerd: gebruik facility_id voor integraties met Direct Link of linking_identifier voor integraties met een Linking Identifier. Stuur ze niet allebei: de API gebruikt het identificatietype dat voor je partneraccount is geconfigureerd en negeert het andere. Meer informatie

  Faciliteitidentificatie van de partner. Verplicht voor integraties met een Linking Identifier.

Retourwaarde

Retourneert een Door/Gate Controller-object.

Een Door/Gate Controller ontgrendelen

Stuurt een ontgrendelopdracht naar de Door/Gate Controller en wacht tot het fysieke relais bevestigt dat het is ontgrendeld.

Je systeem moet beslissen of de persoon toegang heeft voordat dit endpoint wordt aangeroepen. Performance Hub controleert alleen de partnersleutel, de toegang tot de faciliteit, het eigendom van de deur en de status van het apparaat.

Parameters

• door_id string verplicht

  ID van de Door/Gate Controller dat door het list-endpoint wordt geretourneerd.

• facility_id string een van beideGeef het type faciliteitidentificatie op dat voor je integratie is geconfigureerd: gebruik facility_id voor integraties met Direct Link of linking_identifier voor integraties met een Linking Identifier. Stuur ze niet allebei: de API gebruikt het identificatietype dat voor je partneraccount is geconfigureerd en negeert het andere. Meer informatie

  Faciliteit-ID in Performance Hub. Verplicht voor integraties met Direct Link.

• linking_identifier string een van beideGeef het type faciliteitidentificatie op dat voor je integratie is geconfigureerd: gebruik facility_id voor integraties met Direct Link of linking_identifier voor integraties met een Linking Identifier. Stuur ze niet allebei: de API gebruikt het identificatietype dat voor je partneraccount is geconfigureerd en negeert het andere. Meer informatie

  Faciliteitidentificatie van de partner. Verplicht voor integraties met een Linking Identifier.

• member_id string verplicht

  Lid-ID van de partner. Wordt gebruikt voor auditlogboeken en latere koppeling van gegevens.

• first_name string verplicht

  Voornaam van de persoon die de deur opent.

• last_name string verplicht

  Achternaam van de persoon die de deur opent.

• full_name string optioneel

  Optioneel. Als dit wordt weggelaten, combineert Performance Hub first_name en last_name.

• check_in_id string optioneel

  Optioneel check-in-ID uit je systeem om gegevens aan elkaar te koppelen.

• idempotency_key string optioneel

  Optionele sleutel ter bescherming tegen herhaling. Als je dezelfde sleutel opnieuw gebruikt voor dezelfde partner, faciliteit en deur, wordt het bestaande resultaat geretourneerd wanneer dat beschikbaar is.

Retourwaarde

Retourneert alleen 200 wanneer het apparaat bevestigt dat het relais fysiek is ontgrendeld. De deur gebruikt de openhoudtijd die in Apparaatbeheer van Performance Hub is geconfigureerd; partners kunnen de relaistiming niet per verzoek overschrijven. De meeste bevestigingen zijn binnen 3-5 seconden binnen. Behandel de gedocumenteerde time-out als een expliciet mislukte ontgrendeling en probeer het alleen opnieuw volgens je eigen veiligheidsregels.

Veelvoorkomende fouten:

• 403 integration_not_enabled - je integratie is niet ingeschakeld voor de faciliteit.
• 409 maintenance_mode_active - medewerkers van de faciliteit hebben de onderhoudsmodus voor de deur ingeschakeld.
• 503 device_offline - de Door/Gate Controller is offline of niet actueel.
• 504 unlock_confirmation_timeout - de opdracht is verzonden, maar er is vóór de time-out geen bijbehorende bevestiging ontvangen.

Een toegangspoging of weigering vastleggen

Legt een toegangspoging of weigering vast waarover je systeem al heeft beslist. Er wordt geen contact gemaakt met de Door/Gate Controller en de deur wordt niet ontgrendeld.

Gebruik dit wanneer je systeem de toegang weigert, of wanneer een poging zonder ontgrendeling in de Toegangslogboeken van Door & Gate Access moet verschijnen. Performance Hub beoordeelt geen lidmaatschapsstatus, toegangsuren of andere toegangsregels.

Een geweigerde gebeurtenis verschijnt in de Toegangslogboeken van Door & Gate Access met de uitkomst Denied, je partnernaam, de deur, de identificatie van het lid als je die meestuurt en de redencode in leesbare vorm. membership_expired wordt bijvoorbeeld weergegeven als "Membership Expired". reason_display_text en user_email worden bij de gebeurtenis opgeslagen.

Parameters

• door_id string verplicht

  ID van de Door/Gate Controller dat door het list-endpoint wordt geretourneerd.

• facility_id string een van beideGeef het type faciliteitidentificatie op dat voor je integratie is geconfigureerd: gebruik facility_id voor integraties met Direct Link of linking_identifier voor integraties met een Linking Identifier. Stuur ze niet allebei: de API gebruikt het identificatietype dat voor je partneraccount is geconfigureerd en negeert het andere. Meer informatie

  Faciliteit-ID in Performance Hub. Verplicht voor integraties met Direct Link.

• linking_identifier string een van beideGeef het type faciliteitidentificatie op dat voor je integratie is geconfigureerd: gebruik facility_id voor integraties met Direct Link of linking_identifier voor integraties met een Linking Identifier. Stuur ze niet allebei: de API gebruikt het identificatietype dat voor je partneraccount is geconfigureerd en negeert het andere. Meer informatie

  Faciliteitidentificatie van de partner. Verplicht voor integraties met een Linking Identifier.

• outcome string verplicht

  denied of attempted.

• reason string optioneel

  Redencode in snake_case met kleine letters, maximaal 64 tekens. Verplicht wanneer outcome denied is. Voorbeeld: membership_expired.

• reason_display_text string optioneel

  Leesbare reden, maximaal 256 tekens. Voorbeeld: Membership expired on 2026-04-01.

• member_id string optioneel

  Lid-ID van de partner. Laat dit weg wanneer de inloggegevens niet bij een lid hoorden, zoals bij een onbekende kaart.

• user_email string optioneel

  E-mailadres van de persoon die toegang probeerde te krijgen.

• timestamp string optioneel

  Wanneer de poging plaatsvond, als ISO 8601 met een tijdzone. Voorbeeld: 2026-05-18T10:15:30Z. Standaard het tijdstip waarop het verzoek wordt ontvangen. Mag niet meer dan 5 minuten in de toekomst liggen of ouder zijn dan 30 dagen.

• idempotency_key string optioneel

  Sleutel ter bescherming tegen herhaling, maximaal 128 tekens. Als je dezelfde sleutel opnieuw gebruikt voor dezelfde partner, faciliteit en deur, wordt het oorspronkelijke resultaat geretourneerd.

Retourwaarde

Retourneert 201 wanneer de gebeurtenis is vastgelegd. Een herhaling met dezelfde idempotency_key retourneert 200 met idempotent ingesteld op true en maakt geen nieuwe gebeurtenis aan.

Een dry-run-sleutel retourneert 200 met dry_run ingesteld op true. Er wordt niets vastgelegd.

Veelvoorkomende fouten:

• 400 - de body is ongeldig, een weigering heeft geen reason, de tijdstempel valt buiten het toegestane bereik, of facility_id / linking_identifier komt niet overeen met een gekoppelde faciliteit.
• 403 - de sleutel is read-only.
• 403 integration_not_enabled - je integratie is niet ingeschakeld voor de faciliteit. message geeft de reden.
• 404 - de Door/Gate Controller is niet gevonden voor de gekoppelde faciliteit.

Faciliteitrapporten

Een momentopname met de belangrijkste operationele en financiële metrics van een faciliteit gedurende een specifieke periode.

Het Report Snapshot-object

Attributen

• facility_id string een van beideGeef het type faciliteitidentificatie op dat voor je integratie is geconfigureerd: gebruik facility_id voor integraties met Direct Link of linking_identifier voor integraties met een Linking Identifier. Stuur ze niet allebei: de API gebruikt het identificatietype dat voor je partneraccount is geconfigureerd en negeert het andere. Meer informatie

  Unieke identificatie van de faciliteit uit Performance Hub.

• linking_identifier string een van beideGeef het type faciliteitidentificatie op dat voor je integratie is geconfigureerd: gebruik facility_id voor integraties met Direct Link of linking_identifier voor integraties met een Linking Identifier. Stuur ze niet allebei: de API gebruikt het identificatietype dat voor je partneraccount is geconfigureerd en negeert het andere. Meer informatie

  Unieke identificatiewaarde die de partner voor elke locatie gebruikt (bijvoorbeeld "Branch ID", "Location Code", "Store Number"). Meer informatie

• start_date string verplicht

  Begindatum van de periode van de momentopname in de notatie YYYY-MM-DD.

• end_date string verplicht

  Einddatum van de periode van de momentopname in de notatie YYYY-MM-DD.

• metrics object verplicht

  Metrics-object met gegevens over leden en omzet voor de periode.

Rapportmomentopnamen opslaan

Dient operationele en financiële metrics in voor een faciliteit gedurende een specifieke periode.

Parameters

• snapshots array verplicht

  Array van Report Snapshot-objecten om op te slaan. Maximaal 25 items per verzoek. Elk item moet facility_id (verplicht als je linking_identifier niet gebruikt) of linking_identifier (verplicht als je facility_id niet gebruikt) bevatten.

Retourwaarde

Retourneert een eenvoudig bericht dat de synchronisatie bevestigt.

Fouten

De Partner API gebruikt standaard HTTP-statuscodes en JSON-response-bodies om uit te leggen waarom een verzoek is mislukt.

Structuur van foutresponses

De meeste API-fouten retourneren een JSON-body met een bericht en, waar beschikbaar, gestructureerde details.

Statuscodes

Fouten bij Access Time Windows

De validatie van vensters mislukt voordat de ongeldige momentopname wordt weggeschreven. Veelvoorkomende oorzaken waarbij een nieuwe poging geen zin heeft:

• access_time_windows_revision ontbreekt terwijl access_time_windows aanwezig is.
• Epochwaarden als tekenreeks, als drijvendekommagetal of vermoedelijk in milliseconden.
• Een ongeldige IANA-tijdzone, een omgekeerd interval, een dubbele external_id, overlappende wekelijkse blokken of een nachtelijk blok dat niet is gesplitst.
• Een waarde buiten de gedocumenteerde limieten voor aantal, lengte of tijdsspanne.

Een herhaalde revisie met andere genormaliseerde inhoud levert een 409 Conflict op. Stem af op de meest recente gezaghebbende status en ken een nieuwere revisie toe; blijf het conflicterende paar niet opnieuw proberen. Een oudere revisie wordt gemeld als een verouderde, overgeslagen momentopname en mag een nieuwere status niet overschrijven. Een onbekende of niet-toegewezen scope_key leidt bij autorisatie tot weigering (fail-closed) en moet worden behandeld als een configuratiewaarschuwing.

Als de levering een time-out krijgt of een tijdelijke 5xx ontvangt, probeer dan exact dezelfde genormaliseerde momentopname opnieuw met dezelfde revisie. Als het ophalen bij de upstream bron is mislukt, laat het vensterveld dan helemaal weg; vervang het nooit door een lege array.

Richtlijnen voor nieuwe pogingen

Probeer deze opnieuw met begrensde exponentiële backoff:

• 429
• 500
• 502
• 503
• 504

Probeer deze niet blindelings opnieuw:

• 400
• 401
• 403
• 404
• 409
• 422

Behandel bij toegangsbeheer time-out- en offline-responses altijd als mislukte ontgrendelingen, tenzij je eigen toegangsregels en veiligheidsprocessen anders voorschrijven.

Gegevens voor ondersteuning

Vermeld het volgende wanneer je contact opneemt met ondersteuning:

• Endpoint en HTTP-methode.
• Tijdstempel en tijdzone.
• Partnersleutel-ID, niet de geheime sleutel.
• Gebruikte faciliteitidentificatie.
• Bronrecord-ID uit je systeem.
• Status en body van de response.
• event_id of command_id, indien beschikbaar.

Versiebeheer

De versie van de Partner API staat in de URL. De huidige versie is:

Wijzigingsbeleid

Performance Hub streeft ernaar om waar mogelijk aanvullende, achterwaarts compatibele wijzigingen door te voeren.

Voorbeelden van achterwaarts compatibele wijzigingen:

• Een nieuw optioneel veld aan een verzoek toevoegen.
• Een nieuw veld aan een response toevoegen.
• Een nieuw endpoint toevoegen.
• Een nieuwe enumwaarde toevoegen waar van clients wordt verwacht dat ze onbekende waarden afhandelen.
• Validatieberichten verbeteren zonder het contract voor statuscodes te wijzigen.

access_time_windows en access_time_windows_revision zijn aanvullende velden in Member-verzoeken. Bestaande clients die ze weglaten, laten de opgeslagen momentopname van Access Time Windows ongewijzigd. Deze regel voor weglaten behoudt de compatibiliteit met gedeeltelijke upserts; weglaten is niet hetzelfde als een lege array sturen.

Voorbeelden van wijzigingen die compatibiliteit verbreken:

• Een veld verwijderen of hernoemen.
• Het type van een veld wijzigen.
• Een optioneel veld in een verzoek verplicht maken.
• Een endpoint verwijderen.
• De betekenis van een bestaande statuscode of domeinspecifieke reason wijzigen.

Uitfasering

Wanneer een wijziging nodig is die compatibiliteit verbreekt, vermijdt Performance Hub waar mogelijk om de bestaande versie ter plekke te wijzigen. In plaats daarvan introduceren we een nieuwe versie of een migratiepad en communiceren we de wijziging aan de betrokken partners.

Meldingen over uitfasering kunnen bestaan uit:

• Een vermelding in het wijzigingslogboek.
• Directe communicatie met partners.
• Opmerkingen in de Partner Console.
• Migratierichtlijnen in de documentatie.

Aanbevelingen voor clients

Bouw clients die bestand zijn tegen aanvullende wijzigingen:

• Negeer responsevelden die je niet gebruikt.
• Behandel onbekende enumwaarden als niet-ondersteund in plaats van te crashen.
• Vermijd strikte gelijkheidscontroles op responses.
• Log onbekende waarden, zodat je je integratie bewust kunt bijwerken.

Bewaar voor Member-partities met revisies, zoals Access Time Windows, de ingediende revisie en de genormaliseerde payload totdat de uitkomst bekend is. Een revisie hergebruiken voor gewijzigde inhoud is een conflict, terwijl het herhalen van dezelfde inhoud idempotent is. Zie Access Time Windows.

OpenAPI-specificaties

Gebruik de gepubliceerde OpenAPI-specificaties om clients te genereren, verzoeken te valideren en wijzigingen in de structuur van de API in de loop van de tijd te volgen.

Zie OpenAPI-specificaties.

Wijzigingslogboek

In dit wijzigingslogboek staan belangrijke wijzigingen in de Partner API en de Partner Console die van invloed zijn op het gedrag van integraties.

2026-09-09

2026-05-06

2026-05-01

Wijzigingscategorieën

Toekomstige vermeldingen gebruiken deze categorieën:

• Toegevoegd - nieuw endpoint, veld, nieuwe handleiding of functionaliteit.
• Gewijzigd - gedrag of documentatie gewijzigd zonder dat ondersteuning vervalt.
• Verouderd - functie blijft beschikbaar, maar er is een migratiepad gepland.
• Verwijderd - functie of endpoint verwijderd.
• Opgelost - bugfix of correctie in de documentatie.
• Beveiliging - wijziging in authenticatie, autorisatie, gegevensverwerking of sleutelbeheer.