Wie verbinde ich meinen Shop oder ein anderes System über die API mit PARITY.med?

Wie verbinde ich meinen Shop oder ein anderes System über die API mit PARITY.med?

Schritt für Schritt

1. Rolle für die Anbindung anlegen — unter Einstellungen → Rollen eine eigene Rolle anlegen, z. B. „Shop-Schnittstelle", und nur die Rechte vergeben, die das angebundene System braucht. Für das Lesen von Artikeln genügt „Artikel anzeigen".
2. API-Zugang öffnen — unter Einstellungen → API-Zugang. Hier siehst du alle Dienstkonten deines Mandanten mit Rolle, Schlüssel-Kürzel, letzter Nutzung und Status.
3. „Dienstkonto anlegen" klicken — eine Bezeichnung eintragen (z. B. „Shopware-Anbindung") und die eben angelegte Rolle auswählen. Beides ist Pflicht.
4. Schlüssel kopieren und sicher ablegen — nach dem Anlegen erscheint der API-Schlüssel (beginnt mit phk_live_) genau einmal. Kopiere ihn in einen Passwort-Tresor oder gib ihn direkt an die Stelle weiter, die das angebundene System einrichtet. Danach ist er nicht mehr abrufbar.
5. Verbindung testen — über „Referenz-Doku" auf derselben Seite öffnest du die Beschreibung der Händler-API. Dort lässt sich jeder Aufruf mit dem Schlüssel direkt ausprobieren.

Überblick

Ein API-Schlüssel gehört immer zu einem Dienstkonto. Ein Dienstkonto ist ein technischer Benutzer ohne Anmeldung, dem du eine Rolle zuweist wie einem Mitarbeiter. Was das angebundene System lesen und ändern darf, bestimmt allein diese Rolle. Ein Schlüssel kann deshalb nie mehr, als du der Rolle bewusst erlaubt hast.

Das angebundene System schickt den Schlüssel bei jedem Aufruf im Header X-Api-Key mit. Jeder Aufruf läuft im Kontext deines Mandanten; Daten anderer Mandanten sind nicht erreichbar.

Voraussetzungen

• Das Recht „API-Schlüssel verwalten (Händler-API und b-med-Migration)", um Dienstkonten anzulegen und zu deaktivieren. Du findest es unter Einstellungen → Rollen im Bereich „API-Zugang". Ohne dieses Recht erscheint der Menüpunkt nicht.
• Das Recht „Rollen anzeigen", damit im Dialog die Rollen zur Auswahl stehen.
• Ein gebuchtes Modul für die Daten, die das System abfragt, z. B. Handel für Artikel.

Wie viele Dienstkonten kann ich anlegen?

Höchstens fünf Dienstkonten können gleichzeitig aktiv sein. Sie zählen nicht als Benutzerlizenz. Ein Dienstkonto, dessen Schlüssel abgelaufen oder widerrufen ist, belegt keinen Platz mehr.

Lege für jedes angebundene System ein eigenes Dienstkonto an. Dann kannst du ein einzelnes System sperren, ohne die anderen zu unterbrechen, und siehst je System, wann es zuletzt zugegriffen hat.

Wie sperre ich einen Zugang?

In der Liste unter Einstellungen → API-Zugang beim Dienstkonto auf „Deaktivieren" klicken und bestätigen. Das Dienstkonto wird gesperrt und sein Schlüssel widerrufen; das angebundene System erhält ab sofort die Antwort 401. Das lässt sich nicht rückgängig machen. Für einen neuen Zugang legst du ein neues Dienstkonto an.

Deaktiviere einen Zugang sofort, wenn ein Schlüssel versehentlich weitergegeben oder in einer Datei gespeichert wurde, die andere einsehen können.

Häufige Fehlerbilder

Das angebundene System erhält 401

Der Schlüssel fehlt im Header X-Api-Key, ist falsch kopiert, abgelaufen oder das Dienstkonto wurde deaktiviert. Prüfe den Status in der Liste und lege bei Bedarf ein neues Dienstkonto an.

Das angebundene System erhält 403

Der Rolle des Dienstkontos fehlt das nötige Recht, oder das Modul ist für deinen Mandanten nicht gebucht. Ergänze das Recht in der Rolle unter Einstellungen → Rollen; die Änderung gilt sofort, ein neuer Schlüssel ist nicht nötig.

Das angebundene System erhält 429

Je Schlüssel gelten 20 Anfragen pro Sekunde, kurzzeitig bis zu 100 am Stück. Die Antwort nennt im Header Retry-After, nach wie vielen Sekunden das System es erneut versuchen darf.

Im Dialog stehen keine Rollen zur Auswahl

Dir fehlt das Recht „Rollen anzeigen", oder in deinem Mandanten gibt es noch keine Rolle. Lege zuerst eine Rolle an oder lass dir das Recht von deiner Administration geben.

FAQ

F: Sieht das Dienstkonto in der Benutzerverwaltung wie ein Mitarbeiter aus?

A: Nein. Dienstkonten erscheinen nur unter Einstellungen → API-Zugang, nicht in der Benutzerliste und nicht in Auswahllisten für Verantwortliche.

F: Welche Daten kann ich über die Händler-API abrufen?

A: Derzeit Artikel mit Stammdaten und Preisen, auch als Änderungsliste für den regelmäßigen Abgleich. Weitere Bereiche wie Kunden, Belege und das Anlegen von Aufträgen folgen schrittweise. Den aktuellen Umfang zeigt immer die Referenz-Doku.

F: Kann ich einen verlorenen Schlüssel noch einmal anzeigen lassen?

A: Nein. PARITY.med speichert nur einen Prüfwert, nicht den Schlüssel selbst. Deaktiviere das Dienstkonto und lege ein neues an.

Verwandte Themen

• Welche Schnittstellen bietet PARITY.med? — Überblick über API, CSV, DATEV und Co-med.
• Warum bekomme ich „Zu viele Anfragen" (Fehler 429)? — was hinter der Aufruf-Bremse steckt.

Letzte Aktualisierung: 2026-09-30