Jede API-Anfrage muss Ihren API-Schlüssel im Header api-key enthalten. Fehlt der Schlüssel oder gehört er nicht zum Programm in der URL, antwortet die API mit 403.

Jeder Schlüssel gehört zu genau einem Programm. Sie können mehrere Schlüssel erstellen, zum Beispiel einen pro System, das sich mit JeriCommerce verbindet, jedem nur den nötigen Zugriff geben und jeden davon löschen, ohne die anderen zu beeinträchtigen.

API-Schlüssel abrufen

Um einen Schlüssel zu erstellen, öffnen Sie Settings > Technical > API keys und klicken Sie auf Add API key. Es öffnet sich eine Seite mit diesen Einstellungen.

Seite Add API key mit Name, Expiration, Restrict key, Permissions, Restrict by IP und Status
Die Seite Add API key, mit aktiviertem Restrict key
1

Schlüssel benennen

Geben Sie unter Name einen Namen ein, zum Beispiel das System, das ihn nutzen wird.

2

Ablauf wählen

Wählen Sie unter Expiration 15 minutes, 1 hour, 1 day, 7 days, 30 days oder Never. Neue Schlüssel starten mit Never. Die Zeit zählt ab dem Speichern.

3

Zugriff wählen

Bei neuen Schlüsseln ist Restrict key aktiviert. Aktivieren Sie unter Permissions mindestens eine Option. Die Tabelle weiter unten zeigt, was jede erlaubt.

4

IP-Adressen beschränken, falls gewünscht

Aktivieren Sie Restrict by IP, um nur Anfragen von bestimmten Adressen anzunehmen. Geben Sie unter IP address or CIDR range eine Adresse ein, zum Beispiel 203.0.113.7 oder 203.0.113.0/24, und klicken Sie auf Add. Sie können bis zu 100 Einträge hinzufügen, IPv4 oder IPv6.

5

Speichern und Schlüssel kopieren

Klicken Sie auf Save. Der Dialog API key created zeigt den Schlüssel. Kopieren Sie ihn und bewahren Sie ihn sicher auf, denn Sie können ihn nicht noch einmal ansehen.

Wenn Sie Restrict key deaktivieren, kann der Schlüssel die gesamte API aufrufen, und ein Leck ist deutlich riskanter. Lassen Sie die Option aktiviert, außer ein System braucht wirklich vollen Zugriff.

Token in API-Anfragen einschließen

Fügen Sie den im vorherigen Schritt abgerufenen API-Schlüssel als Wert des Headers api-key hinzu, um auf die API-Endpunkte zuzugreifen.

Das folgende Beispiel verwendet cURL und liest einen Kunden:

curl --request GET \
  --url https://api.jericommerce.com/v1/programs/{program_slug}/customers/customer@example.com \
  --header 'api-key: {{ apiKey }}'

Bewahren Sie den Schlüssel auf Ihrem Server auf. Wer ihn kennt, kann die Daten Ihrer Kunden ändern. Binden Sie ihn deshalb nie in eine Website, eine App oder anderen Code ein, der auf dem Gerät des Kunden läuft.

Die Endpunkte Balance preview und List rewards sind öffentlich und funktionieren ohne Schlüssel.

Was jede Berechtigung erlaubt

Ein eingeschränkter Schlüssel kann nur das, was Sie unter Permissions aktivieren. Klaviyo-Webhooks sind ebenfalls API-Aufrufe, ihr Schlüssel braucht also die Berechtigung für diese Aktion.

Berechtigung Was der Schlüssel kann
Customers Kundendaten abrufen
Customer tokens Download-Link abrufen und Kunden-Tokens
Balance Guthaben erhöhen und verringern
Coupons and rewards Coupon zuweisen und Prämie einlösen
Campaigns Gift Card senden und Kampagnen zuweisen
Push Push-Benachrichtigung senden
Earning flows Eigene Sammelaktion ausführen
Subscriptions JeriCommerce-Abonnement des Programms erstellen oder kündigen
API integration Kunden und Treuedaten über die Custom API Integration synchronisieren
VTAP Einen VTAP-NFC-Leser verbinden
MCP Diesen Schlüssel mit dem JeriCommerce-MCP verwenden: No access, Read oder Write. Write schließt das Lesen ein

Schlüssel bearbeiten

Klicken Sie unter Settings > Technical > API keys bei einem Schlüssel auf die drei Punkte und wählen Sie Edit API key. Sie können alles außer dem Wert des Schlüssels ändern.

  • Expiration bietet Don't change an, wenn der Schlüssel ein Ablaufdatum hat, damit das Speichern anderer Einstellungen es nicht verschiebt.
  • Status in der Seitenspalte stoppt einen Schlüssel, wenn Sie Inactive wählen. Mit Active schalten Sie ihn wieder ein.
  • Delete API key im selben Menü entfernt den Schlüssel. Apps, die ihn verwenden, funktionieren dann nicht mehr.

Die Liste zeigt bei jedem Schlüssel ein Badge: Active, Inactive oder Expired. Schlüssel, die vor diesen Einstellungen erstellt wurden, haben keine Beschränkungen und keinen Ablauf und zeigen Unrestricted, bis Sie sie beschränken.

Fehler des API-Schlüssels

Diese Fehler stehen im Feld message der Antwort.

Status message Bedeutung
401 API_KEY_INACTIVE Der Schlüssel ist nicht aktiv. Prüfen Sie seinen Status.
401 API_KEY_EXPIRED Die Expiration des Schlüssels ist überschritten.
403 API_KEY_IP_NOT_ALLOWED Die Anfrage kommt von einer Adresse außerhalb von Restrict by IP.
403 API_KEY_PERMISSION_DENIED Dem Schlüssel fehlt die Berechtigung für diese Anfrage.