Προδιαγραφή ενοποίησης API
Ενοποίηση: Παραγγελίες ηλεκτρονικού καταστήματος προς λογιστήριο
Έκδοση: 1.0
Συντάχθηκε από: Hamza Idrissi
Ημερομηνία: 5 Απριλίου 2029
1. Σκοπός
Αποστολή κάθε πληρωμένης παραγγελίας από το ηλεκτρονικό κατάστημα στο λογιστικό σύστημα ως τιμολόγιο πώλησης, ώστε να μην χρειάζεται να την καταχωρεί ξανά το οικονομικό τμήμα.
2. Συστήματα
- Αποστέλλει δεδομένα: Ηλεκτρονικό κατάστημα (API v2)
- Λαμβάνει δεδομένα: Λογιστικό σύστημα (REST API)
3. Ροή δεδομένων
1. Ένας πελάτης πληρώνει μια παραγγελία.
2. Το κατάστημα στέλνει ένα webhook στην υπηρεσία ενοποίησης.
3. Η υπηρεσία μετατρέπει την παραγγελία σε τιμολόγιο και καλεί το API του λογιστικού συστήματος.
4. Το λογιστικό σύστημα επιστρέφει έναν αριθμό τιμολογίου, τον οποίο η υπηρεσία αποθηκεύει στην παραγγελία.
4. Σημεία πρόσβασης και μηνύματα
| Μέθοδος και διαδρομή | Τι κάνει | Βασικά πεδία | Τι επιστρέφει |
|---|---|---|---|
| POST /invoices | Δημιουργία τιμολογίου | Σώμα αιτήματος: πελάτης, γραμμές, φόρος, σύνολο | Επιστρέφει: id και αριθμό τιμολογίου |
| GET /customers?email= | Εύρεση πελάτη | Επιστρέφει: id πελάτη ή κενό | |
| POST /customers | Δημιουργία πελάτη | Σώμα αιτήματος: όνομα, email, διεύθυνση |
5. Αντιστοίχιση πεδίων
order.total_paid → invoice.total
order.billing_email → customer.email
order.items[].sku → line.product_code
6. Έλεγχος ταυτότητας και ασφάλεια
OAuth 2.0 client credentials. Τα tokens έχουν ισχύ μίας ώρας. Τα μυστικά φυλάσσονται σε ασφαλή χώρο, ποτέ στον κώδικα. Όλες οι κλήσεις χρησιμοποιούν HTTPS. Τα webhooks είναι υπογεγραμμένα και η υπογραφή ελέγχεται.
Τα προσωπικά δεδομένα αποστέλλονται μόνο όταν είναι απαραίτητο, δεν καταγράφονται στα αρχεία καταγραφής και καλύπτονται από τους όρους απορρήτου και των δύο συστημάτων.
7. Σφάλματα και νέες προσπάθειες
Νέα προσπάθεια σε 429 και 5xx έως 5 φορές με αυξανόμενες καθυστερήσεις. Μην κάνετε νέα προσπάθεια για σφάλματα 4xx. Καταγράψτε τα και ειδοποιήστε το οικονομικό τμήμα. Κάθε τιμολόγιο έχει μοναδικό κλειδί, ώστε μια νέα προσπάθεια να μην δημιουργεί διπλότυπο.
8. Όρια και όγκοι
Το API του λογιστικού συστήματος επιτρέπει 60 κλήσεις το λεπτό. Αναμένονται 400 παραγγελίες την ημέρα, έως 2.000 τις ημέρες προσφορών.
9. Δοκιμές
Χρησιμοποιήστε το sandbox του λογιστικού συστήματος. Δοκιμάστε μια κανονική παραγγελία, μια παραγγελία με έκπτωση, μια επιστροφή χρημάτων, έναν πελάτη που υπάρχει ήδη και μια διακοπή του API.
10. Υπεύθυνοι και υποστήριξη
Υπεύθυνος: ομάδα ηλεκτρονικού εμπορίου. Υποστήριξη: Hamza Idrissi. Κλιμάκωση: γραφείο υποστήριξης του προμηθευτή λογιστικού συστήματος.
11. Αλλαγές και εκδόσεις
Κάθε πλευρά δίνει προειδοποίηση 30 ημερών για μη συμβατή αλλαγή.