Kun je software koppelen die geen API heeft?

Ja, langs vier routes

Een API koppeling is de kortste weg, niet de enige. Oudere ERP-pakketten, boekhoudsoftware op een eigen server en de portalen van leveranciers hebben vaak geen REST API. Ze hebben bijna altijd wel een andere uitgang. In volgorde van voorkeur:

De volgorde volgt uit twee dingen: hoe vers de gegevens zijn en hoeveel er stuk kan gaan zonder dat iemand het merkt. Een SOAP-service geeft een foutcode als iets misgaat. Een bestand dat niet aankomt geeft niets. Een portaal dat een knop verplaatst geeft ook niets, en het script leest daarna een lege pagina.

Een koppeling gebruikt vaak twee routes naast elkaar. Voorraad komt elke nacht als bestand, orders gaan via de importmap terug. Of het ERP wordt gelezen via een databaseweergave en beschreven via de importfunctie van het pakket.

SOAP en de database: de routes die op een API lijken

SOAP

SOAP is de oudere van de twee gangbare vormen van webservices. Versie 1.2 is vastgelegd door het W3C; de tweede editie is van 27 april 2007. Een vraag is een XML-bericht met een vaste envelop: een Header voor de aanmelding en een Body voor de vraag zelf. Een fout komt terug als Fault. Welke functies er zijn staat in een WSDL-bestand dat het pakket zelf aanbiedt.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Header>
    <SessionId>4f1c9a52</SessionId>
  </soap:Header>
  <soap:Body>
    <GetStock>
      <ItemCode>KB-2210</ItemCode>
      <Warehouse>1</Warehouse>
    </GetStock>
  </soap:Body>
</soap:Envelope>

Voor de koppeling is dit een API met meer tekst per bericht. De envelop hierboven is 10 regels voor een vraag die in REST één regel is. Het werk zit in de aanmelding (vaak een sessie die na een aantal minuten verloopt en opnieuw moet worden aangevraagd) en in de datatypen: een bedrag als 12.50, een datum zonder tijdzone, een leeg veld dat als ontbrekend element of als lege tekst terugkomt. Die drie staan in de WSDL en worden per veld vastgelegd.

Een alleen-lezen weergave op de database

Een pakket dat op een eigen server draait, bewaart alles in een database. De beheerder kan daarop een weergave (view) maken met precies de kolommen die de koppeling nodig heeft, en een account dat alleen die weergave mag lezen. Voor voorraad zijn dat bijvoorbeeld 4 kolommen: artikelnummer, magazijn, voorraad en gereserveerd.

Drie regels houden deze route veilig:

• Alleen lezen. Schrijven in tabellen gaat langs de controles van het pakket heen. Een order die rechtstreeks in de ordertabel wordt gezet, krijgt geen nummer uit de nummerreeks, geen btw-berekening en geen reservering.
• Een weergave, geen tabellen. Bij een update van het pakket kunnen tabellen en kolommen veranderen. De beheerder past de weergave aan; de koppeling blijft dezelfde 4 kolommen lezen.
• Lezen op een kopie als de belasting telt. Een vraag over 15.000 artikelen om de 15 minuten is 96 keer per dag een volledige tabel. Op een alleen-lezen kopie van de database merkt de administratie daar niets van.

Schrijven gaat bij deze route via de importfunctie van het pakket zelf, meestal een bestand in een importmap. Daarmee komt route 3 in beeld.

Bestanden uitwisselen zonder verrassingen

De meest gebruikte route zonder API is de geplande export: het pakket zet op vaste tijden een CSV- of XML-bestand op een SFTP-server, en de koppeling haalt het op. SFTP loopt over SSH, standaard op poort 22, met een sleutel in plaats van een wachtwoord. Het verschil met een API of een feed is dat er geen antwoord terugkomt. Vier dingen gaan mis als er geen regel voor is.

Het derde geval in getallen. Het ERP schrijft om 02:00:00 een bestand van 15.000 regels en doet daar 40 seconden over: 375 regels per seconde. Een koppeling die om 02:00:20 kijkt, vindt een bestand met 20 × 375 = 7.500 regels. Er komt geen foutmelding, want een half CSV-bestand is ook een geldig CSV-bestand.

De andere 7.500 artikelen ontbreken. Geldt voor deze bron de regel dat een artikel dat ontbreekt op 0 gaat, dan staat om 02:01 de helft van het assortiment op uitverkocht. De koppeling heeft daarom twee controles. Hij leest alleen bestanden die niet meer .tmp heten. En hij vergelijkt het aantal regels met de vorige ronde: bij een daling van meer dan bijvoorbeeld 10% (hier van 15.000 naar minder dan 13.500) wordt het bestand niet verwerkt en gaat er een melding uit.

/export/voorraad_20261002_0200.csv        15.000 regels   verwerkt, naar /archief
/export/voorraad_20261003_0200.csv.tmp     7.500 regels   wordt geschreven, overslaan

Het vierde geval is het geval dat het langst onopgemerkt blijft. Een export die op vrijdagnacht stopt, valt zonder controle pas op als een klant maandag iets bestelt dat zaterdag is uitverkocht: 72 uur op oude voorraad. De controle is simpel. Het bestand hoort er om 02:30 te zijn; is het er om 03:00 niet, dan gaat er een melding uit. Wat er verder in leveranciersbestanden misgaat (scheidingstekens, tekenset, kopregels) staat in CSV- en Excel-bestanden van leveranciers.

Schrijven via bestanden werkt omgekeerd: de koppeling zet een orderbestand in de importmap en het pakket leest het in. Een ontvangstbevestiging is er niet. De koppeling controleert daarom in de volgende export of de order met het ordernummer van de webshop erin staat, en meldt een order die na 2 rondes nog ontbreekt.

Portalen zonder export

Een deel van de leveranciers heeft alleen een dealerportaal: een website met een login waar je per artikel de voorraad opzoekt. Geen export, geen API. Dit is route 4, en hij wordt per portaal beoordeeld. Drie vragen bepalen of het kan:

• Wat staat er in de afspraak met de leverancier? Het script gebruikt jouw account. De leverancier hoort te weten dat het gebeurt.
• Hoe logt het portaal in? Een gebruikersnaam en wachtwoord zijn te automatiseren. Een code per sms bij elke aanmelding niet zonder medewerking van de leverancier.
• Hoeveel pagina's zijn het? Het script gedraagt zich als een bezoeker en wacht tussen twee pagina's.

De rekensom bij de derde vraag: 1.200 artikelen met elk een eigen pagina en 3 seconden tussen twee pagina's is 3.600 seconden, dus 60 minuten per ronde. Dat past één keer per nacht. Elk kwartier past niet. Heeft het portaal een lijstpagina met 50 artikelen per pagina, dan zijn het 24 pagina's en 72 seconden.

Een script breekt als het portaal verandert. Een kolom die van plaats wisselt, levert zonder controle een levertijd op in het voorraadveld. De koppeling controleert daarom per ronde of de pagina de verwachte opbouw heeft en of het aantal gevonden artikelen overeenkomt met de vorige ronde, en schrijft bij een afwijking niets weg. De webshop houdt dan de laatste goede stand en er gaat een melding uit.

Voor veel portalen is er een tussenweg. Een leverancier die geen export op SFTP wil zetten, kan vaak wel elke ochtend een bestand mailen. Een bijlage in een vaste mailbox is voor de koppeling route 3, met dezelfde vier controles. Meer over bronnen van leveranciers staat bij leveranciersvoorraad koppelen.

Soms is vragen de kortste weg

Een concrete vraag aan de leverancier van het pakket of aan de groothandel levert vaak meer op dan een technische omweg. De vraag of er een API is, levert een nee op. Deze vraag kan iemand die het pakket beheert met ja beantwoorden:

Kunnen jullie elke nacht om 02:00 een CSV-bestand op een SFTP-map zetten met:
artikelnummer, EAN, vrije voorraad, verwachte leverdatum
Bestandsnaam met datum, puntkomma als scheidingsteken, UTF-8.

Dat zijn 4 velden, 1 tijdstip en 3 afspraken over de vorm. In een pakket met een exportmodule is dit een instelling.

Twee dingen om na te vragen voordat je concludeert dat er geen API is. Bij een aantal pakketten is de API een aparte module of hoort hij bij een hoger abonnement, en staat hij dus uit en niet afwezig. En een API die er wel is, kan het veld missen dat je nodig hebt, zoals een staffelprijs of een verwachte leverdatum. Dan komt dat ene veld alsnog via een export en de rest via de API.

Beschikbare gegevens en fouten in leveranciersbestanden

De naam van het pakket zegt weinig over de vraag of het te koppelen is. Bepalend is of er een vaste, herhaalbare manier is om gegevens eruit te halen en erin te zetten. Daar zijn vier routes voor, in volgorde van voorkeur:

Een API hebben is iets anders dan de velden krijgen die je nodig hebt. Een geval dat vaak voorkomt: orders en artikelen zitten in de API, de staffelkorting die je met een klant hebt afgesproken niet. Die komt dan uit een prijslijst die het ERP wel kan exporteren en wordt onderweg aan de order toegevoegd.

Bij bestanden zit het werk in de details. Hieronder de kopregel en één artikel uit een leveranciersbestand: eerst zoals de leverancier het aanlevert, daarna hetzelfde artikel nadat iemand het bestand in Excel heeft geopend en opgeslagen.

artikelnr;ean;omschrijving;voorraad;prijs
00482;8712345678906;Koppelstuk 22 mm messing;14;12,50
482;8,71235E+12;Koppelstuk 22 mm messing;14;12,5

De voorloopnullen van het artikelnummer zijn weg en de EAN is afgerond tot 8,71235E+12. Het artikel wordt in de webshop niet meer gevonden, niet op artikelnummer en niet op EAN. Een foutmelding komt er niet: de voorraad van dat artikel wordt niet meer bijgewerkt.

Een koppeling op bestanden regelt daarnaast vier dingen: unieke bestandsnamen, het archiveren van verwerkte bestanden, het overslaan van een bestand dat nog geschreven wordt, en merken dat de export van vandaag niet is aangekomen. Dat laatste is de fout die een leveranciersfeed een week ongemerkt stil kan leggen. Meer hierover staat in koppelen zonder API, CSV en Excel van leveranciers en voorraad van je leverancier koppelen.

Wat betekent dit voor je koppeling?

Bij een systeem zonder API bouwen wij de koppeling op de uitgang die het systeem wel heeft, met de controles die bij die route horen: unieke bestandsnamen, een archief, een melding bij een ontbrekend of gekrompen bestand, en een wachtrij zodat een order niet stil verdwijnt. Daarna draaien en bewaken wij hem. In het dashboard zie je per ronde welk bestand is verwerkt en hoeveel regels erin zaten.

Verandert de bron, bijvoorbeeld een nieuwe kolom in de export of een portaal met een nieuwe opbouw, dan passen wij de koppeling aan. De aanpak voor systemen buiten de standaardlijstjes staat op maatwerk koppeling laten maken, het overzicht van alle stromen op koppelingen. Vertel welk systeem het is, dan hoor je langs welke route het kan.