API-integratiespecificatie
Integratie: Webshoporders naar boekhouding
Versie: 1.0
Opgesteld door: Hamza Idrissi
Datum: 5 april 2029
1. Doel
Stuur elke betaalde webshoporder als verkoopfactuur naar het boekhoudsysteem, zodat de financiële afdeling die niet opnieuw hoeft in te voeren.
2. Systemen
- Verstuurt gegevens: Webshop (API v2)
- Ontvangt gegevens: Boekhoudsysteem (REST API)
3. Gegevensstroom
1. Een klant betaalt voor een order.
2. De webshop stuurt een webhook naar de integratieservice.
3. De service zet de order om in een factuur en roept de boekhoud-API aan.
4. Het boekhoudsysteem retourneert een factuurnummer, dat de service bij de order opslaat.
4. Endpoints en berichten
| Methode en pad | Wat het doet | Belangrijkste velden | Wat het teruggeeft |
|---|---|---|---|
| POST /invoices | Een factuur aanmaken | Body: klant, regels, belasting, totaal | Retourneert: factuur-id en factuurnummer |
| GET /customers?email= | Een klant zoeken | Retourneert: klant-id of leeg | |
| POST /customers | Een klant aanmaken | Body: naam, e-mail, adres |
5. Veldmapping
order.total_paid → invoice.total
order.billing_email → customer.email
order.items[].sku → line.product_code
6. Authenticatie en beveiliging
OAuth 2.0 met clientcredentials. Tokens zijn één uur geldig. Secrets staan in de vault, nooit in code. Alle aanroepen gebruiken HTTPS. Webhooks zijn ondertekend en de handtekening wordt gecontroleerd.
Persoonsgegevens worden alleen verstuurd wanneer dat nodig is, worden niet naar logs geschreven en vallen onder de privacyvoorwaarden van beide systemen.
7. Fouten en nieuwe pogingen
Probeer het opnieuw bij 429 en 5xx, tot 5 keer met oplopende wachttijden. Probeer 4xx-fouten niet opnieuw; log ze en waarschuw de financiële afdeling. Elke factuur heeft een unieke sleutel, zodat een nieuwe poging geen duplicaat kan aanmaken.
8. Limieten en volumes
De boekhoud-API staat 60 aanroepen per minuut toe. Verwacht 400 orders per dag, tot 2.000 op actiedagen.
9. Testen
Gebruik de boekhoud-sandbox. Test een normale order, een order met korting, een terugbetaling, een klant die al bestaat en een storing van de API.
10. Eigenaars en ondersteuning
Eigenaar: E-commerce team. Ondersteuning: Hamza Idrissi. Escalatie: de supportdesk van de boekhoudleverancier.
11. Wijzigingen en versiebeheer
Elke partij kondigt een ingrijpende wijziging 30 dagen van tevoren aan.