REST API und mandantenbezogenes Scoping

Erfahren Sie, wie die REST API von Booknetic SaaS mandantenbezogen arbeitet, API-Schlüssel nutzt und externe Systeme sicher dem richtigen Mandanten zuordnet.

Version:

SaaS
- Regulär
- SaaS

Kategorien

Wofür dieser REST API ist

Booknetic enthält einen WordPress REST API für die Arbeit mit Booknetic-Daten aus externen Systemen.

In einer normalen Booknetic-Installation ist der REST API unter diesem Namensraum verfügbar:

/wp-json/booknetic/v1/

In Booknetic SaaS, derselbe Booknetic REST API ist mandantenbewusst. Das bedeutet, dass die API-Anfrage eines Mandanten im eigenen Booknetic-Arbeitsbereich dieses Mandanten funktioniert.

Verwenden Sie es, wenn ein Mandant oder sein Entwickler Booknetic mit Systemen wie den folgenden verbinden möchte:

ein internes Dashboard;
eine CRM- oder Kundendatenbank;
ein Reporting-Tool;
ein Zahlungsabgleichstool;
eine benutzerdefinierte Mobil- oder Web-App, die Mandantenbuchungsdaten benötigt.

Die wichtigste Regel ist:

Authentifizieren Sie sich als der Mandant, auf dessen Daten Sie zugreifen möchten. Die API-Antwort ist auf die Daten dieses Mandanten beschränkt.

Informationen zur allgemeinen Mandantenadministratorerfahrung finden Sie unter Referenz zum Mandanten-Admin-Panel. Informationen zur Mandantendatengrenze finden Sie unter Datenisolation und Berechtigungsgrenzen.

Basis URL

Der REST-Namespace ist:

/wp-json/booknetic/v1

Eine vollständige Anfrage sieht also normalerweise so aus:

https://your-domain.com/wp-json/booknetic/v1/appointments

Verwenden Sie in einem SaaS-Setup den Mandanten URL, der dem Mandanten gehört, der die Anfrage stellt.

Mandanten-URLs im Verzeichnismodus

Wenn Ihre Plattform Mandanten-URLs im Verzeichnisstil verwendet, erscheint der Mandant slug nach Ihrer Hauptdomäne:

https://your-domain.com/tenant-slug/

Abhängig davon, wie Ihr SaaS-Routing konfiguriert ist, kann der mandantenbezogene REST URL aus demselben Mandanten-URL-Kontext erstellt werden, zum Beispiel:

https://your-domain.com/tenant-slug/wp-json/booknetic/v1/appointments

Mandanten-URLs im Subdomänenmodus

Wenn Ihre Plattform Mandanten-URLs im Subdomain-Stil verwendet, erscheint der Mandant slug vor Ihrer Hauptdomäne:

https://tenant-slug.your-domain.com/

Der REST URL verwendet dann diese Mandanten-Subdomäne:

https://tenant-slug.your-domain.com/wp-json/booknetic/v1/appointments

Der Subdomain-Modus erfordert DNS und Hosting-Unterstützung. Wenn Sie nicht sicher sind, welchen URL-Stil Ihre Plattform verwendet, lesen Sie diesen Mandanten-URLs und Routing bevor Sie Entwicklern API-URLs geben.

Authentifizierung

Booknetic REST-Anfragen verwenden die WordPress REST-Authentifizierung. Für Server-zu-Server-Integrationen ist die praktische Option WordPress Anwendungskennwort/Basisauthentifizierung.

Die Anfrage sendet einen HTTP Basic Auth-Header unter Verwendung des WordPress-Benutzernamens des Mandantenbenutzers und des Anwendungskennworts dieses Benutzers:

Authorization: Basic base64(username:application-password)
Content-Type: application/json

Mit curl, Sie können dies schreiben als:

curl -u '[email protected]:xxxx xxxx xxxx xxxx xxxx xxxx' \
  'https://tenant-slug.your-domain.com/wp-json/booknetic/v1/appointments?skip=0&limit=20'

Oder wenn Ihr Entwickler den Header manuell erstellen möchte:

curl -H 'Authorization: Basic <base64-tenant-username-and-application-password>' \
  'https://tenant-slug.your-domain.com/wp-json/booknetic/v1/appointments?skip=0&limit=20'

Sicherheit: Verwenden Sie nicht die WordPress-Administratoranmeldeinformationen des SaaS-Inhabers für Mandantenintegrationen. Erstellen Sie Anmeldeinformationen für den Mandantenbenutzer, der Inhaber der Integration ist.

Wie die Scoping-Prozedur pro Mandant funktioniert

Im Klartext funktioniert eine mandantenbezogene REST-Anfrage folgendermaßen:

Der Entwickler sendet eine Anfrage an den Standard-Namespace Booknetic REST:

/wp-json/booknetic/v1/...

Die Anfrage authentifiziert sich als WordPress-Benutzer, der mit einem Mandanten verbunden ist.
Booknetic löst diesen Mandantenkontext auf.
Booknetic liest oder schreibt Daten im Bereich dieses Mandanten.
Die Antwort enthält nur die Daten dieses Mandanten.

Wenn sich Aurora Wellness Studio beispielsweise bei seinem eigenen Mandantenbenutzer authentifiziert und Folgendes aufruft:

GET /wp-json/booknetic/v1/customers

Die Antwort sollte Aurora Wellness Studio-Kunden enthalten, nicht die Kunden eines anderen Mandanten.

Planberechtigungen und Benutzerfunktionen gelten weiterhin. Wenn der Tarif eines Mandanten kein Modul enthält, schlägt ein API-Aufruf für dieses Modul möglicherweise fehl oder gibt keine verwendbaren Daten zurück, selbst wenn die Anmeldeinformationen gültig sind.

Worauf Mandanten über REST API zugreifen können

Der öffentliche REST-Namespace ist für Mandanten-Booknetic-Daten und ausgewählte Booknetic-Modulaktionen vorgesehen.

Zu den allgemeinen Ressourcen für Mandanten gehören:

Ressource	Beispielendpunkt	Notizen
Termine	`GET /appointments`	Listen Sie Termindaten für den aktuellen Mandantenbereich auf.
Termindetails	`GET /appointments/{id}`	Gibt den Termin nur zurück, wenn er zum authentifizierten Bereich gehört und Berechtigungen den Zugriff zulassen.
Terminstatus	`PUT /appointments/{id}/change-status`	Ändert den Terminstatus, wenn der Benutzer die Berechtigung hat.
Kunden	`GET /customers`, `POST /customers`, `PUT /customers/{id}`	Kundenliste/Erstellung/Aktualisierung für den aktuellen Mandantenbereich.
Standorte	`GET /locations`, `POST /locations`, `PUT /locations/{id}`	Der Standortzugriff hängt vom Mandantenplan und den Berechtigungen ab.
Dienstleistungen	`GET /services`, `GET /services/categories`, `GET /services/extras`	Nützlich für Auswahllisten und Dienstsuche.
Staff	`GET /staffs`	Die Route ist `staffs`, nicht `staff`.
Zahlungen	`GET /payments/{appointmentId}`, `PUT /payments/{appointmentId}`	Zahlungsinformationen sind an einen Termin ID gebunden.
Armaturenbrett	`GET /dashboard/stats`, `GET /dashboard/upcoming-appointments`, `GET /dashboard/graph`	Daten im Dashboard-Stil für den authentifizierten Bereich.
Benachrichtigungen	`GET /notifications`, `POST /notifications/mark-as-read`	In-App-Benachrichtigungsendpunkte, sofern verfügbar.

Wichtiger Hinweis zur Terminerstellung/-aktualisierung

Einige öffentliche API-Referenzen beschreiben Routen zum Erstellen und Aktualisieren von Terminen. In der überprüften Booknetic-Quelle für diesen SaaS-Dokumentationsstapel: POST /appointments und PUT /appointments/{id} Routen sind vorhanden, aber der überprüfte Controller gibt für diese Aktionen eine leere Antwort zurück.

Erstellen Sie daher keine Produktionsintegration, die von der Terminerstellung/-aktualisierung über diese Routen abhängt, es sei denn, der Booknetic-Support oder die Technik bestätigen den unterstützten Anforderungstext und das Laufzeitverhalten für Ihre Version.

Bei Terminintegrationen sind die sichereren dokumentierten Aktionen das Auflisten von Terminen, das Lesen von Termindetails, das Löschen, sofern zulässig, und das Ändern des Status, sofern zulässig.

Was nicht über den öffentlichen REST API verfügbar ist

Booknetic SaaS verfügt außerdem über besitzerseitige Bildschirme zur Verwaltung der Plattform. Diese Bildschirme sind nicht mit denen des öffentlichen Mandanten REST API identisch.

Die geprüfte Quelle fand keinen öffentlichen /wp-json/booknetic/v1/ REST-Endpunkt für SaaS-Vorgänge auf Inhaberseite wie:

Auflistung aller Mandanten;
Mandanten erstellen oder bearbeiten;
Mandanten löschen;
Verwaltung von SaaS-Tarifen;
SaaS-Einstellungen ändern;
Verwaltung benutzerdefinierter Felder auf Plattformebene;
Mutation des SaaS-Workflow-Editors;
Verwaltung der API-Schlüssel des Mandanten zentral über das Inhaberkonto;
Mit einem Inhaberschlüssel können die Betriebsdaten aller Mandanten abgefragt werden.

Diese besitzerseitigen Bildschirme verwenden interne Admin-Routen innerhalb des WordPress-Administratorbereichs. Sie sind nicht als öffentliche REST API-Endpunkte dokumentiert und sollten nicht als kundenorientierte Integrationsendpunkte verwendet werden.

Verwenden Sie den SaaS-Inhaber UI für besitzerseitige Vorgänge wie z Tenants, Plans, Zahlungen, und SaaS Settings.

Beispiel: Termine für einen Mandanten einholen

Diese Anfrage listet Termine für den Mandantenbenutzer auf, der durch die Anmeldeinformationen dargestellt wird:

curl -u '[email protected]:xxxx xxxx xxxx xxxx xxxx xxxx' \
  'https://tenant-slug.your-domain.com/wp-json/booknetic/v1/appointments?skip=0&limit=20'

Beispielhafte Antwortform:

{
  "data": [],
  "meta": {
    "total": 0,
    "skip": 0,
    "limit": 20
  }
}

Ein Mandanten mit Terminen erhält darin Terminobjekte data.

Beispiel: Kunden auflisten

curl -u '[email protected]:xxxx xxxx xxxx xxxx xxxx xxxx' \
  'https://tenant-slug.your-domain.com/wp-json/booknetic/v1/customers?skip=0&limit=50'

Beispielhafte Antwortform:

{
  "data": [],
  "meta": {
    "total": 0,
    "skip": 0,
    "limit": 50
  }
}

Beispiel: Kunden anlegen

Verwenden Sie dies nur mit Anmeldeinformationen für den Mandant, der Inhaber des Kundendatensatzes sein soll:

curl -u '[email protected]:xxxx xxxx xxxx xxxx xxxx xxxx' \
  -X POST 'https://tenant-slug.your-domain.com/wp-json/booknetic/v1/customers' \
  -H 'Content-Type: application/json' \
  -d '{
    "first_name": "QA",
    "last_name": "Customer",
    "email": "[email protected]",
    "phone": "+15555550199",
    "note": "Imported via API"
  }'

Eine erfolgreiche Aktion zum Erstellen/Aktualisieren eines Kunden gibt eine ID-Form des Kunden zurück, z. B.:

{
  "customer_id": 123
}

Wenn die Validierung fehlschlägt, gibt Booknetic möglicherweise einen Validierungsfehler mit Details auf Feldebene zurück.

Beispiel: Einen Terminstatus ändern

Wenn der authentifizierte Mandantenbenutzer die Berechtigung zum Ändern des Terminstatus hat:

curl -u '[email protected]:xxxx xxxx xxxx xxxx xxxx xxxx' \
  -X PUT 'https://tenant-slug.your-domain.com/wp-json/booknetic/v1/appointments/123/change-status' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "approved",
    "run_workflows": 1
  }'

Verwenden Sie den Termin ID, der zu diesem Mandanten gehört. Verwenden Sie diesen Endpunkt nicht, um den Termin ID eines anderen Mandanten zu testen.

Beispiel: Zahlungsstatus für einen Termin aktualisieren

Wenn ein externes Abgleichstool eine Terminzahlung als bezahlt markieren muss:

curl -u '[email protected]:xxxx xxxx xxxx xxxx xxxx xxxx' \
  -X PUT 'https://tenant-slug.your-domain.com/wp-json/booknetic/v1/payments/123' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "paid",
    "paid_amount": 50
  }'

Der Zahlungsstatus values wird voraussichtlich einer der folgenden sein:

pending
paid
canceled
not_paid

Die {appointmentId} Im URL ist der Termin ID mit der Zahlung verbunden.

Antwort- und Fehlerformen

Listenendpunkte geben üblicherweise Folgendes zurück:

{
  "data": [
    {}
  ],
  "meta": {
    "total": 42,
    "skip": 0,
    "limit": 20
  }
}

Einzelelement-Endpunkte geben üblicherweise Folgendes zurück:

{
  "data": {}
}

Endpunkte erstellen/aktualisieren geben möglicherweise einen ID zurück:

{
  "id": 123
}

oder für Kunden:

{
  "customer_id": 123
}

Validierungsfehler können Folgendes umfassen: 422 Antwort mit Felddetails:

{
  "code": "422",
  "message": "Validation failed",
  "data": {
    "status": 422,
    "errors": {
      "email": "Please enter a valid email"
    }
  }
}

Tarifbegrenzungen

Die überprüfte Booknetic SaaS-Quelle für diesen Dokumentationsstapel identifizierte keine Booknetic-spezifische öffentliche REST-Ratenbegrenzungsrichtlinie.

Das geht nicht bedeutet, dass Integrationen unbegrenzten Datenverkehr senden sollten. REST-Aufrufe nutzen weiterhin Ihre WordPress-Site, Hosting-Ressourcen, Datenbank, Sicherheits-Plugins, Caching-Ebenen und alle von Ihnen konfigurierten Firewall- oder CDN-Regeln.

Empfohlenes Integrationsverhalten:

Verwenden Sie Paginierung mit skip und limit anstatt immer wieder alles anzufordern;
Vermeiden Sie enge Abfrageschleifen.
Cache-Ergebnisse nach Möglichkeit in Ihrem externen System speichern;
Versuchen Sie fehlgeschlagene Anfragen mit Backoff erneut, anstatt sie sofort zu wiederholen.
Planen Sie große Synchronisierungsaufträge außerhalb Ihrer geschäftigsten Buchungszeiten.
Überwachen Sie das Hosting von CPU-, PHP-Workern und die Datenbanklast.

Wenn Sie eine Integration mit hohem Volumen ausführen, testen Sie sie im Staging oder während eines Fensters mit geringem Datenverkehr, bevor Sie sie in der Produktion verwenden.

REST API vs. Webhooks

REST API und Webhooks lösen unterschiedliche Probleme.

Brauchen	Benutzen
Ihr externes System möchte Booknetic-Daten bei Bedarf lesen oder aktualisieren	REST API
Booknetic oder ein Zahlungsanbieter müssen Ihre Website benachrichtigen, wenn ein Ereignis eintritt	Webhook
Ein Mandantentwickler möchte Termindaten in ein Dashboard ziehen	REST API
Stripe muss Booknetic SaaS mitteilen, dass eine Abonnementverlängerung bezahlt wurde	Stripe-Webhook

Informationen zu Stripe SaaS-Abrechnungsereignissen finden Sie unter Einrichten des Stripe-Webhooks für die SaaS-Abrechnung.

Wenn Sie Mandantenbuchungsintegrationen erstellen, verwechseln Sie Stripe-Abrechnungs-Webhooks nicht mit Booknetic-Mandanten-REST API-Aufrufen. Stripe-Webhooks dienen zur Aktualisierung der SaaS-Abonnementabrechnung. Booknetic REST API dient für Mandantenbuchungsdaten.

Häufige Fragen

Kann mein Mandant seinem Entwickler API Zugriff gewähren?

Ja, der Mandant kann einem Entwickler mandantenweiten API-Zugriff gewähren, indem er Anmeldeinformationen für diesen Mandantenbenutzer verwendet, normalerweise über einen WordPress-Anwendungskennwort-/Basisauthentifizierungsfluss.

Geben Sie Anmeldeinformationen nur an vertrauenswürdige Entwickler weiter. Behandeln Sie Anwendungskennwörter wie Geheimnisse und widerrufen Sie sie, wenn die Integration nicht mehr benötigt wird.

Kann ich mit einem Inhaber-API-Schlüssel die Termine und Kunden jedes Mandanten lesen?

In der überprüften Quelle wurde kein öffentlicher, mandantenübergreifender REST-Schlüssel auf Inhaberseite gefunden.

Wenn Sie Daten von mehreren Mandanten über das öffentliche REST API benötigen, besteht das sicherere Modell darin, den Endpunkt jedes Mandanten mit den eigenen Anmeldeinformationen dieses Mandanten aufzurufen und die Daten in Ihrem externen System getrennt aufzubewahren.

Versuchen Sie nicht, die Mandantengrenze zu umgehen, indem Sie interne Administratorrouten oder direkten Datenbankzugriff verwenden, es sei denn, Sie verfügen über einen kontrollierten, sicherheitsüberprüften internen Prozess. Direkter Datenbankzugriff kann private Mandanten-/Kundendaten offenlegen und sollte nicht als normale Kundenintegrationsmethode behandelt werden.

Kann der SaaS-Inhaber Mandanten und Tarife über REST verwalten?

Nicht über einen öffentlichen REST-Endpunkt, der in der überprüften Quelle gefunden wurde.

Verwenden Sie das Admin-Panel des SaaS-Inhabers für Mandanten, Plan, SaaS-Einstellungen, SaaS-Zahlungen und Plattform-Workflow-Management.

Gibt es ein separates? `booknetic-saas/v1` REST-Namespace?

Keine separate Öffentlichkeit booknetic-saas/v1 Der Namespace wurde in der überprüften Quelle für diesen Dokumentationsstapel gefunden.

Verwenden Sie den Standard-Namespace Booknetic REST:

/wp-json/booknetic/v1/

Gibt es einen offiziellen SDK?

Im für diese Seite verwendeten Quellmaterial wurde kein offizielles Booknetic SaaS REST SDK identifiziert.

Entwickler können den REST API direkt mit Standard-HTTP-Clients aufrufen, z curl, JavaScript fetch, PHP HTTP-Clients, Python requests, oder Postbote.

Wie funktioniert die API-Versionierung?

Der aktuelle Namespace enthält die Version im Pfad:

/wp-json/booknetic/v1/

Wenn Booknetic eine zukünftige REST-Version einführt, würde diese normalerweise als neuer Namespace erscheinen, z v2. Behalten Sie die Integrationen bei, die für den dokumentierten Namespace für Ihre installierte Booknetic-Version geschrieben sind.

Warum gibt ein Endpunkt Berechtigungsfehler für einen Mandanten zurück, für einen anderen jedoch nicht?

Überprüfen Sie zuerst diese Punkte:

Ist der Benutzername/das Anwendungspasswort korrekt?
Ist das Anwendungspasswort noch aktiv?
Gehört dieser WordPress-Benutzer zu dem Mandanten, den Sie erwarten?
Ist das von Ihnen aufgerufene Modul im Tarif des Mandanten enthalten?
Verfügt der Benutzer über die erforderlichen Fähigkeiten für diese Aktion?
Rufen Sie den richtigen Mandanten URL an?

Die Planfunktionen gelten für API-Anrufe. Wenn der Mandant nicht auf ein Modul im Mandantenpanel zugreifen kann, schlägt möglicherweise auch die zugehörige API-Aktion fehl.

Best Practices für SaaS-Inhaber

Bevor Sie Mandanten API-Hinweise geben:

Bestätigen Sie den Mandanten-URL-Stil, den Ihre Plattform verwendet.
Erstellen Sie separate Anmeldeinformationen für jede Mandantenintegration.
Geben Sie niemals die WordPress-Administratoranmeldeinformationen des SaaS-Inhabers weiter.
Aktivieren Sie nur die Module und Planfunktionen, die der Mandant nutzen sollte.
Dokumentieren Sie, welches externe System das jeweilige Anwendungspasswort besitzt.
Nicht verwendete Anwendungskennwörter widerrufen;
Testen Sie eine zerstörungsfreie Methode GET Anfrage vor dem Senden von Erstellungs-/Aktualisierungs-/Löschanfragen;
Halten Sie Mandantendaten auch in externen Systemen getrennt.

Checkliste zur schnellen Fehlerbehebung

Problem	Was zu überprüfen ist
`401` nicht autorisiert	Benutzername, Anwendungspasswort, widerrufenes Passwort, fehlerhafter Basic Auth-Header.
`403` oder die Erlaubnis wurde verweigert	Mandantenplanfähigkeit, Benutzerfähigkeit, Modulzugriff.
Leer `data` Array	Der Mandant verfügt möglicherweise noch nicht über Datensätze, die Filter sind möglicherweise zu eng oder die Anfrage ist auf einen anderen Mandanten beschränkt.
Falsche Mandantendaten erwartet	Überprüfen Sie den Mandanten URL und den authentifizierten Benutzer. Verwenden Sie einen WordPress-Benutzer nicht mandantenübergreifend wieder, es sei denn, dies wurde absichtlich konfiguriert.
`404` Endpunkt nicht gefunden	Bestätigen Sie, dass der Pfad unten aufgeführt ist `/wp-json/booknetic/v1/` und überprüfen Sie beispielsweise die Routenschreibweise `staffs` statt `staff`.
„Erstellen/Aktualisieren“ verhält sich nicht wie erwartet	Stellen Sie sicher, dass der Endpunkt in Ihrer installierten Booknetic-Version unterstützt wird, bevor Sie sich darauf verlassen.
Langsame Antworten	Reduzieren Sie Abfragen, paginieren Sie und überprüfen Sie die Hosting-/Serverressourcen von WordPress.