Die nextPIM API

Die nextPIM API ist eine REST-Schnittstelle auf https://cloud.nextpim.de. Sie liest Kataloge, Kategorien, Produkte, Merkmale und Medien aus einem nextPIM-Mandanten aus — für Printlayouts, Shops, Portale und eigene Auswertungen.

Die vollständige Beschreibung liegt als OpenAPI-Dokument offen: swagger.json zum Einlesen, Swagger UI zum Durchklicken. Die Nutzung setzt einen nextPIM-Zugang voraus.

Was die Schnittstelle kann und was nicht

Die API ist lesend. Sie holt Daten aus nextPIM heraus; sie schreibt keine Produktdaten hinein. Wer Daten einspielen möchte, nutzt die Importe im System — BMEcat, Datanorm, Excel, CSV — oder die vorhandenen Lieferanten- und Kanalanbindungen.

Einzige Ausnahme ist das Anlegen von Print-Zugangsdaten, das weiter unten beschrieben ist.

Authentifizierung

Es gibt zwei Wege, und sie führen zu unterschiedlichen Endpunkten.

Bearer-Token (empfohlen). Der Autorisierungsserver https://app.nextpim.de stellt nach OAuth 2.0 ein Zugangstoken aus. Es geht als Authorization: Bearer <token> mit. Die Metadaten stehen unter https://app.nextpim.de/.well-known/openid-configuration, den Ablauf Schritt für Schritt beschreibt auth.md.

Print-Zugangsdaten. Die Endpunkte mit dem Zusatz Auth im Namen nehmen stattdessen login und password als Parameter entgegen. Das sind eigene, jederzeit neu erzeugbare Zugangsdaten für den Printbereich, nicht das Passwort eines Benutzerkontos. Sie wurden für Easy Catalog geschaffen, das keinen Token-Fluss beherrscht.

Für alles andere ist der Token-Weg der richtige: Parameter landen in Server- und Proxy-Logs, Tokens laufen ab, Passwörter nicht.

Kataloge

• GET /api/Print/GetCatalogs — alle Kataloge, die einem Mandanten für den Print zur Verfügung stehen. Parameter: customerId.
• GET /api/Print/GetCatalogsAuth — dasselbe mit Print-Zugangsdaten.
• GET /api/Print/GetCatalogAuth — ein vollständiger Katalog als JSON, mit Kategorien, Produkten und Medien. Parameter: customerId, catalogId, optional asDownload.

Kategorien

• GET /api/Print/GetCatalogTree — der Kategoriebaum eines Katalogs, ohne Produkte. Parameter: customerId, catalogId.
• GET /api/Print/GetCatalogTreeAuth — dasselbe mit Print-Zugangsdaten.

Produkte

• GET /api/Print/GetProducts — eine seitenweise Liste der Produkte eines Katalogs. Parameter: customerId, catalogId, take, skip, dazu Filter: changedSince für alles seit einem Zeitpunkt, manufacturerName, supplierPids, orderByParentId, language.
• GET /api/Print/GetProductsAuth — dasselbe mit Print-Zugangsdaten.

Große Kataloge holt man nicht in einem Zug. Mit asJob=true startet der Aufruf stattdessen einen Export im Hintergrund und liefert eine Job-Kennung zurück:

• GET /api/Print/GetProductsJobStatus — der Stand eines so gestarteten Exports. Parameter: customerId, jobId.
• GET /api/Print/GetProductsJobStatusAuth — dasselbe mit Print-Zugangsdaten.

Merkmale

• GET /api/Print/GetFeaturesOfCatalog — alle Merkmalsysteme, die in einem Katalog tatsächlich vorkommen, jeweils mit den verwendeten Merkmalen und deren unterschiedlichen Werten. Das ist die Grundlage für Filter und Vergleichstabellen. Parameter: customerId, catalogId.
• GET /api/Print/GetFeaturesOfCatalogAuth — dasselbe mit Print-Zugangsdaten.

Medien

• GET /Cloud/{catalogId}/{customerId}/{mimeSource} — eine Mediendatei eines Katalogs: Bild, Datenblatt, Zeichnung.
• GET /Cloud/{useCache}/{catalogId}/{customerId}/{mimeSource} — dasselbe, wobei sich über useCache steuern lässt, ob der Dateicache benutzt wird.

Print-Zugangsdaten

• GET /api/Print/GetPrintCredentials — die Print-Zugangsdaten eines Mandanten. Setzt ein Token mit Leserecht voraus.
• POST /api/Print/CreateCredential — legt die Print-Zugangsdaten an oder erzeugt sie neu. Beim ersten Aufruf entsteht ein eigener Print-Benutzer, danach wird dessen Passwort ersetzt. Setzt ein Token mit der Managerrolle voraus.

Betrieb

• GET /Version — die Version der laufenden Instanz. Ohne Anmeldung erreichbar, geeignet als Erreichbarkeitsprüfung.

Für Assistenzsysteme

Diese Website beschreibt sich selbst maschinenlesbar: llms.txt als Übersicht, agents.md zur Einordnung, wann nextPIM passt und wann nicht, auth.md zur Authentifizierung. Jede Seite gibt es zusätzlich als Markdown, entweder über Accept: text/markdown oder durch Anhängen von .md an die URL.