Wat is een OCI koppeling?

OCI in twee zinnen

OCI staat voor Open Catalog Interface, een protocol van SAP. Het regelt twee dingen tussen het inkoopsysteem van een klant en de webshop van een leverancier: de inkoper komt ingelogd de webshop binnen, en zijn winkelmand gaat als een rij formuliervelden, de NEW_ITEM-velden, terug naar het inkoopsysteem.

Voor de inkoper vervangt het twee handelingen. Hij hoeft geen aparte inlog bij de leverancier te hebben, en hij typt de bestelling niet over in zijn eigen systeem. Voor zijn werkgever loopt elke bestelling langs budget en goedkeuring. Voor de leverancier is het vaak een eis uit het contract: de klant bestelt alleen nog via zijn inkoopsysteem.

Een OCI koppeling verschilt van de meeste koppelingen op één punt. Een API koppeling verplaatst gegevens tussen twee systemen zonder dat iemand kijkt. OCI loopt via de browser van een mens: beide berichten, de inlog en de winkelmand, reizen mee met een klik van de inkoper.

Hoe werkt een OCI-sessie technisch?

Een sessie heeft drie stappen: de aanroep, het winkelen en de terugkeer.

De aanroep

De beheerder van het inkoopsysteem legt per leverancier een adres en een lijst parameters vast. Klikt de inkoper op de leverancier, dan stuurt zijn browser die parameters naar de webshop. De standaardmethode is POST. De beheerder kan ook GET kiezen, en dan staan alle parameters in de URL:

POST /oci/login HTTP/1.1
Host: webshop.example.nl
Content-Type: application/x-www-form-urlencoded

USERNAME=bakker-oci&PASSWORD=k7Qm2xLp
&HOOK_URL=https%3A%2F%2Finkoop.bakkerinstallatie.example%2Foci%3Fsessie%3D7f3a
&OCI_VERSION=4.0&http_content_charset=iso-8859-1&returntarget=_top

De waarden zijn URL-gecodeerd. De webshop decodeert ze, zoekt de klant bij de gebruikersnaam en bewaart HOOK_URL en returntarget bij de sessie.

Bij de Profit-definitie van AFAS staat de inlog in de URL: het inlogadres in het OCI-profiel bevat de gebruikersnaam en het wachtwoord, en InSite zet HOOK_URL erachter. Zie OCI koppeling AFAS.

De terugkeer

De laatste pagina die de inkoper in de webshop ziet, bevat een HTML-formulier. Het action-attribuut is het retouradres, het target-attribuut de waarde van returntarget, en elke regel van de winkelmand staat erin als verborgen velden met de naam NEW_ITEM-<veld>[<regelnummer>]. De inkoper verstuurt het formulier met een klik, of de pagina doet dat zelf.

Twee details uit de specificatie gaan vaak mis. Het retouradres bevat meestal zelf parameters, zoals sessie=7f3a hierboven. Die horen niet in action te blijven staan: de webshop haalt ze eruit en zet ze als eigen verborgen velden in het formulier. En de pagina met het formulier moet in de tekenset staan die het inkoopsysteem opgaf. Een webshop die UTF-8 stuurt naar een systeem dat iso-8859-1 verwacht, levert "Aansluitdoos 3-polig, geïsoleerd" af als "geïsoleerd". Meer daarover in tekencodering en UTF-8.

Wat zit er wel en niet in OCI?

OCI beschrijft het winkelen en niets daarna.

De rechterkolom is waar het werk zit. De order komt via een andere route terug, meestal als cXML-bericht of als pdf per e-mail. Btw gaat mee in een vrij veld dat per klant wordt afgesproken. Een samengesteld product, zoals een verdeelkast op maat, past niet in de velden: de specificatie noemt als uitwegen een verwijzing naar een offerte in NEW_ITEM-EXT_QUOTE_ID, de lange tekst of een bijlage.

OCI 5.0, uit 2012, bouwt voort op 4.0. De leverancier kan zijn catalogus als JSON naar SAP SRM kopiëren zodat inkopers daar zoeken zonder de webshop te openen, en er zijn twee velden bijgekomen voor een hiërarchie van regels: NEW_ITEM-ITEM_TYPE en NEW_ITEM-PARENT_ID. Voor een webshop die een klant met AFAS of een ander inkoopsysteem aansluit, is het heen en weer van 4.0 wat telt.

Voorbeeld: één artikel in een OCI-winkelmandje

Een inkoper van Bakker Installatie B.V. legt 12 wandcontactdozen in de winkelmand. In de webshop staat de regel zo:

{
  "artikelnummer": "10482",
  "omschrijving": "Wandcontactdoos 2-voudig met randaarde, inbouw, RAL 9010",
  "aantal": 12,
  "eenheid": "stuk",
  "prijs": "17,08",
  "btw": 21
}

Dit is het formulier dat naar het inkoopsysteem gaat:

<form method="post" target="_top"
      action="https://inkoop.bakkerinstallatie.example/oci">
  <input type="hidden" name="sessie" value="7f3a">
  <input type="hidden" name="NEW_ITEM-DESCRIPTION[1]"
         value="Wandcontactdoos 2-voudig met randaarde,">
  <input type="hidden" name="NEW_ITEM-QUANTITY[1]" value="12">
  <input type="hidden" name="NEW_ITEM-UNIT[1]" value="PCE">
  <input type="hidden" name="NEW_ITEM-PRICE[1]" value="17.08">
  <input type="hidden" name="NEW_ITEM-CURRENCY[1]" value="EUR">
  <input type="hidden" name="NEW_ITEM-VENDORMAT[1]" value="10482">
  <input type="hidden" name="NEW_ITEM-CUST_FIELD1[1]" value="21">
</form>

Vier dingen zijn onderweg veranderd:

1. De omschrijving. Het veld is 40 tekens lang, de omschrijving 56. Er vallen 56 - 40 = 16 tekens af: "inbouw, RAL 9010". Verkoopt de webshop dezelfde doos ook als opbouw, dan hebben beide regels in het inkoopsysteem dezelfde tekst.
2. De eenheid. "stuk" wordt PCE. Het veld is 3 tekens lang en SAP eist een ISO-code die in het inkoopsysteem is ingericht.
3. De prijs. De komma wordt een punt, het euroteken wordt een eigen veld met EUR. Het regelbedrag is 12 × 17,08 = 204,96 exclusief btw.
4. De btw. Het percentage staat in een vrij veld, hier NEW_ITEM-CUST_FIELD1 zoals AFAS het leest. Het inkoopsysteem rekent er 21% van 204,96 = 43,04 bij en komt op 248,00.

Het eerste punt is geen fout van het inkoopsysteem. De oplossing ligt bij de leverancier: een korte omschrijving van hoogstens 40 tekens per artikel waarin het onderscheid vooraan staat, bijvoorbeeld "WCD 2V RA inbouw RAL9010". De volledige tekst kan mee in het veld voor lange tekst, dat geen maximale lengte heeft.

Wat betekent dit voor je webshop?

De specificatie is kort. Het werk zit in wat eromheen moet: een inlogadres per klant, een sessie die de juiste prijzen laadt, een overdracht in plaats van een kassa, omschrijvingen en eenheden die in de velden passen, en een adres dat de order daarna aanneemt. Elk inkoopsysteem leest net andere velden, en dat blijkt pas bij de eerste proefsessie met de klant.

Wij bouwen dat als koppeling op je webshop en draaien en bewaken hem daarna. Het verloop van een bestelling en wat elke kant levert staat op OCI en PunchOut; wat je webshop zelf moet kunnen op OCI koppeling webshop. Vertel welk inkoopsysteem je klant gebruikt, dan hoor je welke velden en welke orderroute daarbij horen.