Koppeling Ecmanage en Inkoopsysteem

Koppeling inkoopsysteem OCI of cXML

Sommige organisaties maken gebruik van inkoopsystemen. Ecmanage kan samen werken met deze systemen als de validatie logica van Ecmanage actief blijft en de winkelwagen van Ecmanage gebruikt wordt op basis van een individuele login van een besteller.

Er zijn twee modellen die we ondersteunen, een OCI variant en een cXML variant.

Opbouw integratie Inkoopsystemen

In het onderstaande schema is weer gegeven hoe de samenwerken kan zijn tussen Inkoopsysteem, Ecmanage en ERP systeem.

De integratie tussen Ecmanage en inkoopsystemen via OCI kan ook werken in een single sign on inrichting. Op deze wijze wordt een besteller direct herkend door Ecmanage zonder apart te hoeven in te loggen. In de cXML variant wordt het inloggen opgelost door middel van een extrinsic en een shared secret.


Template gestuurde winkelwagen OCI

Bij de configuratie van de inkoopsysteem koppeling in Ecmanage kan er door middel van een template een mapping gemaakt worden van de Ecmanage order gegevens naar uw inkoop systeem.

Een voorbeeld:

OCI Field

Value

Toelichting

1

NEW_ITEM-VENDORMAT[1]

58561_6200-34

assortimentid

2

NEW_ITEM-DESCRIPTION[1]

Dames Uniform broek Zwart

3

NEW_ITEM-MATGROUP[1]

BROEK

productgroep

4

NEW_ITEM-QUANTITY[1]

1

5

NEW_ITEM-UNIT[1]

STUK

6

NEW_ITEM-CURRENCY[1]

EUR

7

NEW_ITEM-PRICE[1]

36.55

8

NEW_ITEM-CUST-FIELD1[1]

21

BTW

9

NEW_ITEM-CUST-FIELD3[1]

CUSTDEMO215559

ordercode ecmanage

cXML order flow


De verwerking start als Ecmanage een PunchOutSetupRequest CXML bericht ontvangt van het inkoopsysteem via een POST op een https url van de bestelomgeving in ecmanage.

In dat bericht verwachten wij bijvoorbeeld de volgende data:

  • cXML.Header.From.Credential.Identity = KLANT

  • cXML.Header.To.Credential.Identity = LEVERANCIER

  • cXML.Header.Sender.Credential.SharedSecret = <geheim>

  • cXML.Request.PunchOutSetupRequest.BuyerCookie = <unieke waarde voor deze sessie>

  • cXML.Request.PunchOutSetupRequest.BrowserFormPost.URL = valide url voor post

  • cXML.Request.PunchOutSetupRequest.Extrinsic[name=”User”] = Unieke gebruikernaam die bekend is in Ecmanage.

Als alles valide is dan wordt er een PunchOutSetupResponse cXML bericht gestuurd met de juiste StartPage. Die pagina is maar een aantal uur geldig.

Met de StartPage kan een gebruiker een bestelling starten. Aan het eind wordt de winkelwagen teruggestuurd met een PunchOutOrderMessage. In dat bericht staat het Ecmanage ordernummer veld in cXML.payloadID. Dat is de unieke identificatie van een order in Ecmanage. Het inkoop systeem kan daarna de winkelwagen goedkeuren, in dat geval wordt er een inkoopordernummer gekoppeld aan de winkelwagen en een order bevestiging wordt gestuurd in een PunchOutOrderMessage. De reactie van dat bericht is een status bericht, deze status geeft aan of het bericht correct is (200 is correct, 400 is error de order wordt dan niet verwerkt).


<cXML payloadID="4510976" timestamp="2025-10-23T10:57:28+02:00">
  <Response>
    <Status code="200" text="OK" />
  </Response>
</cXML>

Indien de status niet correct is:

<cXML payloadID="4510999" timestamp="2025-10-23T11:05:16+02:00">
  <Response>
    <Status code="400" text="Bad Request">Ordercode not found in Ecmanage. Perhaps Ordercode is missing or unknown in PO? Please contact Sender as mentioned in Purchase Order (PO):4000177</Status>
  </Response>
</cXML>


Identificatie besteller met optie voor dynamisch aanmaken

Als voorbeeld het volgende fictieve bericht:

<PunchOutSetupRequest operation="create">
<BuyerCookie>1011779435157251</BuyerCookie>
<Extrinsic name="User">john.doe@customer.com</Extrinsic>
<BrowserFormPost>
<URL>https://procurement.customer.com:443/punchout/PunchoutCallBack.jsp?transactionid=1274480137</URL>
</BrowserFormPost>
<Contact>
<Name xml:lang="en-US">Doe, Mr John</Name>
<Email>john.doe@customer.com</Email>
</Contact>
<SupplierSetup>
<URL>https://leverancier.ecmanage.nl/klant/login.aspx?loginwith=cxml</URL>
</SupplierSetup>
</PunchOutSetupRequest>

Om een bestaande gebruiker/besteller te identificeren kijken we naar de Extrinsic "User":
<Extrinsic name="User">john.doe@customer.com</Extrinsic>

Of we kunnen een bestaande gebruiker/besteller identificeren op basis van het kenmerk Email uit de Contact.
De naam van de extrinsic of het gebruiken van Email uit Contact is instelbaar.

Indien deze gebruiker met unieke User naam niet bestaat in de bestelomgeving dan kan deze dynamisch aangemaakt worden, we gebruiken daarvoor de details uit het Contact element.

De onbekende gebruiker kan dan ook direct inloggen op het bestelportaal via cXML. Het Contact gedeelte is optioneel, het Extrinsic gedeelte is voor het bestelplatform verplicht. Zonder Contact informatie kan het zijn dat nieuwe onbekende gebruikers niet kunnen inloggen, de leverancier moet voor die gebruikers handmatig een account aanmaken.

Winkelwagen naar inkoopsysteem

Het volgende bericht is een voorbeeld van het bericht dat gestuurd wordt naar het inkoopsysteem. In dit bericht is zichtbaar dat de ordercode van ecmanage op meerdere plekken gevonden kan worden. Dit is relevant omdat het inkoopsysteem dit veld weer terug dient te sturen bij het bevestigen van een order, zie volgende paragraaf.

<?xml version="1.0" encoding="UTF-8"?>
<cXML payloadID="ECM_12345" timestamp="2026-06-01T14:49:16+02:00">
<Header>
<From>
<Credential domain="NetworkID">
<Identity>DUNS_SUPPLIER</Identity>
</Credential>
</From>
<To>
<Credential domain="NetworkID">
<Identity>DUNS_CUSTOMER</Identity>
</Credential>
</To>
<Sender>
<Credential domain="supplier.ecmanage.eu">
<Identity>PunchoutResponse</Identity>
</Credential>
<UserAgent>Ecmanage</UserAgent>
</Sender>
</Header>
<Message>
<PunchOutOrderMessage>
<BuyerCookie>0a1f4eb4-f011-4b9a-a0ee-aa8c48ba502d</BuyerCookie>
<PunchOutOrderMessageHeader operationAllowed="create">
<Total>
<Money currency="EUR">13.64</Money>
</Total>
<SupplierOrderInfo orderID="ECM_12345"/>
</PunchOutOrderMessageHeader>
<ItemIn quantity="1">
<ItemID>
<SupplierPartID>27.854112_EA</SupplierPartID>
<SupplierPartAuxiliaryID>ECM_12345</SupplierPartAuxiliaryID>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="EUR">13.64</Money>
</UnitPrice>
<Description xml:lang="en">Eyewash Bottle standard 200ml</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification>42171700</Classification>
</ItemDetail>
</ItemIn>
</PunchOutOrderMessage>
</Message>
</cXML>


Terugmelden goedkeuring inkooporder

Voor het terugmelden van een inkoop order die goedgekeurd is kan er gebruik worden gemaakt van een https POST bericht met een cXML payload. In dat cXML bericht staat een verwijzing naar het Ecmanage ordernummer en het inkoop ordernummer, standaard zoeken we naar de volgende velden:

Veld

Waarde

OrderRequestHeader.SupplierOrderInfo[orderID]

Ecmanage ordernummer

OrderRequestHeader[orderID]

Inkoopsysteem ordernummer

Indien het niet lukt om deze velden vanuit het inkoopsysteem te vullen bieden we de volgende 4 alternatieven:


Optie 1: SupplierOrderInfo


<OrderRequest>
<OrderRequestHeader orderID="INKOOP_1234" orderDate="2025-10-03T12:26:52">
<SupplierOrderInfo orderID="ECM_12345"></SupplierOrderInfo>
</OrderRequestHeader>
<ItemOut quantity="1.0000" lineNumber="1">
<ItemID>
<SupplierPartID>ITEM123</SupplierPartID>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="EUR">12.10</Money>
</UnitPrice>
<Description xml:lang="en">
<ShortName>Blue Overall</ShortName>
</Description>
<UnitOfMeasure>EACH</UnitOfMeasure>
</ItemDetail>
    </ItemOut>
</OrderRequest>

Optie 2: OrderRequestHeader  Extrinsic 


<OrderRequest>
<OrderRequestHeader orderID="INKOOP_1234" orderDate="2025-10-03T12:26:52">
          <Extrinsic name="orderID">ECM_12345</Extrinsic>
</OrderRequestHeader>
<ItemOut quantity="1.0000" lineNumber="1">
<ItemID>
<SupplierPartID>ITEM123</SupplierPartID>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="EUR">12.10</Money>
</UnitPrice>
<Description xml:lang="en">
<ShortName>Blue Overall</ShortName>
</Description>
<UnitOfMeasure>EACH</UnitOfMeasure>
</ItemDetail>
    </ItemOut>
</OrderRequest>

Optie 3: Item SupplierPartAuxiliaryID

<OrderRequest>
<OrderRequestHeader orderID="INKOOP_1234" orderDate="2025-10-03T12:26:52">
</OrderRequestHeader>
<ItemOut quantity="1.0000" lineNumber="1">
<ItemID>
<SupplierPartID>ITEM123</SupplierPartID>
<SupplierPartAuxiliaryID>ECM_12345</SupplierPartAuxiliaryID>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="EUR">12.10</Money>
</UnitPrice>
<Description xml:lang="en">
<ShortName>Blue Overall</ShortName>
</Description>
<UnitOfMeasure>EACH</UnitOfMeasure>
</ItemDetail>
    </ItemOut>
</OrderRequest>

Optie 4: ItemDetail  Extrinsic


<OrderRequest>
<OrderRequestHeader orderID="INKOOP_1234" orderDate="2025-10-03T12:26:52">
</OrderRequestHeader>
<ItemOut quantity="1.0000" lineNumber="1">
<ItemID>
<SupplierPartID>ITEM123</SupplierPartID>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="EUR">12.10</Money>
</UnitPrice>
<Description xml:lang="en">
<ShortName>Blue Overall</ShortName>
</Description>
<UnitOfMeasure>EACH</UnitOfMeasure>
               <Extrinsic name="NEW-ITEM-CUST_FIELD3">ECM_12345</Extrinsic>
</ItemDetail>
    </ItemOut>
</OrderRequest>


Veel voorkomende vragen


1. Na het plaatsen van de bestelling komt de order niet in het inkoopsysteem via OCI

In dit geval is de inkoopsessie niet correct gestart. Bij het starten van de inkoopsessie is het de bedoeling dat het inkoopsysteem de gebruiker stuurt naar de inlog pagina van de bestelomgeving met een HOOK_URL parameter in de url van de browser. Deze HOOK_URL bevat het adres waar de winkelwagen naar gestuurd moet worden na het afronden van de winkelwagen. Zonder deze stap wordt de order als een reguliere order verwerkt zonder goedkeuring door het inkoopsysteem.

2. Na het bevestigen van de purchase order uit het inkoopsysteem wordt de order niet verwerkt

Het bevestigen van een inkooporder verloopt door een PurchaseOrder bericht in cXML formaat te sturen naar een url van de bestelomgeving. In dit cXML bericht dient een unieke winkelwagen orderid te staan. Zonder dit gegeven wordt de PurchaseOrder niet verwerkt. Bij het sturen van een onvolledige PurchaseOrder wordt er ook een email met de foutmelding "Ordercode not found in Ecmanage" bericht gestuurd.
 

Voorbeeld Inkoopsystemen

Een aantal voorbeeld integraties op basis van OCI en cXML:


    • Related Articles

    • API voor koppeling HR-systeem

      Sommige klanten hebben de wens om een personeelssysteem te koppelen aan Ecmanage zodat nieuwe medewerkers automatisch aangemaakt worden en kleding kunnen bestellen. Er is de mogelijkheid om een token aan te vragen bij de supportafdeling van Ecmanage ...