API und Webhooks
Kabeldaten-API für Website, Shop und PIM.
Über die API holen Ihre Systeme, was im Portal liegt: jedes veröffentlichte Kabel mit Daten, Bildern, Datenblatt und Schnittzeichnung.
Für wenFür IT-Leitung, Entwicklerinnen und Entwickler und Web-Agenturen.
Kurz gesagt
- Lesen: Kabel, Daten, Bilder und Datenblätter
- Bestellen: Renderings ohne das Portal zu öffnen
- Webhooks: signierte Meldungen bei Änderungen
- Schlüssel mit Rechten, als OpenAPI beschrieben
Ihr System fragt
GET /api/v1/cables/rg58Authorization: Bearer cbl_…Das Portal antwortet
{"slug": "rg58","name": "RG 58 C/U","technical": [{"kind": "field","label": "Wellenwiderstand","value": { "kind": "text", "text": "50 Ohm" }}],"assets": [{"url": "https://portal.example/…/rg58.png",… weitere FelderIhre Produktseite
Was ist die API?
Was es ist
Die API ist die Schnittstelle, über die Ihre eigenen Systeme Kabel, Daten und Bilder aus dem Portal holen.
Ihre Kabel liegen einmal im Portal. Website, Shop und PIM fragen dort nach, statt eine eigene Abschrift zu pflegen. Ein PIM ist das System, in dem ein Unternehmen seine Produktdaten sammelt.
Die Begriffe
- API
- Eine Adresse, die ein Programm aufruft und die mit Daten antwortet, nicht mit einer Seite für Menschen.
- API-Schlüssel
- Ein geheimer Text, mit dem sich Ihr System ausweist. Er gehört zu genau einer Firma im Portal.
- Recht
- Was ein Schlüssel darf: Lesen, Schreiben oder Bestellen. Sie wählen es beim Anlegen.
- Webhook
- Eine Meldung, die das Portal von sich aus an eine Adresse Ihres Systems sendet, sobald etwas geschieht.
- OpenAPI-Beschreibung
- Eine Datei, die jeden Aufruf und jedes Feld der API maschinenlesbar beschreibt.
Wie kommen die Daten in mein System?
So funktioniert es
Ihr Server fragt mit einem Schlüssel, das Portal antwortet mit Daten und meldet später, was sich ändert.
Das Beispiel zeigt das Lesen eines Kabels. Bestellen läuft genauso: fragen, antworten, melden.
Der Ablauf in sechs Stationen auf einer Linie: Sie legen einen Schlüssel an. Ihr System fragt ein Kabel ab, das Portal liefert Daten und Adressen, Ihr System zeigt sie. Später meldet das Portal eine Änderung, und Ihr System holt das Geänderte.
SieIhr SystemDas Portal
SieSchlüssel anlegen
Ihr SystemKabel abfragen
Das PortalDaten und Adressen liefern
Ihr SystemAuf der eigenen Seite zeigen
Das PortalÄnderung per Webhook melden
Ihr SystemNur das Geänderte holen
Schritt für Schritt
- Schritt 1 von 6: Sie
Schlüssel anlegen
Ein Inhaber legt im Portal einen Schlüssel an und wählt seine Rechte. Das Portal zeigt den Schlüssel genau einmal.
- Schritt 2 von 6: Ihr System
Kabel abfragen
Ihr Server ruft die Liste oder ein einzelnes Kabel ab. Den Schlüssel sendet er im Kopf der Anfrage mit.
- Schritt 3 von 6: Das Portal
Daten und Adressen liefern
Die Antwort ist JSON: technische Daten, Querschnitte und die Adressen von Bildern, Schnittzeichnungen und Datenblatt.
- Schritt 4 von 6: Ihr System
Auf der eigenen Seite zeigen
Ihr System speichert die Daten. Bilder und Zeichnungen bindet es direkt über ihre Adresse ein.
- Schritt 5 von 6: Das Portal
Änderung per Webhook melden
Wird ein Kabel veröffentlicht, geändert oder zurückgezogen, sendet das Portal eine signierte Meldung an Ihre Adresse.
- Schritt 6 von 6: Ihr System
Nur das Geänderte holen
Ihr System prüft die Signatur und ruft genau dieses Kabel neu ab.
Derselbe Weg als Zeichnung
Die Zeichnung zeigt den Weg vom Portal über die API bis auf Ihre Website.
Die API für Website, Shop und PIM
- Kabel, Daten und Bilder liegen im Portal.
- Das System des Herstellers fragt die API, mit einem eigenen Schlüssel.
- Bild und Daten stehen auf der Website; ein Webhook meldet Neues.
Portal, Portal mit API, Entwickler oder Plattform-Partner: Welcher Zugang zu Ihnen passt, steht auf einer Seite. Welcher Zugang passt? →
Was steht in einer Antwort?
Was die API antwortet
Ein Aufruf liefert ein Kabel mit allem, was öffentlich dazugehört: Daten, Querschnitte und die Adressen seiner Dateien.
Oben stehen eine echte Anfrage und ihre gekürzte Antwort. Darunter steht, was eine Produktseite daraus macht. Listen kommen seitenweise, mit bis zu 100 Einträgen je Seite.
Oben eine Anfrage nach einem Kabel mit dem Schlüssel im Kopf und die Antwort als JSON mit technischen Daten, Bildern, Querschnitten und der Adresse des Datenblatts. Darunter eine Produktseite, die daraus Bild, Daten und Downloads zeigt.
Ihr System fragt
GET /api/v1/cables/rg581Authorization: Bearer cbl_…Das Portal antwortet
{"slug": "rg58","name": "RG 58 C/U","technical": [{2"kind": "field","label": "Wellenwiderstand","value": { "kind": "text", "text": "50 Ohm" }}],"assets": [{3"url": "https://portal.example/…/rg58.png","width": 1600, "height": 1067,"contentHash": "9f2c7d0b…",… weitere Felder}],"variants": [{4"outerDiameterMm": 4.95,"crossSectionUrl": "https://portal.example/…/rg58.svg","webModelUrl": "https://portal.example/…/rg58.glb",… weitere Felder}],"datasheetUrl":5"https://portal.example/api/v1/cables/rg58/datasheet",… weitere Felder}Ihre Produktseite
Weitere Kabel aus der Liste
Was die Zahlen zeigen
Die Anfrage
Eine Adresse je Kabel und der Schlüssel im Kopf. Mehr braucht ein lesender Aufruf nicht.
Technische Daten
Eine geordnete Liste aus Bezeichnung und Wert, in der Reihenfolge des Datenblatts.
Bilder mit fester Adresse
Jede freigegebene Datei kommt mit Adresse, Größe in Pixeln und einer Prüfsumme. Die Prüfsumme ändert sich mit der Datei.
Querschnitte
Jede Zeile der Tabelle mit Außendurchmesser, Schnittzeichnung und 3D-Modell, soweit sie vorliegen.
Datenblatt
Das fertige PDF des Kabels hat eine eigene Adresse. Auch dieser Aufruf braucht den Schlüssel.
Lesen, Schreiben oder Bestellen: Welches Recht braucht mein Schlüssel?
Die drei Rechte im Vergleich
Lesen genügt für Website, Shop und PIM; Schreiben und Bestellen geben Sie nur dem System, das es braucht.
Schreiben und Bestellen schließen Lesen ein. Ein Schlüssel kann beide Rechte zugleich haben.
Das Formular für einen neuen Schlüssel im Portal: ein Name, drei Kästchen für die Rechte Lesen, Schreiben und Bestellen und ein Budget. Darunter der Hinweis, dass der Schlüssel nur einmal angezeigt wird.
Neuer Schlüssel
- LesenKabel, Familien, Dateien und Kabelanfragen abrufen
- SchreibenZusätzlich eine Kabelanfrage anlegen
- BestellenZusätzlich Preise abfragen, Bilder bestellen und abholen
cbl_••••••••••••Der Schlüssel wird nur einmal angezeigt.
| Merkmal | Lesen | Schreiben | Bestellen |
|---|---|---|---|
| Was der Schlüssel darf | Kabel, Familien, Dateien und Kabelanfragen abrufen | Zusätzlich eine Kabelanfrage anlegen | Zusätzlich Preise abfragen, Bilder bestellen und abholen |
| Typischer Einsatz | Website, Shop oder PIM zeigen Ihre Kabel | Ihr System meldet ein neues Kabel zum Modellieren | Der Shop bestellt ein fehlendes Bild selbst |
| Budget je Schlüssel | Für Lesen nicht nötig | Für Schreiben nicht nötig | Auf Wunsch je Monat oder insgesamt |
| Für Gäste einer Agentur | Ja, wenn ein Inhaber Lesen freigibt | Nein | Ja, wenn ein Inhaber Bestellen freigibt |
Was bringt die API, und wo endet sie?
Vorteile und Grenzen
Die API hält alle Ihre Systeme auf einem Stand, aber sie liest nur Veröffentlichtes und braucht jemanden, der programmiert.
Vorteile
Eine Quelle für alle Systeme
Was im Portal veröffentlicht ist, steht in Website, Shop und PIM gleich.
Dateien direkt einbinden
Öffentliche Bilder und Zeichnungen haben eine eigene Adresse. Ihre Website bindet sie ein, ohne sie zu kopieren.
Bestellen ohne Doppelungen
Eine doppelt gesendete Bestellung wird nur einmal ausgeführt. Weicht der Preis vom erwarteten ab, wird nichts bestellt.
Schlüssel mit engen Rechten
Jeder Schlüssel hat eigene Rechte und auf Wunsch ein Budget. Ein Inhaber widerruft ihn jederzeit.
Meldungen mit Signatur
Ihr System erkennt an der Signatur, dass eine Meldung vom Portal stammt. Fehlgeschlagene Meldungen wiederholt das Portal mehrmals.
Maschinenlesbar beschrieben
Die OpenAPI-Beschreibung und die Dokumentation mit einem Beispiel für jeden Aufruf sind öffentlich abrufbar.
Grenzen
Nur von Server zu Server
Ein Browser kann die API nicht aufrufen. So landet kein Schlüssel im Quelltext einer Seite.
Nur Veröffentlichtes
Lesende Aufrufe liefern veröffentlichte Kabel und freigegebene Dateien. Entwürfe und archivierte Kabel fehlen.
Kein Veröffentlichen per API
Kabel ändern und veröffentlichen Sie im Portal. Schreiben legt nur eine Kabelanfrage an.
Anfragen aus dem Katalog nur als Hinweis
Ein Webhook meldet, dass eine Anfrage eingegangen ist. Name und Text lesen Sie im Portal.
Nicht jede Änderung wird gemeldet
Geänderte Typdaten lösen eine Meldung aus. Änderungen an Querschnitten und Bildern lösen noch keine aus.
Begrenzte Zahl von Aufrufen
Ein Schlüssel darf 100 Aufrufe in Folge senden. Nach 10 Sekunden Pause zählt das Portal neu.
Keine fertige Shop-Erweiterung
Es gibt kein Plugin für ein Shop-System. Die Anbindung schreibt Ihre IT oder Ihre Agentur.
Nicht das richtige Werkzeug, wenn …
- Niemand bei Ihnen oder Ihrer Agentur programmiert: Dann binden Sie den fertigen Katalog in Ihre Website ein.
- Die Daten sollen direkt aus dem Browser geladen werden.
- Ihr System soll Kabel selbst anlegen, ändern oder veröffentlichen.
Was ist anders, als Daten von Hand zu übertragen?
Verglichen mit heute
Heute pflegt jemand jede Abschrift einzeln; mit der API gibt es nur noch das Original.
Heute trägt eine Person die Daten von Hand in Website, Shop und PIM ein, und zwei der drei Abschriften sind veraltet. Mit der API holen alle drei Systeme denselben Stand aus dem Portal.
Bisher
Von Hand übertragen
Stand der DatenSo alt wie die letzte Abschrift
Mit API
API
Stand der DatenImmer der Stand im Portal
| Merkmal | Von Hand übertragen | Dateien per E-Mail | API |
|---|---|---|---|
| Stand der Daten | So alt wie die letzte Abschrift | Der Stand vom Tag des Versands | Immer der Stand im Portal |
| Ein neues Bild | Jemand lädt es herunter und wieder hoch | Jemand verschickt es erneut | Ihr System holt es über seine Adresse |
| Fehlerquelle | Tippfehler und vergessene Kabel | Alte Dateien bleiben im Umlauf | Keine Abschrift, kein Abschreibfehler |
| Aufwand je Kabel | Jedes Mal von Hand | Jedes Mal eine E-Mail | Keiner nach der Einrichtung |
| Einrichtung | Keine | Keine, nur ein Postfach | Einmal programmieren |
Was brauche ich dafür, und was kostet es?
Was Sie brauchen und was es kostet
Sie brauchen veröffentlichte Kabel, einen Tarif mit API und einen Server, der die Aufrufe sendet.
Was Sie brauchen
Veröffentlichte Kabel
Die API liefert, was im Portal veröffentlicht ist. Ohne veröffentlichte Kabel bleibt die Liste leer.
Ein Tarif mit API
API und Webhooks sind nicht in jedem Tarif enthalten.
Ein Inhaber für die Schlüssel
Nur Inhaber legen Schlüssel und Webhooks an. Eine Firma hat höchstens 10 Empfangsadressen für Webhooks.
Ein eigener Server
Die Aufrufe kommen von Ihrem Server, nie aus dem Browser Ihrer Besucher.
Für Webhooks eine öffentliche Adresse
Das Portal sendet Meldungen nur an eine verschlüsselte Adresse, die aus dem Internet erreichbar ist.
Jemand, der programmiert
Ihre IT oder Ihre Agentur schreibt die Anbindung einmal. Die OpenAPI-Beschreibung hilft dabei.
Was es kostet
Lesende Aufrufe kosten nichts. Bilder, die Ihr System bestellt, kosten dasselbe wie im Portal und stehen auf der Monatsrechnung. Ob API und Webhooks enthalten sind, hängt von Ihrem Tarif ab.
Was wird sonst noch gefragt?
Häufige Fragen
Kurze Antworten auf das, was Entwickler vor dem Start meist noch wissen wollen.
- Ist die API in jedem Tarif enthalten?
- Nein. Ob API und Webhooks enthalten sind, hängt von Ihrem Tarif ab.
- Können wir die API direkt aus dem Browser aufrufen?
- Nein. Die API ist für Aufrufe von Server zu Server gedacht, damit kein Schlüssel im Browser landet.
- Lassen sich Kabel per API veröffentlichen?
- Nein. Veröffentlicht wird im Portal; die API liefert, was veröffentlicht ist, und meldet es per Webhook.
- Wo finden wir die Dokumentation?
- Im Portal unter den Einstellungen zur API, mit einem Beispiel zu jedem Aufruf. Die OpenAPI-Beschreibung ist ohne Schlüssel abrufbar.
- Was passiert, wenn unser Server einen Webhook verpasst?
- Das Portal wiederholt die Meldung mehrmals mit wachsendem Abstand. Danach steht sie im Protokoll, und ein Inhaber sendet sie von Hand erneut.
- Wie prüfen wir, dass eine Meldung vom Portal stammt?
- Jede Meldung trägt eine Signatur aus Ihrem geheimen Wert, dem Zeitpunkt und dem Inhalt. Ihr Server rechnet sie nach und verwirft alte Meldungen.