Craftsman software (IDS Connect)

This page shows whoever installs craftsman software (Handwerkersoftware) how to connect it to a punchout.dev shop over IDS Connect.

What you need from the shop owner

Item	Typical label in the software	Value
Roundtrip-URL	Roundtrip-URL	https://api.punchout.dev/v1/ids/launch/<shop id>
Username	Benutzername	The credential’s identity
Password	Passwort	The credential’s secret, shown to the shop owner once
Customer number	Kundennummer	Only if your software has no username field (see below)

The shop owner finds the Roundtrip-URL on the shop’s Embed tab under Launch URLs for the buying system, IDS Connect Roundtrip-URL, and creates the credential on the Buyers tab.

If the shop owner limits Allowed return hosts, give them the host name your software receives the cart on.

What to enter in the software

Enter the Roundtrip-URL as shown, without a trailing slash, and the username and password from the shop owner. Where these fields are depends on the package, and its documentation shows the screen.

If your software has no Benutzername field and asks only for a Kundennummer, enter the customer number there and the password as usual. The shop owner then creates the credential with that customer number as its identity. When both fields are filled in, the username counts.

punchout.dev supports only the cart round trip: the user opens the shop from the software, fills the cart and hands it back. Functions such as sending a cart from the software into the shop, opening a specific article or an article search are not offered.

Test the connection

1. Run the software’s connection test, if it has one. punchout.dev answers it without a login, so it confirms the address but not the credentials.
2. Start the punchout from the software.
3. Put two or three articles in the shop’s cart and open the cart page.
4. Check the articles the panel lists and click Transfer to procurement system.
5. Start the punchout again and click Back to procurement system.

What a successful test looks like

• The shop opens with the punchout panel, which reads “Punchout active”.
• On the cart page the panel lists the articles with quantity and price.
• After the transfer, the articles appear in the software with article number, quantity, unit and price.
• After Back to procurement system, the software closes the punchout without adding anything.

If the shop owner set up auto-login for your credential, the craftsman arrives signed in to the shop account mapped to it and sees that account’s prices.

punchout.dev hands prices over the way craftsman software expects. The shop owner sets in the portal whether the shop’s prices include VAT and which VAT rate applies.

When the test fails

What you see	Cause	What to do
A page “Zugang verweigert / Access denied”	The username, customer number or password does not match, or the credential is disabled	Compare them with the shop owner, or ask for a new password
The same page	The shop does not allow the address your software receives the cart on	Give the shop owner your host name; they add it to Allowed return hosts
The same page	The software asked for a function other than the cart round trip	Use the cart round trip only
The same page	The Roundtrip-URL carries a wrong Shop ID	Copy the URL again from the shop owner
A page “Punchout nicht freigeschaltet / Punchout not enabled”	The shop is still in its Sandbox	Nothing on your side. See Plans and Sandbox
The shop opens without the punchout panel	The shop forwards the browser to an address that is not registered for punchout.dev, for example with or without www.	The shop owner adds that address under Allowed origins on the General tab
The transfer button does nothing	The shop’s Content-Security-Policy blocks your software’s return host	The shop owner allows your host in that policy
The software rejects the transferred cart	The cart holds article numbers longer than 15 characters, which some craftsman software cannot process. punchout.dev never shortens an article number, because a shortened number orders the wrong article	Check whether your software accepts longer article numbers, and talk to the shop owner
The transfer fails after a long pause	A punchout lasts four hours	Start the punchout again

The “Access denied” page is deliberately identical for every cause, so it gives nothing away about the shop or the credential. Work through the causes in the order of the table.