IDS (Integrierte Daten-Schnittstelle) ist eine standardisierte Schnittstelle zwischen einem Online-Shop und einer Handwerkersoftware. Sie ermöglicht zwei zentrale Arbeitsabläufe:
- Übergabe aus der Handwerkersoftware in den Shop (Warenkorb-Import): Die Handwerkersoftware übergibt eine Artikelliste als XML-Warenkorb an den Shop. Der Shop übernimmt die Positionen, der Handwerker kann die Bestellung direkt abschließen.
- Rückübermittlung vom Shop in die Handwerkersoftware: Nach dem Warenkorb-Import oder Bestellabschluss im Shop werden die Positionen zurück an die Handwerkersoftware übergeben (z.B. für Angebots-erstellung oder Auftrags-bestätigung).
Der Einstiegspunkt ist immer /ids. Die Schnittstelle wird mit dem Shop-Merkmal IDS-Schnittstelle aktiviert. Der Nutzer wird beim Aufruf anhand der übergebenen Zugangsdaten (name_kunde / pw_kunde) automatisch eingeloggt. Um direkt gesamte Belege per IDS übermitteln zu können, müssen die entsprechenden Shop-Merkmale zusätzlich aktiviert werden.
Unterstützte IDS-Versionen: 1.3, 2.0 und 2.5.
Automatisch Einrichtung (ITEK / o-connect)
Für Händler, die am ITEK-Verzeichnis (auch bekannt als o-connect oder zentrales Händlerverzeichnis) teilnehmen, kann die IDS-Anbindung vollautomatisch durch die Handwerkersoftware eingerichtet werden:
- Der Händler beantragt eine IDS-Händlernummer bei der ITEK.
- Die Händlernummer und die zugehörige Shop-URL werden im zentralen Händlerverzeichnis hinterlegt.
- Die Handwerkersoftware des Handwerkers schlägt über dieses Verzeichnis anhand der Händlernummer automatisch die korrekte IDS-URL nach – ohne dass der Handwerker oder der Händler die URL manuell eintragen muss.
Manuelle Einrichtung (per URL)
Wenn keine automatische Einrichtung über das ITEK-Verzeichnis genutzt wird, kann die IDS-Anbindung auch manuell eingerichtet werden. Der Händler teilt dem Handwerker bzw. dem Hersteller der Handwerkersoftware die direkte IDS-URL des Shops mit:
https://<shop-url>/ids
Die Handwerkersoftware trägt diese URL direkt als Lieferanten-Endpunkt ein. Zugangsdaten (Benutzername und Passwort) werden dabei als URL-Parameter übergeben und müssen dem tatsächlichen Shop-Konto des Handwerkers entsprechen.
Die IDS-Schnittstelle wird über den Endpunkt /ids angesprochen. Der Aktions-Parameter heißt action. Folgende Aktionen werden unterstützt:
| Aktion | Bedeutung |
|---|---|
WKS |
Warenkorb-Import: Die Handwerkersoftware übergibt einen XML-Warenkorb (warenkorb-Parameter) an den Shop. Der Shop übernimmt die Positionen und leitet zur Warenkorb-Seite weiter. Enthält der Aufruf eine hookurl, wird der Warenkorb nach dem Kauf zurück an die Handwerkersoftware übermittelt (Hybrid-Modus). |
WKE |
Warenkorb-Empfang: Wie WKS, aber der Shop soll den Warenkorb
explizit zurückübermitteln. Ein mitgelieferter XML-Warenkorb wird ebenfalls
eingelesen.
|
AS |
Artikelsuche: Öffnet den Shop mit einem vorausgefüllten Suchbegriff (searchterm-Parameter). Leitet zum Navigator oder zur alten Suche weiter, je nach Shop-Konfiguration. Wenn ids.enableIdsCheckoutOnSearchAction = true aktiviert ist, wird auch der IDS-Checkout-Modus gesetzt. |
ADL |
Artikel-Deeplink: Öffnet direkt die Detailseite eines Artikels anhand der übergebenen Artikelnummer (ghnummer-Parameter). Wird genau ein Treffer gefunden, erfolgt eine direkte Weiterleitung. Andernfalls wird eine Suchergebnisseite geöffnet. |
LI |
Login-Informationen: Gibt per XML zurück, welche Anmeldedaten der Shop erwartet (Benutzername und Passwort erforderlich, Kundennummer nicht). |
SV |
Unterstützte Versionen: Gibt per XML die unterstützten IDS-Versionen zurück (aktuell: 1.3, 2.0, 2.5). |
Authentifizierungsparameter, die bei allen Aktionen übergeben werden können:
| Parameter | Bedeutung |
|---|---|
name_kunde |
Benutzername / E-Mail-Adresse des Shop-Nutzers |
pw_kunde |
Passwort des Shop-Nutzers (URL-kodiert übergeben) |
hookurl |
Rückgabe-URL der Handwerkersoftware für die Übermittlung. Wird in der Session gespeichert und bei der Übermittlugn aufgerufen. Fehlt dieser Parameter, gelangt man in den Debug-Modus. |
target |
Ziel-Frame für die Rückgabe (Standard: _top).
|
Bei den Aktionen WKS und WKE übergibt die Handwerkersoftware
einen XML-Warenkorb als POST-Parameter warenkorb.
Folgende XML-Felder werden ausgewertet:
| XML-Pfad | Bedeutung |
|---|---|
WarenkorbInfo/Version |
IDS-Version (setzt die Session-Version) |
Order/OrderInfo/Kommission |
Kommission / Warenkorb-Bezeichnung |
Order/OrderInfo/InquiryNo |
Anfrage-Nummer (wird als externe Warenkorb-ID verwendet: I-{Nr}) |
Order/OrderInfo/PartNo |
Auftrags-Nummer (wird als externe Warenkorb-ID verwendet: P-{Nr}) |
Order/OrderInfo/DeliveryDate |
Gewünschtes Lieferdatum (ISO-Format) |
Order/OrderInfo/DeliveryWeek + DeliveryYear |
Gewünschte Lieferwoche (alternativ zu DeliveryDate) |
Order/OrderItem |
Artikelposition (mehrfach vorhanden) |
Order/OrderItem/ArtNo |
Artikelnummer |
Order/OrderItem/Qty |
Menge (muss größer 0 sein) |
Order/OrderItem/QU |
Mengeneinheit |
Order/OrderItem/Kurztext |
Kurztext |
Order/OrderItem/Divers |
true = freie Position (Divers-Artikel) |
RefItems/Customer |
Kundenreferenznummer der Position |
RefItems/CustomerSubNo |
Kundenreferenz-Unterposition |
Order/DeliveryPlaceInfo/Address |
Lieferadresse (Name1/2/3, Street, PCode, City, Country) |
Neue Session bei jedem Aufruf
Wird beim IDS-Aufruf kein hookurl-Parameter übergeben, setzt der Shop automatisch /ids/debug als Rückgabe-URL in die Session. Klickt der Nutzer dann im Brwoser auf "per IDS übermitteln" wird an /ids/debug weitergeleitet – der Browser zeigt dort den rohen XML-Warenkorb an, den der Shop zurückübermittelt hätte.
Dies ist nützlich, um die Rückübermittlung zu testen, ohne eine echte Empfänger-URL einer Handwerkersoftware zu benötigen:
https://<shop-url>/ids?action=WKS&name_kunde=...&pw_kunde=...
(ohne hookurl) – nach dem Kauf landet man auf /ids/debug und sieht den übertragenen XML-Warenkorb.
Fehlerseite
Bei Problemen mit dem Session-Zustand (z.B. wenn der Nutzer nicht eingeloggt ist, obwohl eine IDS-Session gestartet wurde, oder wenn eine alte Session „hängt") kann die Session manuell zurückgesetzt werden:
https://<shop-url>/session/reset
Dieser Aufruf löscht die aktuelle Browser-Session vollständig. Danach kann ein neuer IDS-Aufruf gestartet werden. Dies ist häufig der erste Diagnoseschritt, wenn der Nutzer nach einem IDS-Aufruf nicht korrekt eingeloggt erscheint oder im falschen Zustand landet.
Konfiguration: Alte Session invalidieren
IDS-Profile ermöglichen es, das Verhalten der Schnittstelle für bestimmte Handwerkersoftware-Hersteller oder Kunden anzupassen.
Über Profile lassen sich z.B. folgende Einstellungen steuern:
- Abweichende Rückgabe-Formate für die Rückübermittlung
- Einschränkungen der erlaubten Aktionen
Hinweis
Symptom: Der Shop öffnet sich, aber der Nutzer landet auf der Login-Seite oder ist nicht eingeloggt, obwohl Zugangsdaten übergeben wurden.
Mögliche Ursachen und Lösungen:
- Benutzername (name_kunde) oder Passwort (pw_kunde) in der IDS-URL sind falsch. -> Zugangsdaten prüfen.
- Das Kundenkonto existiert nicht oder ist gesperrt. -> Konto im Backend prüfen.
-
URL-Encoding-Problem: Sonderzeichen im Passwort wurden nicht korrekt kodiert.
-> Passwort URL-enkodieren (z.B.
@->%40,#->%23). - Alte Session im Browser vorhanden. -> /session/reset aufrufen und erneut versuchen.
Symptom: Der Handwerker sieht im Shop andere Preise als erwartet.
Mögliche Ursachen und Lösungen:
- Preismodus prüfen: Der angezeigte Preis hängt vom eingeloggten Konto und dem diesem Konto zugewiesenen Preismodus ab (z.B. Listenpreise, Nettopreise, keine Preise). -> Im Frontend den Preismodus ändern (falls möglich) oder im Backend am Kunden den Preismodus prüfen.
- Der Nutzer ist trotz übergebener Zugangsdaten nicht korrekt eingeloggt und sieht deshalb öffentliche Preise statt Kundenpreise. -> Login-Zustand prüfen (s.o.).
Symptom: Im Shop ist keine Schaltfläche zum Übergeben an die Handwerkersoftware sichtbar (per IDS übermimtteln).
Mögliche Ursachen und Lösungen:
- Keine aktive IDS-Session: Der IDS-Button wird nur angezeigt, wenn der Shop über eine IDS-URL geöffnet wurde und dabei eine hookurl übergeben wurde. Wird der Shop direkt im Browser aufgerufen, gibt es keine IDS-Session. -> Sicherstellen, dass der Shop via IDS-URL aus der Handwerkersoftware heraus geöffnet wird.
- Nutzer ist nicht eingeloggt. -> Login-Zustand prüfen (s.o.).
- Das Shop-Merkmal IDS ist nicht aktiviert. -> Im Backend unter Shop-Merkmale prüfen.
Symptom: Eine oder mehrere Positionen aus dem XML-Warenkorb landen nicht im Warenkorb, der Shop zeigt eine Fehlermeldung.
Mögliche Ursachen und Lösungen:
- Die Artikelnummer im XML-Feld ArtNo ist dem Shop nicht bekannt. -> Artikelnummer prüfen; falls freie Positionen gewünscht sind, muss Divers=true gesetzt und die Einstellung ids.userDefinedItemWhenNotPresentPermission = "enabled" aktiviert sein.
- Die übergebene Menge (Qty) ist 0 oder negativ. -> Menge prüfen.
Damit ein IDS-Problem schnell und effizient bearbeitet werden kann, sollte bei jeder Supportanfrage zu IDS Folgendes mitgeteilt werden:
- Shop: URL oder Name des betroffenen Shops
- Kundennummer: Die Kundennummer des betroffenen Nutzers im Shop
- Handwerkersoftware: Name der Software
- Artikel / Angebot / Use-Case: Welcher Artikel oder welches Angebot ist betroffen? Was genau wurde versucht (z.B. Warenkorb übergeben, Angebot übertragen)?
- Fehlerbeschreibung: Was passiert tatsächlich? Was wurde erwartet?
- Screenshot / Fehlermeldung: Falls vorhanden