Wir unterstützen den PunchOut über das IDS-Connect-Protokoll (Version 2.5). Alle Aktionen der Spezifikation werden unterstützt – mit Ausnahme von Heatinglabel senden (`HLS`). Bitte achten Sie darauf, dass das aufrufende System alle Parameter per HTTP-POST mit dem Encoding `multipart/form-data` übergibt.
---
## Aufruf des PunchOut-Kataloges
| Parameter | HTTP-Parameter | Anmerkung |
|---|---|---|
| Aktionscode | `action` | Pflichtfeld. Bestimmt die aufgerufene Funktion (siehe unterstützte Aktionen). |
| Kundennummer | `kndnr` | Kundennummer des Anwenders beim Lieferanten. |
| Benutzername | `name_kunde` | Benutzername des Anwenders beim Lieferanten. |
| Passwort | `pw_kunde` | Passwort des Anwenders beim Lieferanten. |
| HOOK-URL | `hookurl` | Rücksprungadresse zum aufrufenden System. Muss bei allen Aktionen mit Rückübertragung angegeben werden. |
| Version | `version` | Version der IDS-Schnittstelle. Konstant `2.5`. |
| Target | `target` | Frame, in dem die Aktualisierung nach Abschluss der Rückkommunikation erfolgt. Standard: `TOP`. |
Welche Login-Parameter (Kundennummer, Benutzername, Passwort) tatsächlich benötigt werden, kann über die Aktion `LI` (Logininformationen) abgefragt werden.
---
## Rückgabe an das einkaufende System
Die Rückübertragung des Warenkorbs erfolgt als XML-Struktur an die HOOK-URL – analog zur OCI-Schnittstelle. Der Warenkorb wird im Parameter `warenkorb` als XML übertragen und entspricht dem Schema `Warenkorb_empfangen.xsd`.
Folgende Daten werden pro Position zurückgegeben:
| Feld | XML-Referenz | Anmerkung |
|---|---|---|
| Artikelnummer | `Order/OrderItem/ArtNo` | Großhandelsartikelnummer (Pflichtfeld) |
| Menge | `Order/OrderItem/Qty` | Anfrage- / Angebotsmenge (Pflichtfeld) |
| Mengeneinheit | `Order/OrderItem/QU` | z. B. `PCE` (Stück), `MTR` (Meter) – siehe Codeliste Mengeneinheiten |
| Artikelkurztext | `Order/OrderItem/Kurztext` | Positions- oder Artikelkurztext |
| Artikellangtext | `Order/OrderItem/Langtext` | Ausführliche Artikelbeschreibung |
| Angebotspreis | `Order/OrderItem/OfferPrice` | Brutto- / Listenpreis |
| Nettopreis | `Order/OrderItem/NetPrice` | Einkaufspreis des Kunden |
| Preisbasis | `Order/OrderItem/PriceBasis` | Preis bezieht sich auf „n" Einheiten der Mengeneinheit |
| Mehrwertsteuer | `Order/OrderItem/VAT` | Angabe in % |
| GTIN (EAN) | `Order/OrderItem/EAN` | GTIN des Artikels |
| Positionsnummer Handwerker | `Order/OrderItem/RefItems/Customer` | Referenznummer – wird bei der Verarbeitung nicht verändert |
| Positionsnummer Lieferant | `Order/OrderItem/RefItems/Supplier` | Referenznummer des Großhändlers |
| Rückgabekennzeichen | `WarenkorbInfo/RueckgabeKZ` | `Warenkorbrückgabe` oder `Warenkorbrückgabe mit Bestellung` |
Sie haben die Möglichkeit, für jeden Ihrer PunchOut-Kunden eine eigene Feldzuordnung über das Field-Mapping in PunchCommerce zu konfigurieren.
---
## Unterstützte Aktionen
### Warenkorb empfangen (`WKE`)
Übernahme eines Warenkorbs aus dem PunchOut-Katalog in die Handwerkssoftware. Der Einkäufer wählt Produkte im Katalog aus und übergibt den Warenkorb an die HOOK-URL.
| Parameter | Wert |
|---|---|
| `action` | `WKE` |
| `hookurl` | Rücksprungadresse (Pflicht) |
---
### Warenkorb senden (`WKS`)
Übergabe eines Warenkorbs aus der Handwerkssoftware an den PunchOut-Katalog. Die Warenkorbdaten werden als XML im Parameter `warenkorb` übertragen und müssen dem Schema `Warenkorb_senden.xsd` entsprechen.
| Parameter | Wert |
|---|---|
| `action` | `WKS` |
| `warenkorb` | XML-Warenkorbdaten |
| `hookurl` | Rücksprungadresse (Pflicht) |
---
### Artikeldeeplink (`ADL`)
Direktaufruf der Detailseite eines Artikels anhand der Großhandelsartikelnummer.
| Parameter | Wert |
|---|---|
| `action` | `ADL` |
| `ghnummer` | Großhandelsartikelnummer |
---
### Artikelsuche (`AS`)
Aufruf der Artikelsuche im Katalog. Der Suchbegriff wird als Parameter übergeben, das Suchergebnis wird angezeigt. Ausgewählte Artikel werden über die HOOK-URL an die Handwerkssoftware zurückübertragen.
| Parameter | Wert |
|---|---|
| `action` | `AS` |
| `searchterm` | Suchbegriff (mehrere Begriffe durch Leerzeichen getrennt) |
| `hookurl` | Rücksprungadresse (Pflicht) |
---
### Logininformationen (`LI`)
Abfrage, welche Login-Parameter vom Katalog benötigt werden. Als Antwort wird eine XML-Struktur mit den Feldern `Kundennummer_erforderlich`, `Benutzername_erforderlich` und `Passwort_erforderlich` zurückgegeben (Werte: `true` / `false`).
| Parameter | Wert |
|---|---|
| `action` | `LI` |
**Beispielantwort:**
```xml
false
true
true
```
---
### Schnittstellenversion (`SV`)
Abfrage der unterstützten Versionen der IDS-Schnittstelle.
| Parameter | Wert |
|---|---|
| `action` | `SV` |
**Beispielantwort:**
```xml
2.5
```
---
## Nicht unterstützt: Heatinglabel senden (`HLS`)
Die Aktion `HLS` dient der Übergabe von Artikellisten an eine externe Plattform zur Berechnung von ErP-Energielabels für Verbundanlagen im Heizungsbereich. Diese Funktion liegt außerhalb des PunchOut-Katalog-Kontexts und wird nicht unterstützt.
---
## Unterstützte Shopsysteme
IDS Connect funktioniert mit allen PunchCommerce-Plugins:
- Shopware 6
- Shopware 5
- Magento (Adobe Commerce)
- Spryker
- JTL Shop
- Vendure
- Medusa
---
## Weitere Informationen zum IDS-Connect-Protokoll
Die vollständige Spezifikation der IDS-Schnittstelle (Version 2.5) wird von ITEK in Zusammenarbeit mit dem BVBS (Bundesverband Bausoftware e.V.), der DG Haustechnik und dem Zentralverband Sanitär Heizung Klima herausgegeben.
