Digitalisatie en automatisatie van de facturatieflow voor een maritieme logistieke speler

PROBLEEM

Een maritieme logistieke speler draaide zijn dagdagelijkse operatie reeds met op maat gemaakte software. Dit hield o.a. in: inboeken van orders die binnenkomen via de klantendienst of rechtstreeks door klanten op het platform, planning van de leveringen binnen de vloot en de mensen in het veld de orders laten beheren naargelang ze afgehandeld werden.
Ook het management en de financiële afdeling hadden belang bij de applicatie, aangezien zij op basis van de verschillende rapporten en statistieken die ze eruit konden trekken hun prognoses maakten en beslissingen namen.

De ontbrekende puzzelstukken waren de facturatie en het voorraadbeheer. Met de aankomende verplichting van elektronische facturatie voor bedrijven in België vanaf januari 2026, hadden ze beslist om nieuwe business software te implementeren die beide zaken kon oplossen. Ik werd aangetrokken samen met een andere developer (die ook dienst deed als PM voor het project) om de gekozen business software te integreren in hun bestaande applicatie.

RANDVOORWAARDEN

• Kritieke applicatie: zo goed als alle dagelijkse taken verliepen via de app. Bugs of storingen hadden dus een grote impact.
• Technische schuld: de applicatie was gegroeid door de jaren heen en hield zich vaak niet aan de conventies van Laravel of algemene best practices. Elke wijziging, hoe klein ook, betekende werken in die code.
• Complexe BTW-structuur: de juiste BTW-codes en regels toepassen is in de maritieme sector een complex gegeven. De juiste codes en tarieven hangen af van het type product (soms zelfs van het specifieke product) en waar of aan wie werd geleverd of verkocht.
• Harde deadline: een nieuwe facturatieflow heeft een directe impact op de boekhouding en nieuwe software verandert de werkwijze van de financiële afdeling. De deadline voor het overschakelen werd vastgelegd op de start van het nieuwe boekjaar, zodat er geen verschillende systemen of processen door elkaar zouden worden gebruikt.

AANPAK

Inwerken

In de eerste weken startte ik met het aanpakken van een aantal kleine problemen en wijzigingen om de bestaande applicatie te leren kennen. Aangezien het ook mijn eerste kennismaking was met Laravel, gaf mij dat de kans om vertrouwd te raken met het framework en zijn ecosysteem.

Al snel merkte ik dat de applicatie veel gangbare best practices niet volgde, zowel algemene als die van Laravel. De meest opvallende waren (bijna) 'rauwe' SQL queries en functionaliteit die zelf gebouwd was, terwijl Laravel die gewoon voorziet.
Het werd ook duidelijk dat terwijl Laravel wel geüpgraded was, de code maar beperkt was mee geëvolueerd. Nieuwere toevoegingen maakten wel gebruik van recentere functies, maar de rest was gebleven zoals het was, ook wanneer eraan gewerkt was.

Codekwaliteit

Door de staat waarin de code zich bevond, heb ik aangedrongen op een 'scoutsmentaliteit': laat de code beter achter dan je ze gevonden hebt.
Je verbetert dus de code wanneer je eraan moet werken, zolang het redelijk blijft.
Eén enkel veldje toevoegen aan een formulier en het bijhorende model mag dus geen reden zijn om ineens een hele dag of meer te spenderen aan het herwerken van de gehele controller. Alleen maar de complexe logica van het formulier verplaatsen naar een service of een handler is al een hele stap vooruit en kost maar enkele minuten.
Moet je daarna nog eens aan de logica komen, zou je die wel kunnen gaan verbeteren omdat de omvang dan al kleiner is.

Naast het opschonen van de code waar mogelijk, heb ik ook enkele tools opgezet om de kwaliteit te bewaken en te verbeteren. Dat waren onder andere PHPStan, simpele composer checks, PHP linting en PHPCS met specifieke regels voor Laravel.
PHPStan heb ik ingesteld op het nog soepele niveau 5 en de bestaande problemen in de baseline gestoken, zodat we niet gehinderd werden omdat PHPStan eerst alle problemen opgelost zou willen hebben.

Een tijdje later, nadat de kwaliteitscontroles vlot liepen, heb ik ook de deployment geautomatiseerd. De pijplijn die ik opzette, draaide de kwaliteitscontroles, installeerde de nodige libraries en pakketten, compileerde alle code voor de frontend en zette alle files op de server waarna die de release aanmaakte en activeerde.

Integratie

De nieuwe business software ging gebruikt worden voor de boekhouding, de facturatie en het voorraadbeheer. Dat betekende dat de integratie zo goed als elk deel van de applicatie zou omvatten:

• Producten doorduwen van de applicatie naar de business software, voor de voorraad en facturatie
• Klantgegevens doorduwen van de applicatie naar de business software, voor de facturatie
• Bestellingen doorduwen van de applicatie naar de business software, voor de voorraad en facturatie
• Facturen binnentrekken van de business software in de applicatie

Omdat de integratie zoveel verschillende delen zou gaan aanraken en verschillende bedrijfsprocessen zou veranderen, wilden we een "big bang" zoveel mogelijk vermijden aan de start van het nieuwe boekjaar.
In plaats daarvan hebben we gekozen voor een incrementele aanpak waarbij we zo vaak mogelijk kleine stukjes al naar productie brachten. Zo konden die stukjes code al meedraaien en eventuele problemen naar boven brengen voor de deadline.

Door de functies ook al te laten werken op een testomgeving van de business software konden we testen met echte data en scenario's, zonder (grote) impact op de huidige werking.
Eén van de zaken die we zo hebben ontdekt is dat hoewel de business software de facturen wel via e-mail kon versturen, ze niet toeliet om nog extra bijlages toe te voegen naast de gegenereerde PDF. Omdat het noodzakelijk was om de leverbonnen mee te sturen hebben we beslist om de facturen terug binnen te trekken in de applicatie en de e-mails van daaruit te versturen.

Omschakeling

Ondanks al onze maatregelen om de omschakeling zo vlot mogelijk te doen verlopen was die om twee redenen toch riskanter dan we hadden gewild.

De eerste was dat er toch zaken waren die enkel getest waren op de testomgeving of zelfs helemaal niet. Denk aan alle data die werd binnengehaald in de applicatie vanuit de business software zoals de facturen, de voorraad en de betaalstatus van de facturen. Je wil namelijk niet dat er in productie facturen komen die gegenereerd zijn op een testomgeving (ook al is het met echte data) en al zeker niet omdat dat systeem pas in gebruik genomen mocht worden vanaf het nieuwe boekjaar.

De tweede reden was de BTW-configuratie. Om de regels en codes van de maritieme sector juist te krijgen was de kennis van de financiële afdeling nodig. Naast hun dagelijkse werk bleef er echter weinig tijd over om op voorhand de business software te verkennen en de juiste instellingen uit te werken. Daardoor was de BTW-logica nog niet helemaal in orde voor de omschakeling.

Zoals vooropgesteld maakten we bij de start van het nieuwe boekjaar de overschakeling naar de nieuwe business software en activeerden we de functies die data terughaalden naar de applicatie.
Naarmate de facturen gemaakt werden en de financiële afdeling met de software begon te werken, kwamen er natuurlijk ook een aantal processen en speciale gevallen naar boven waar we nog niet van wisten.
Na ongeveer drie maanden hadden we alle kinderziekten er kunnen uithalen en liepen de business software en integratie ervan in de applicatie vlot en stabiel.

RESULTAAT

Tegen de tijd dat de integratie stabiel liep, was zowat de volledige backoffice-flow van de maritieme speler geautomatiseerd. Facturen werden automatisch gegenereerd zodra een order als compleet werd gemarkeerd en de voorraad werd daar automatisch naar aangepast.
De financiële afdeling deed de boekhouding nu volledig in de nieuwe business software en de maritieme speler was daarmee voorbereid op de verplichte elektronische facturatie vanaf januari 2026.