API-integrationsspecifikation
Integration: Butiksordrar till redovisning
Version: 1.0
Skriven av: Hamza Idrissi
Datum: 5 april 2029
1. Syfte
Skicka varje betald webborder till redovisningssystemet som en säljfaktura, så att ekonomicontoret slipper skriva in den igen.
2. System
- Skickar data: Webbplats (API v2)
- Tar emot data: Redovisningssystem (REST API)
3. Dataflöde
1. En kund betalar en order.
2. Butiken skickar en webhook till integrationstjänsten.
3. Tjänsten gör om ordern till en faktura och anropar redovisningens API.
4. Redovisningssystemet returnerar ett fakturanummer som tjänsten sparar på ordern.
4. Endpoints och meddelanden
| Metod och sökväg | Vad den gör | Huvudfält | Vad den returnerar |
|---|---|---|---|
| POST /invoices | Skapa en faktura | Body: kund, rader, moms, totalt | Returnerar: faktura-id och fakturanummer |
| GET /customers?email= | Hitta en kund | Returnerar: kund-id eller tomt | |
| POST /customers | Skapa en kund | Body: namn, e-post, adress |
5. Fältmappning
order.total_paid → invoice.total
order.billing_email → customer.email
order.items[].sku → line.product_code
6. Autentisering och säkerhet
OAuth 2.0 client credentials. Tokens gäller i en timme. Hemligheter förvaras i valvet, aldrig i kod. Alla anrop går över HTTPS. Webhooks signeras och signaturen kontrolleras.
Personuppgifter skickas bara när det behövs, skrivs inte till loggar och omfattas av båda systemens dataskyddsvillkor.
7. Fel och återförsök
Gör om försöket vid 429 och 5xx upp till 5 gånger med ökande väntetid. Försök inte igen vid 4xx-fel, logga dem och larma ekonomi. Varje faktura har en unik nyckel så att ett nytt försök inte kan skapa en dubblett.
8. Gränser och volymer
Redovisningens API tillåter 60 anrop per minut. Förväntat 400 ordrar per dag, upp till 2 000 på reapdagar.
9. Testning
Använd redovisningens sandlåda. Testa en normal order, en order med rabatt, en återbetalning, en kund som redan finns och ett avbrott i API:t.
10. Ägare och support
Ägare: E-handelsteamet. Support: Hamza Idrissi. Eskalering: redovisningsleverantörens support.
11. Ändringar och versionshantering
Båda sidor meddelar 30 dagar i förväg vid en brytande ändring.