Twee ioi-sites koppelen voor externe boekhouding

Deze doc legt uit hoe je twee ioi-sites aan elkaar koppelt, zodat klanten, leveranciers, facturen en creditnota’s van de ene site automatisch (of op aanvraag) worden overgezet naar de andere site, in plaats van intern geboekt te worden.

Algemeen principe: dit is een gekruiste configuratie, en die moet ALTIJD aan beide kanten worden gedaan, zelfs als de documenten maar in één richting stromen.

Dit is niet enkel een organisatorische kwestie: het is een technische vereiste. Wanneer site A een document naar site B stuurt, geeft ze haar eigen verbindings-identificatie door. Later, wanneer B site A moet terugbellen (om de boekhoudkundige status van het oorspronkelijke document bij te werken, te annuleren, enz.), doet ze dit door op B zelf een ioi Accounting API Connection-record op te zoeken met precies die identificatie. Als dat record niet bestaat op B, mislukt deze terugroepactie, ook al is de oorspronkelijke overdracht A → B perfect verlopen.

Concreet voorbeeld: ik zet een factuur over van site A (ERP) naar site B (boekhouding LU). Site A stuurt de factuur, en vraagt vervolgens dat de status ervan verandert zodra ze geboekt is. Als de statuswijziging lukt op site B, dan neemt site B opnieuw contact op met site A om te melden dat de status van de oorspronkelijke ERP-factuur moet worden aangepast. Site B moet site A dus kennen en er verbinding mee kunnen maken, net zoals A B moet kennen voor de initiële verzending. Vandaar de regel: altijd de gekruiste configuratie aan beide kanten uitvoeren, met duidelijke vermelding van de naam waaronder je bij de andere site geregistreerd staat.

In de praktijk is een van beide sites de “master” (ze verstuurt haar klanten/leveranciers/facturen) en de andere de “ontvanger” (ze ontvangt ze enkel): de documentenstroom loopt in één richting. Een echt tweerichtingsverkeer (elke site verstuurt ook naar de andere) is met dit mechanisme theoretisch mogelijk, maar wordt in de praktijk normaal gezien niet gebruikt.

Concreet, voor een koppeling tussen een mastersite en een ontvangende site:

• Deel 1 (API-verbinding): aan te maken op beide sites, zonder uitzondering, ook op de ontvangende site die zelf nooit iets zal versturen (nodig voor de statusterugkoppeling, zie het voorbeeld hierboven).
• Delen 2 en 3 (journalen + “Transfer candidate”): enkel nodig op de mastersite, degene die de documenten daadwerkelijk verstuurt.

---

Deel 1 - De API-verbinding aanmaken (aan beide kanten) #

1.1 Op de site die de documenten zal ONTVANGEN: een dedicated gebruiker aanmaken #

Dit is de gebruiker die de andere site zal gebruiken om zich te authenticeren bij haar API-aanroepen.

1. Maak een nieuwe User aan die specifiek voor dit doel bestemd is (bv. api-koppeling-lu@uwdomein.com). Gebruik geen persoonlijk account.
2. Genereer op de fiche van deze gebruiker, sectie API Access, een API Key en een API Secret. Noteer beide waarden onmiddellijk (het secret wordt nadien nooit meer in klare tekst getoond).
3. Zorg ervoor dat de gebruiker actief is (niet gedeactiveerd).

1.2 Op de site die de documenten zal VERSTUREN: het verbindingsrecord aanmaken #

Ga naar ioi Accounting API Connection (nieuw document) en vul in:

Veld	Inhoud
Identification	Een unieke identificatie, eenmalig gekozen (niet meer te wijzigen na aanmaak). Wordt automatisch de technische naam van het record (in HOOFDLETTERS). Dit is de waarde die de andere site letterlijk moet overnemen in haar eigen veld “Accounting API Connection ID for this site” (zie verder).
Site URL	De basis-URL van de externe site (bv. https://oviservice.ioi.online).
API Key	De sleutel gegenereerd in stap 1.1 op de externe site.
API Secret	Het secret gegenereerd in stap 1.1 op de externe site.
Accounting API Connection ID for this site	De waarde van het veld “Identification” zoals ingevuld op het verbindingsrecord dat op de externe site werd aangemaakt (dat wat die externe site gebruikt om u terug te bellen). Moet exact overeenkomen (hoofdletters spelen geen rol, alles wordt automatisch in hoofdletters gezet) met de naam van een ioi Accounting API Connection-record dat echt op de externe site moet bestaan, anders mislukken de terugroepacties (statusupdate, annulering).
Accounting Access	Enkel aanvinken als u ook de saldi/boekhoudkundige situaties van de externe site vanaf deze site wilt kunnen raadplegen. Niet nodig voor de eenvoudige documentoverdracht.

Belangrijk, in deze volgorde te doen om heen-en-weer te vermijden:

1. Maak op site A het verbindingsrecord aan met een gekozen “Identification” (bv. OVI-BE). Laat “Accounting API Connection ID for this site” voorlopig leeg als u de identificatie van site B nog niet kent.
2. Maak op site B het verbindingsrecord aan met zijn eigen “Identification” (bv. OVI-LU), en vul “Accounting API Connection ID for this site” in = OVI-BE (de waarde gekozen in stap 1).
3. Ga terug naar het record van site A en vul “Accounting API Connection ID for this site” in = OVI-LU.

Elke site heeft dus verplicht haar eigen ioi Accounting API Connection-record (dat naar de andere site verwijst, met de gegevens van een dedicated gebruiker die op die andere site bestaat): dit Deel 1 moet in alle gevallen aan beide kanten worden herhaald, zelfs als slechts een van beide sites daadwerkelijk documenten naar de andere verstuurt (zie de uitleg bovenaan deze doc).

---

Deel 2 - De betrokken journalen configureren #

Deze stap gebeurt op de verzendende site, op elk verkoopjournaal (voor klanten/verkoopfacturen) en/of aankoopjournaal (voor leveranciers/aankoopfacturen) waarvan de documenten naar de externe site moeten vertrekken.

Open het betrokken journaal (ioi Sales Journal of ioi Purchases Journal).

2.1 Tabblad “Sales Invoices” / “Purchases Invoices” (en “Sales Credit Notes” / “Purchases CN”) #

Sectie “Accounting Transfer”: het veld Accounting Journal (link naar een intern boekhoudjournaal) moet leeg blijven. Dit veld bepaalt de manier van overdracht:

• ingevuld → interne overdracht (er wordt rechtstreeks op deze site een boekhoudkundige boeking aangemaakt, het hier beschreven mechanisme wordt niet gebruikt);
• leeg → externe overdracht (op voorwaarde dat de velden van deel 2.2 zijn ingevuld).

2.2 Tabblad “Files” #

Veld	Inhoud
Accounting Journal (External)	Vrije identificatie van het journaal dat het document moet ontvangen, zoals het aan de kant van de externe site begrepen moet worden. Af te spreken met de beheerder van de andere site.
Accounting API Connection (External)	Selecteer het ioi Accounting API Connection-record aangemaakt in Deel 1.2.

Deze twee velden bestaan afzonderlijk voor facturen en voor creditnota’s: vul ze in voor elk documenttype dat u wilt overzetten.

2.3 Tabblad “Logs” #

Veld	Functie
Automatic	Aanvinken zodat DIT journaal deelneemt aan de automatische overdracht (elke 10 minuten, zie Deel 4). Indien niet aangevinkt, vertrekt geen enkel document van dit journaal automatisch, zelfs niet als de algemene instelling actief is.
Attempt Submit	Indien aangevinkt, probeert het systeem de boeking op de externe site ook meteen te valideren (“submit”) na het aanmaken ervan.
Number of inactive days at the beginning of the month	De automatische overdracht start pas nadat deze dag van de maand voorbij is (bv. 5 = niets vertrekt vóór de 6de van de maand).
Minimum document age in days	Wachttijd na de documentdatum vóór de automatische verzending (bv. 5 dagen = een document van vandaag vertrekt niet vóór 5 dagen).

Deze laatste twee instellingen gelden enkel voor de automatische trigger: de manuele overdracht via “Transfer Now” (Deel 4) negeert ze.

---

Deel 3 - Klanten/leveranciers markeren voor overdracht #

Op elke betrokken ioi Customer / ioi Supplier-fiche, sectie “Transfer (External)”:

• Transfer candidate: aanvinken zodat deze derde partij naar de externe site(s) wordt gesynchroniseerd.
• Last transferred on: wordt automatisch ingevuld na de eerste geslaagde overdracht, alleen-lezen.

Enkel dit vakje aanvinken volstaat niet. De overdrachtstaak zoekt, onder alle verkoop-/aankoopjournalen, naar minstens één journaal dat correct is geconfigureerd zoals in Deel 2 (extern Accounting Journal + Accounting API Connection ingevuld). Als geen enkel journaal geconfigureerd is, mislukt de overdracht met de fout “No accounting API connection found” (zie Deel 6), ongeacht de status van het vakje “Transfer candidate”.

Optie: enkel overzetten bij aanmaak #

In ioi Accounting Settings (zie Deel 4), sectie algemene parameters:

• Do not update customers after creation on external site(s)
• Do not update suppliers after creation on external site(s)

Standaard (niet aangevinkt) wordt elke latere wijziging aan de derde partij automatisch opnieuw overgezet (zolang “Transfer candidate” aangevinkt blijft). Indien aangevinkt, wordt enkel de initiële aanmaak overgezet: latere wijzigingen aan de derde partij worden niet meer doorgestuurd naar de externe site.

---

Deel 4 - De globale overdracht activeren en testen #

Ga naar ioi Accounting Settings → tabblad “Transfer of Invoices & CNs”, sectie “Execution”:

Veld	Functie
Automatic (Every 10 Minutes)	Algemene schakelaar. Moet aangevinkt zijn opdat de geplande taak (elke 10 minuten) wordt uitgevoerd. Deze taak beheert zowel de synchronisatie van de derde partijen (Deel 3) als de overdracht van facturen/creditnota’s van journalen gemarkeerd als “Automatic” (Deel 2.3).
Inactive From / Inactive Until (Server Time)	Optioneel: tijdsvenster (servertijd) waarin de automatische overdracht niet wordt getriggerd. Laat beide velden samen leeg als u geen inactiviteitsvenster wilt; vul nooit maar één van de twee in.
Transfer Now	Forceert onmiddellijk een uitvoering, manueel, zonder op de 10 minuten te wachten. Handig om de configuratie te testen nadat ze is ingesteld.
Latest Transfer Beginning / Latest Transfer End	Tijdstempel van de laatste uitvoering van de taak. Te raadplegen bij twijfel: als “End” al lang niet meer wordt bijgewerkt terwijl “Automatic” aangevinkt is, zit de taak wellicht vast.
Latest Error Log (caped to 6500 characters)	Laatste foutenlogboek, één bericht per derde partij/document dat mislukte tijdens de laatste uitvoering. Eerste plaats om te checken bij problemen.

De velden VAT Code For Proposed Financial Discount (Sales/Purchases) op dezelfde pagina hebben enkel betrekking op de modus “voorgesteld financieel korting” (verminderde btw); ze hebben geen invloed op de werking van de koppeling zelf.

---

Deel 5 - Wat wordt overgezet, en hoe #

• Klanten/Leveranciers: identiteit, contactgegevens, btw, bankgegevens, betalings-/leveringsvoorwaarden, standaard boekhoudrekeningen, enz. De volledige lijst van overgezette velden ligt vast (niet configureerbaar).
• Facturen en creditnota’s: enkel documenten in status “in wacht” (standby); voor verkoop moet het document bovendien goedgekeurd zijn (of geen goedkeuring vereisen). De samenvattingslijnen (algemene rekening, btw-code, bedragen, analytics) worden ongewijzigd verstuurd, samen met de bijlagen van het document.
• Na een geslaagde overdracht gaat het brondocument naar status “Temporary” op de verzendende site, en behoudt het een verwijzing naar de boeking aangemaakt op de externe site (zichtbaar op het document).
• Indien “Attempt Submit” is aangevinkt op het journaal, probeert het systeem de boeking op de externe site meteen daarna ook te valideren; als deze validatie mislukt, blijft het document in fout staan, ook al is de aanmaak zelf gelukt.

---

Deel 6 - Probleemoplossing: veelvoorkomende fouten #

Bericht / symptoom	Waarschijnlijke oorzaak	Oplossing
“No accounting API connection found”	Geen enkel verkoopjournaal (voor een klant) of aankoopjournaal (voor een leverancier) heeft zowel “Accounting Journal (External)” als “Accounting API Connection (External)” ingevuld (Deel 2.2).	Vervolledig de configuratie van minstens één journaal.
“Accounting API connection {id} not found”	Het veld “Accounting API Connection (External)” van een journaal verwijst naar een verwijderd of onbestaand record.	Controleer/herstel het ioi Accounting API Connection-record.
Er gebeurt niets ondanks “Transfer candidate” aangevinkt en journalen geconfigureerd	De algemene instelling “Automatic (Every 10 Minutes)” (Deel 4) is niet aangevinkt, of het huidige tijdstip valt binnen het venster “Inactive From/Until”.	Vink “Automatic” aan, controleer het tijdsvenster, of gebruik “Transfer Now” om onmiddellijk te testen.
Authenticatiefout (401/403) bij de aanroep	Ongeldige of verlopen API-sleutel/secret, of de dedicated gebruiker is gedeactiveerd op de externe site.	Genereer een nieuwe sleutel/secret op de externe site (Deel 1.1) en werk ze bij in de verbinding.
Factuur/creditnota nooit automatisch overgezet, maar manuele overdracht werkt wel	“Number of inactive days at the beginning of the month” of “Minimum document age in days” (Deel 2.3) nog niet verstreken, of het vakje “Automatic” van het journaal niet aangevinkt.	Controleer deze twee instellingen en het vakje “Automatic” van het betrokken journaal.
Het aantal klanten/leveranciers komt na een tijdje niet overeen tussen de twee sites	Synchronisatie nog onvolledig (nieuwe derde partijen nog niet aangevinkt als “Transfer candidate”, of de taak is nog niet gelopen) of configuratie maar half afgewerkt (slechts één richting geconfigureerd).	Controleer “Latest Transfer End” en “Latest Error Log” (Deel 4) om te bevestigen dat de taak wel degelijk loopt, en dat de configuratie indien nodig aan beide kanten is gebeurd.

---

Samenvatting van de aandachtspunten #

Onderwerp	Te controleren
API-verbinding	Altijd op beide sites aangemaakt, elk met de sleutel/secret van een actieve dedicated gebruiker van de andere site
Gekruiste identificaties	“Accounting API Connection ID for this site” op A = “Identification” van het record op B, en omgekeerd (anders mislukken de statusterugkoppelingen)
Journalen + “Transfer candidate”	Enkel nodig op de mastersite (degene die verstuurt); de ontvangende site heeft enkel Deel 1 nodig
Journaal (intern vs. extern)	“Accounting Journal” (intern) leeg + “Accounting Journal (External)” en “Accounting API Connection (External)” ingevuld
Journaal - activering	Vakje “Automatic” aangevinkt op het journaal (tabblad Logs), naast de algemene instelling
Derde partij	Vakje “Transfer candidate” aangevinkt op elke betrokken klant/leverancier
Algemene instelling	“Automatic (Every 10 Minutes)” aangevinkt in ioi Accounting Settings, velden “Inactive From/Until” samen leeg (nooit maar één van de twee)
Test	Knop “Transfer Now” voor een onmiddellijke uitvoering, daarna “Latest Error Log” controleren