API-Schlüssel
Ein API-Schlüssel lässt Ihr Backend mit einem Shop arbeiten. Erstellen Sie ihn im Dashboard, speichern Sie ihn auf Ihrem Server und senden Sie ihn als Bearer-Token.
Einen Schlüssel erstellen
Abschnitt betitelt „Einen Schlüssel erstellen“Erstellen Sie im Shop einen Schlüssel mit den Berechtigungen read und write. Das ivk_-Token wird nur einmal angezeigt; speichern Sie es sofort. Ein Shop kann bis zu 10 nicht widerrufene Schlüssel haben; siehe Limits.
Ein Agent kann denselben Schlüssel mit seiner Anmeldesitzung erstellen:
curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/keys' \ -H 'Authorization: Bearer <session-token>' \ -H 'Idempotency-Key: <saved-unique-key>' \ -H 'Content-Type: application/json' \ -d '{"name":"backend","scopes":["read","write"]}'Verwenden Sie eine Sitzung, um Schlüssel zu erstellen oder zu ändern. Ein API-Schlüssel kann keinen weiteren Schlüssel erstellen. Wenn das Konto MFA hat, kann die Schlüsselverwaltung einen frischen zweiten Faktor erfordern.
Die API aufrufen
Abschnitt betitelt „Die API aufrufen“curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/payments?limit=50' \ -H 'Authorization: Bearer ivk_...'| Bereich | Zweck |
|---|---|
read |
erlaubt das Lesen von Rechnungen und Einzahlungen sowie der Gebühren und aktivierten Netzwerke des Händlers. |
write |
erlaubt alles im Shop: Rechnungen und Einzahlungen erstellen, stornieren und deaktivieren, Webhooks, Name und Branding des Shops. |
Fordern Sie für ein Backend, das Zahlungen erstellt und prüft, beide Berechtigungen an. Gehen Sie nicht davon aus, dass write automatisch read einschließt.
Der Schlüssel arbeitet nur mit seinem eigenen Shop, dort aber mit allem. Eine Anmeldesitzung braucht es nur dafür, wohin der Shop auszahlt (Empfänger, Delegate, Auszahlungsziel), für das Archivieren und das Zurücksetzen der Sandbox. Mit read liest er außerdem die Gebühren und aktivierten Netzwerke seines Händlers (GET /api/v1/merchants/{merchant_id}/tariffs und /networks). Alles andere zu Konto und Händler – Anmeldung, Profil, Team, andere Shops, die Händlerübersicht, API-Schlüssel, Wallet und Karte – erfordert eine Anmeldesitzung; ein Schlüssel erhält 403 api_key_not_allowed oder 401. Setzen Sie ihn niemals in Browser-Code, eine Zahlungs-URL oder einen geteilten Chat.
Das Archivieren des Shops deaktiviert alle seine Schlüssel.
Prüfen, wozu ein Schlüssel gehört
Abschnitt betitelt „Prüfen, wozu ein Schlüssel gehört“GET /api/v1/me mit dem Schlüssel liefert den Schlüssel und wozu er gehört:
{"user_id":"…","onboarding_required":false,"mfa_required":false,"key_id":"…","key_name":"backend","scopes":["read","write"],"shop_id":"…","shop_name":"Main shop","sandbox":false,"merchant_id":"…","merchant_name":"Acme"}Verwenden Sie shop_id in den Shop-Pfaden; eine Händlerliste ist dafür nicht nötig.
Zugriff per IP einschränken
Abschnitt betitelt „Zugriff per IP einschränken“Geben Sie optional allowed_ips beim Erstellen oder Bearbeiten eines Schlüssels an:
{"allowed_ips":["203.0.113.10","2001:db8::/32"]}Dies sind Beispieladressen. Ersetzen Sie sie durch die tatsächlichen Egress-Adressen Ihres Backends. Bis zu 10 IPs oder CIDR-Bereiche sind pro Schlüssel zulässig; mehr gibt 400 too_many_allowed_ips zurück. Eine leere Liste entfernt die Beschränkung.
Rotieren oder widerrufen
Abschnitt betitelt „Rotieren oder widerrufen“Erstellen Sie einen Ersatzschlüssel, aktualisieren Sie Ihr Backend und widerrufen Sie dann den alten Schlüssel mit DELETE /api/v1/shops/{shop_id}/keys/{key_id}.
PATCH auf demselben Pfad kann name, enabled, scopes oder allowed_ips ändern. Ausgelassene Felder bleiben unverändert. Das Bearbeiten zeigt das Token weder an noch rotiert es.
Schlüssel funktionieren, bis sie deaktiviert oder widerrufen werden, vorbehaltlich des Konto- und Shop-Zugriffs. Sie sind kein Versprechen dauerhaften Zugriffs. Siehe die API-Referenz für Anfragedetails.