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

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

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.
write	erlaubt das Erstellen von Rechnungen und Einzahlungen sowie die Verwaltung von Webhooks.

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 funktioniert nur innerhalb der Berechtigungen seines Shops. Er kann keine Konten oder das Team des Händlers verwalten. Setzen Sie ihn niemals in Browser-Code, eine Zahlungs-URL oder einen geteilten Chat.

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

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.