Als je een eigen abonnementenbeheersysteem en/of administratiesysteem hebt, biedt Bizplay een aantal manieren om daarmee te integreren. In deze sectie beschrijven we de belangrijkste integratiemechanismen. In de subsecties doorlopen we de verschillende stadia/processen in een klantlevenscyclus en beschrijven we hoe je dit het beste kunt ondersteunen met het specifieke integratiepunt.
De volgende manieren van communicatie met een extern administratiesysteem worden ondersteund:
De configuraties van de eerste twee integraties vindt je in het gedeelte Integraties van je reselleromgeving.
Om ervoor te zorgen dat een extern systeem en Bizplay naadloos met elkaar communiceren, is het aan te raden om een intermediair systeem te gebruiken dat zorgt voor de communicatie tussen de systemen en de vertalingen van de verschillende datastructuren. Een optie is om hiervoor Amazon AWS API Gateway te gebruiken.
Wanneer er een abonnementsgerelateerde verandering plaatsvindt in Bizplay, kun je een webhook gebruiken om de bijgewerkte informatie naar het externe systeem te sturen, zodat Bizplay en je externe administratiesysteem synchroon blijven en je de juiste actie kunt ondernemen, zoals de klant factureren voor de nieuwe sitatie.
In de sectie Integraties kun je een nieuwe webhook toevoegen. Je configureert deze door de volgende eigenschappen in te vullen:
| Eigenschap | Uitleg |
|---|---|
| Omschrijving | Een beschrijving naar keuze, bijvoorbeeld "Systeem X integratie". |
| Doel-URL | De URL waar een webhook request naartoe wordt gestuurd. Dit wordt in meer detail beschreven in de paragraaf hieronder. |
| HTTP-methode | De methode die wordt gebruikt om de webhook HTTP request te versturen. Over het algemeen zal dit een POST methode zijn. |
| Acties | Selecteer alle acties die in Bizplay kunnen gebeuren en waarvan je wilt dat je externe systeem een update ontvangt. Bijvoorbeeld customer.updated stuurt de nieuwe klantgegevens als de klantgegevens in Bizplay zijn bijgewerkt. |
| Optioneel e-mailadres voor notificatie | Je kunt de webhook triggers die naar je externe systeem worden gestuurd actief volgen door je e-mailadres in te vullen. Het systeem stuurt je dan een e-mail wanneer een webhook-trigger wordt verzonden en ook wanneer er een mislukt na drie keer proberen. Op die manier kun je handmatig actie ondernemen als je merkt dat er iets mis is gegaan bij de aflevering van de webhook. |
| Notificatie alleen bij fouten | Vink dit vakje aan als je alleen een e-mail wilt ontvangen als een webhook aflevering mislukt. |
| Ingeschakeld | Gebruik dit om de webhook te activeren of deactiveren. Als hij inactief is, wordt deze webhook niet getriggert in geval van wijzigingen in Bizplay. |
Het kan goed zijn dat je administratiesysteem voor elk type wijziging een andere URL vereist. In dat geval maak je een webhook voor elk van de "acties" waarmee je wilt synchroniseren. Bijvoorbeeld, de customer.updated actie zou een POST verzoek naar https://your.system.com/company/123 kunnen vereisen, terwijl de subscription.canceled actie een POST verzoek naar https://your.system.com/package/123/cancel zou kunnen vereisen. Omdat beide URL's nogal verschillend zijn, is een aparte webhook voor elk van hen (één voor elke specifieke actie) noodzakelijk.
De kans is echter groot dat je beheersysteem de gegevens in een ander formaat moet ontvangen dan Bizplay levert. In dat geval is het zinvol om een systeem tussen Bizplay en je administratiesysteem te plaatsen dat:
Amazon's API Gateway is een voorbeeld van een systeem waarmee dit kan worden gedaan. We helpen je graag om dit op te zetten.
In dit scenario kunnen we een generieke API maken die overeenkomt met de exacte actienamen uit Bizplay, bijvoorbeeld customer.updated gebruikt https://intermediate.system.com/customer/updated en subscription.canceled gebruikt https://intermediate.system.com/subscription/canceled. Omdat de URL overeenkomt met de actienaam, kunnen we de volgende "variabelen" gebruiken in de doel-URL, die worden vervangen door de juiste gegevens wanneer de webhook wordt geactiveerd:
{object}}: verwijst naar het eerste deel van de actienaam (bijvoorbeeld customer of subscription){action}}: verwijst naar het tweede deel van de actienaam (bijv. created of canceled){{id}}: verwijst naar de id van het onderwerp van de wijzigingMet behulp van deze variabelen zou een doel-URL er dan als volgt uit kunnen zien: https://intermediate.system.com/{{object}}/{{action}}/{{id}}.
Om te voorkomen dat zomaar elk systeem een wijzigingsmelding naar je beheersysteem kan sturen, wordt bij elk verzoek een geheime sleutel meegestuurd in een header met de naam X-Bizplay-Secret. Elke webhook heeft een unieke sleutel. Deze kun je vinden op de webhook detailpagina. Aan de ontvangende kant van het webhook-verzoek (bijvoorbeeld in het intermediaire systeem) moet je controleren of de doorgegeven sleutel correct is voordat je het verzoek verwerkt.
Op de detailpagina van een webhook zie je ook een lijst met webhook request die zijn verzonden, samen met hun status. De status kan zijn:
Op dit moment ondersteunt Bizplay het ophalen van de volgende twee soorten informatie:
In de sectie Integraties kun je een nieuwe externe gegevensbron toevoegen. Je configureert deze door de volgende eigenschappen in te vullen:
| Eigenschap | Uitleg |
|---|---|
| Omschrijving | Een beschrijving naar keuze, bijvoorbeeld "Systeem X integratie". |
| Doel-URL | De URL waar de externe data opgehaald kan worden. Zie de Doel URL sectie in de paragraaf hierboven voor opties om deze URL te configureren. |
| HTTP-methode | De methode die wordt gebruikt om het HTTP request te versturen. Over het algemeen zal dit een GET methode zijn. |
| Acties | Selecteer de acties waarvoor je de externe gegevens wilt ophalen. Dit kunnen invoices.list en customer.get zijn. |
| Ingeschakeld | Gebruik dit om het ophalen van externe gegevens te activeren of deactiveren. |
In Bizplay heeft elke geconfigureerde gegevensbronactie een ander effect.
| Actie | Afhandeling |
|---|---|
invoices.list |
Als deze actie is geconfigureerd, krijgen je klanten een knop Facturen op hun pagina met bedrijfsgegevens in het abonnement-gedeelte. Als de gebruiker daarop klikt, worden de facturen onmiddellijk opgehaald uit je administratiesysteem en gepresenteerd in een lijst, met links naar de facturen in je administratiesysteem. Deze lijst wordt 5 minuten gebufferd. |
customer.get |
Wanneer de Facturatiecontact ID van een klant wordt gewijzigd, worden de klantgegevens op de achtergrond opgehaald. Het kan een minuut of twee duren om dit uit te voeren. Op dit moment wordt alleen de URL voor het wijzigen van de betaalmethode opgehaald. Als die is opgeslagen, krijgt de klant een Betalingswijze wijzigen/aanpassen knop op de pagina met bedrijfsgegevens in het abonnement-gedeelte. |
Bizplay heeft een beperkte API waarmee je systeem direct updates naar Bizplay kan sturen. Momenteel is deze API alleen beschikbaar voor het activeren van een nieuw abonnement. Je roept dit doorgaans aan wanneer jij (of je klant) een nieuw (betaald) abonnement aanmaakt in je administratiesysteem.
Onze API moet worden aangeroepen namens een reguliere Bizplay-gebruiker; in het bijzonder een gebruiker met een reseller beheerdersrol. Klik in de gebruikerslijst op de gebruikersdetails en je ziet de API-sleutel die bij dat gebruikersaccount hoort. Als die er nog niet is, kun je er een aanmaken door op de knop Genereren te klikken. Een gebruiker kan alleen zijn eigen API-sleutel volledig zien. De sleutels van andere gebruikers worden slechts gemaskeerd vertoond. Elk verzoek aan de API moet worden gedaan met een Autorization header die begint met BEARER gevolgd door een spatie en dan de API sleutel, bijvoorbeeld BEARER SdV4iLgAttyK2zytj6Lf3W.