Een API-koppeling met Excel: wanneer werkt dat en wanneer niet?

1. Wat deze gids wel en niet doet

Deze gids gaat over de beslissing en de test, niet over klikinstructies. Microsoft beschrijft in de eigen documentatie een webconnector waarmee Excel via Power Query gegevens van een webadres kan ophalen, plus een aparte pagina over het oplossen van fouten met die connector. Die documentatie is de bron voor de mogelijkheid; welke knop op jouw scherm staat, hangt af van je exacte Excel-editie en dat controleer je apart voordat je iets vastlegt.

Wat hier buiten scope blijft: een belofte dat een bepaalde koppeling "ondersteund" is, een universeel stukje verbindingscode, en het idee dat een gelukte proef op één laptop hetzelfde is als een beheerde productiestroom. Een geslaagde ophaalactie bewijst die ene bron, op dat moment, met die ene account.

Gebruik dit stuk om te kiezen tussen drie routes:

2. Lezen of schrijven: kies de richting eerst

De belangrijkste vraag is niet "welke API", maar "welke kant op bewegen de gegevens en wie is leidend".

Lezen is de veiligste start. Excel haalt een kopie op, jij rekent of rapporteert, en het bronsysteem verandert niet. Als de bron per ongeluk niet bereikbaar is, mist je werkmap hooguit een verversing. Power Query is hiervoor bedoeld: het bevraagt een adres, zet het antwoord om in een tabel en herhaalt dat op verzoek.

Schrijven vanuit Excel is een andere opdracht. Een werkmap die records aanmaakt of wijzigt in een ander systeem, kan bij een dubbele verversing dezelfde order twee keer versturen, verkeerde regels overschrijven of een halve batch achterlaten. Wil je dit toch, dan hoort daar een testomgeving bij, een vaste externe identificatie per record en een controle of een actie al is uitgevoerd. Doe schrijftests nooit met echte klantgegevens.

Tweerichting combineert beide risico's en voegt conflictregels toe: als hetzelfde veld in Excel en in het bronsysteem verandert, moet vooraf vaststaan welke wint of wie het conflict beoordeelt. In de praktijk is dit zelden nog een Excel-taak.

Voor de meeste mkb-vragen is het antwoord: begin read-only, en behandel schrijven als een apart besluit met eigen acceptatiecriteria.

3. Verversen, authenticatie en waar je geen geheimen bewaart

Een koppeling die alleen werkt terwijl jij ernaast zit, is geen koppeling maar een handmatige stap met extra techniek.

Voor verversen beslis je vooraf:

• hoe actueel de gegevens moeten zijn: bij openen, één keer per dag, of elk uur;
• of de verversing op een gedeelde, beheerde plek draait of op één persoonlijke computer;
• wat er zichtbaar gebeurt als een verversing mislukt, zodat niemand met stille oude cijfers verder werkt.

Voor authenticatie geldt: een openbare documentatiepagina bewijst niet dat jouw account toegang heeft. Breng in kaart welke methode de bron vraagt (bijvoorbeeld een sleutel in een header of een token dat periodiek verloopt), welk account de koppeling gebruikt, wie eigenaar is van dat account en hoe toegang wordt ingetrokken als iemand vertrekt. Microsoft beschrijft bij het oplossen van webconnector-fouten ook problemen met referenties en autorisatie. Leg daarom vast hoe toegang wordt vernieuwd en wie een mislukte vernieuwing opvolgt.

Bewaar geen geheimen in de werkmap zelf. Zet geen sleutels, tokens of wachtwoorden in cellen, in de querytekst of in een tabblad "config". Een werkmap wordt gemaild, gekopieerd en in back-ups bewaard; een sleutel daarin lekt mee. Verwijs naar een afgesproken veilige plek en laat de sleutel daar staan.

4. Schemawijziging en limieten: wat je test

Twee dingen breken een werkende koppeling vaak zonder waarschuwing: de bron verandert zijn structuur, of de bron begrenst hoeveel je mag opvragen.

Schemawijziging betekent dat een veld wordt hernoemd, verplaatst, verwijderd of van type verandert. Power Query onthoudt vaak vaste kolomnamen en volgorde; als de bron "besteldatum" hernoemt naar "order_date", kan een kolom leeg worden of kan de verversing stoppen. Test daarom:

• of alle verwachte velden aanwezig zijn en gevuld;
• of het aantal opgehaalde records klopt met een onafhankelijk brontotaal;
• of er geen dubbele sleutelwaarden binnenkomen;
• wat er gebeurt bij een onbekend of extra veld.

Limieten (vaak rate limits genoemd) beperken het aantal verzoeken per minuut of per dag. Bij gepagineerde antwoorden haalt één verversing meerdere pagina's op; dat telt op. Reken vooraf uit hoeveel verzoeken één verversing kost en hoeveel verversingen per dag draaien, en vergelijk dat met de toegestane limiet. Kom je in de buurt, dan is vaker verversen geen kleine instelling maar een risico op geblokkeerde of onvolledige data.

Leg de bedoelde regels apart vast van wat je daadwerkelijk waarnam. Een bedoelde regel is "de verversing haalt 150 records op"; een waarneming is "vandaag kwamen er 148 binnen". Het verschil is precies wat een acceptatietest zichtbaar maakt.

5. Eigenaarschap: wie beheert de koppeling

Een koppeling zonder eigenaar wordt een stille storing. Wijs vóór livegang vier rollen aan, ook als één persoon meerdere rollen vervult:

• proces-eigenaar: bepaalt welke gegevens nodig zijn en wat zakelijk correct is;
• data-eigenaar: bewaakt veldbetekenis, toegestane waarden en kwaliteit;
• technisch eigenaar: onderhoudt de query, de verversing en de toegang;
• operationeel eigenaar: ziet mislukte verversingen en handelt ze af.

Leg ook vast waar de werkmap staat, wie hem mag wijzigen en of de verversing op een gedeelde omgeving draait in plaats van op de laptop van één medewerker. Een koppeling die aan een persoonlijk account of één toestel hangt, valt weg zodra die persoon weg is.

Voor het bredere plaatje, waarin deze koppeling één stap is in een grotere werkstroom, is de route bedrijfsprocessen automatiseren bedoeld. Wil je eerst bepalen welke administratieve taken zich hier überhaupt voor lenen, dan helpt de gids administratie automatiseren.

6. Stopcriteria: wanneer je niet zelf verder gaat

Stop met de zelfbouw en leg de vraag bij een verantwoordelijke of specialist wanneer een van deze punten geldt:

• de koppeling moet schrijven of tweerichting zijn, en er is geen testomgeving;
• de bron biedt geen toegestane, gedocumenteerde toegang voor jouw account;
• geheimen zouden in de werkmap of in een gedeeld bestand terechtkomen;
• de bedoelde verversfrequentie komt in de buurt van de limiet van de bron;
• een schemawijziging heeft de stroom al een keer stil gebroken zonder melding;
• niemand kan de vier eigenaarsrollen invullen;
• de gegevens sturen facturen, betalingen of voorraad aan zonder controlestap.

Een werkende ophaalactie is geen bewijs dat de stroom beheersbaar is. Gebruik deze controle niet als goedkeuring voor een proces waarin fouten geld of klantvertrouwen kosten.

7. Fictief voorbeeld: de bestelstroom van Atelier Meridiaan (.example)

Stel: een fictief atelier, Atelier Meridiaan, wil elke ochtend de bestellingen van de vorige dag in Excel zien om de productie te plannen. Het bronsysteem biedt een read-only adres, hier alleen ter illustratie geschreven als api.meridiaan-orders.example/v1/orders. Alle namen, adressen en waarden zijn verzonnen.

De bedoelde afspraken:

• richting: alleen lezen; Excel verandert niets in het bronsysteem;
• verversing: één keer per dag om 07:00, op een beheerde omgeving, niet op een laptop;
• authenticatie: een token uit de afgesproken wachtwoordkluis, niet in de werkmap;
• omvang: het antwoord komt in 3 pagina's van 50 records, dus 150 bestellingen op een normale dag, met een piek tot 200;
• verzoeken per verversing: 3 pagina's plus 1 telcontrole, samen 4 verzoeken;
• limiet van de bron: 60 verzoeken per minuut, dus 4 verzoeken per ochtend blijft ruim binnen de grens;
• acceptatie: het aantal opgehaalde records is gelijk aan het brontotaal, er zijn geen dubbele order-id's en de verplichte velden zijn gevuld.

Wat de eerste proef opleverde (fictieve waarneming): er kwamen 148 records binnen in plaats van 150. Tijdens een gefaseerde wijziging gebruikten de laatste twee bronrecords al het nieuwe veld "order_date", terwijl de andere 148 nog "besteldatum" gebruikten. De datumfilter sloeg daardoor precies die twee regels over. Verschil: 150 verwacht min 148 ontvangen is 2 gemiste records. Resultaat: afgekeurd, want het aantal klopt niet en de bron leverde twee schema-versies door elkaar.

Het vervolg: de technisch eigenaar past de query aan op de nieuwe veldnaam, voegt een controle toe die stopt bij een onbekende kolom, en draait de test opnieuw. Pas als 150 gelijk is aan 150 en er geen dubbele id's zijn, gaat de stroom naar dagelijks gebruik. Dit is een tafeloefening, geen uitgevoerde klantkoppeling.

8. Vul het keuze- en testblad in en kies je vervolg

Gebruik het bijbehorende invulblad om per gegevensstroom de richting, de bedoelde regels, de eigenaar en de waargenomen waarden naast elkaar te zetten. Houd de bedoelde acceptatieregels streng gescheiden van wat je echt zag; alleen dan is zichtbaar welke stap wel en welke niet is bevestigd. Zet geen sleutels, tokens of persoonsgegevens in het blad en gebruik alleen fictieve .example-adressen zolang je test.

Drie mogelijke uitkomsten:

Wordt het een structurele, betrouwbare stroom tussen systemen, dan is dat geen Excel-taak meer maar het onderwerp van een API-koppeling laten maken. "Lezen aannemelijk" betekent niet "goedgekeurd voor facturatie of voorraad"; het betekent alleen dat de bekende gegevens correct binnenkwamen zonder de bekende regels te breken.