E-shop API 3.6 – Σύνδεση της EMDI με e-shop

Η EMDI συνδέεται με οποιοδήποτε e-shop (ή δικό σου backend) μέσω απλών κλήσεων HTTP. Η επιστροφή είναι κείμενο χωρισμένο με ερωτηματικό (;), δηλαδή CSV. Δεν χρειάζεται JSON API ούτε συγκεκριμένη γλώσσα.

Οποιαδήποτε γλώσσα που ανοίγει ένα URL και απαντά GET ή POST αρκεί: C#, Java, Python, Node.js, Go, ASP / .NET, Ruby, PHP, ακόμα και ένα στατικό αρχείο. Οι έτοιμες γέφυρες της SBZ είναι σε PHP λόγω του ότι τα OpenCart, WooCommerce, Magento και CS-Cart τρέχουν σε PHP. Αν θέλεις να συνδέσεις δικό σου e-shop ή υπηρεσία, υλοποίησε τους ίδιους συνδέσμους στη γλώσσα προγραμματισμού που δουλεύεις.

Άνοιξε Ρυθμίσεις → Σύνδεση e-shop. Ενεργοποίησε τη σύνδεση, βάλε τη διεύθυνση του site και τον κωδικό (key) και πάτησε εφαρμογή ώστε να συμπληρωθούν οι σύνδεσμοι. Μπορείς να ανοίξεις κάθε σύνδεσμο από το κουμπί δίπλα του για δοκιμή. Στο πρόγραμμα περιήγησης πρέπει να βλέπεις CSV, όχι σελίδα HTML λάθους.

Στις Πωλήσεις, σε νέο παραστατικό, πάτησε Insert. Ανοίγει το παράθυρο «Εισαγωγή γραμμών ειδών από το διαδίκτυο». Επίλεξε παραγγελία στα αριστερά, πάτησε Εισαγωγή και κλείσε το παράθυρο. Το παραστατικό συμπληρώνεται αυτόματα, με πελάτη, τρόπο πληρωμής/αποστολής, σχόλιο και γραμμές. Η ενημέρωση του e-shop γίνεται όταν πατήσεις Καταχώρηση, όχι όταν κλείνεις το παράθυρο παραγγελιών.

Σειρά κλήσεων όταν ανοίγεις το παράθυρο:
modifiedcustomers → (αν ήρθαν γραμμές)
customersconfirm → modifiedproducts → (αν ήρθαν γραμμές) productsconfirm → orderlist.
Σε κάθε επιλογή παραγγελίας καλείται το selectedorder.
Με την καταχώρηση καλείται το confirmorder και μετά, για κάθε είδος με την επιλογή internet, το productavailability μαζί με το quantityvariable.

Η αποστολή είδους από την αποθήκη είναι POST multipart. Η απάντηση πρέπει να είναι UTF-8. Η πρώτη γραμμή είναι επικεφαλίδα και αγνοείται. Η σειρά των πεδίων δεν αλλάζει. Κενό πεδίο αφήνεται ανάμεσα σε δύο ;. Μην βάζεις ερωτηματικό μέσα στην τιμή ενός πεδίου.

Endpoints

Όσα endpoints αλλάζουν κατάσταση στο e-shop (confirmorder, cancelorder, customersconfirm, productsconfirm, productavailability, deletetmp) καλούνται από την EMDI με GET (παράμετροι στο URL).
Μόνο το uploadproduct είναι POST multipart.

Στις έτοιμες PHP γέφυρες τα ονόματα μοιάζουν με ?key=…&action=orders. Σε άλλη υλοποίηση μπορεί να έχει συνδέσμους όπως /orders.

Κάθε γραμμή είναι μία εκκρεμής παραγγελία. Καλό είναι να στέλνεις μόνο όσες δεν έχουν ακόμη ολοκληρωθεί.

Ο πελάτης αντιστοιχίζεται με τον κωδικό στην EMDI. Το πεδίο χρήστης αντιστοιχεί στο όνομα χρήστη της EMDI. Το κόστος μεταφορικών και η έκπτωση γίνονται επιπλέον γραμμές στο παραστατικό. Αν το κόστος αντικαταβολής είναι ακριβώς 0.01, εισάγεται γραμμή αντικαταβολής με αξία 0. Η κατάσταση αποθηκεύεται στο πεδίο που όρισες ως «Πεδίο κατάστασης σε πεδίο». Ο τρόπος πληρωμής και αποστολής πρέπει να ταιριάζουν με τις περιγραφές στις ρυθμίσεις της EMDI. Το παραστατικό είναι ο τίτλος είδους παραστατικού (π.χ. ΤΙΜΟΛΟΓΙΟ ΠΩΛΗΣΗΣ).

Η κλήση γίνεται με 2 τρόπους:

1. Αν ο σύνδεσμος στις ρυθμίσεις τελειώνει σε =, η EMDI προσθέτει στο τέλος τον κωδικό παραγγελίας και διαβάζει μόνο αυτήν.
2. Αν δεν τελειώνει σε =, διαβάζει όλο το αρχείο και κρατά τις γραμμές με τον κωδικό της επιλεγμένης παραγγελίας.

Η έκπτωση γραμμής είναι ποσοστό.

Σημείωση: Με αυτή τη κλήση η EMDI αλλάζει δεδομένα στο e-shop, κάνοντας κλήση GET βάσει παραμέτρων.

Καλείται στην καταχώρηση του παραστατικού.
Η EMDI αντικαθιστά τα #docid, #shipcomp, #voucherno και προσθέτει στο τέλος τον αριθμό παραγγελίας του e-shop (από το πεδίο Σχετικά, χωρίς το πρόθεμα σχετικού, στις ρυθμίσεις προεπιλογή ^).

Παράδειγμα σε PHP (ίδια λογική σε κάθε γλώσσα):

Το κουμπί Ολοκλήρωση στο παράθυρο παραγγελιών καλεί επίσης αυτόν τον σύνδεσμο (χωρίς voucher και τρόπο αποστολής). Η κανονική ροή είναι η καταχώρηση του παραστατικού.

Σημείωση: Με αυτή τη κλήση η EMDI αλλάζει δεδομένα στο e-shop, κάνοντας κλήση GET βάσει παραμέτρων.

Η EMDI προσθέτει στο τέλος του συνδέσμου τον αριθμό παραγγελίας. Εμφανίζεται το κουμπί Ακύρωση μόνο όταν ο σύνδεσμος είναι συμπληρωμένος στις ρυθμίσεις.

Η EMDI ενημερώνει βάσει κωδικού ή δημιουργεί νέο πελάτη. Με επιλεγμένα τα «Κεφαλαία» στις ρυθμίσεις ο κωδικός γίνεται κεφαλαία χωρίς ειδικούς χαρακτήρες.

Η χώρα είναι κωδικός alpha-2 (GR, CY, DE, …). Στο πεδίο πρόσθετα πεδία βάλε Όνομα_πεδίου:Τιμή και χώρισε πολλά πεδία με τους δύο χαρακτήρες \n. Τα κενά στο όνομα γίνονται _. Το τελευταίο πεδίο είναι η Τ.Θ.

Ο κωδικός είδους πρέπει να είναι ο ίδιος στο e-shop και στην EMDI.

Δεύτερος κωδικός (MPN): ΚΩΔΙΚΟΣ|ΚΩΔΙΚΟΣ2. Επιπλέον τιμές τιμοκαταλόγου: 1,80|2:2,00|4:3,50 (έως 4 επιπλέον). Το «Με ΦΠΑ» ορίζει αν οι τιμές περιλαμβάνουν ΦΠΑ.

Πολλές κατηγορίες χωρίζονται με κόμμα, η πρώτη είναι η κύρια. Κράτησε το πεδίο σειράς κατηγορίας (ακόμη και κενό) για σωστές θέσεις βάρους/ενεργού. Στην περιγραφή 2: κείμενο χωρίς : πηγαίνει στις σημειώσεις· γραμμές Όνομα:Τιμή γεμίζουν προσαρμοσμένα πεδία (διαχωριστικό \n).

Σημείωση: Με αυτή τη κλήση η EMDI αλλάζει δεδομένα στο e-shop, κάνοντας κλήση GET βάσει παραμέτρων.

Μετά την καταχώρηση αγοράς/πώλησης με κίνηση αποθήκης, για κάθε είδος με σήμανση internet:

δηλαδή productavailability + κωδικός + quantityvariable + διαθεσιμότητα. Καταχώρισε και τις αγορές στην EMDI. Αν δεν θέλεις ενημέρωση αποθέματος, άφησε κενούς αυτούς τους συνδέσμους.

Σημείωση: Με αυτή τη κλήση η EMDI αλλάζει δεδομένα στο e-shop, κάνοντας κλήση GET βάσει παραμέτρων.

Με τα productsconfirm/customersconfirm το e-shop αποθηκεύει ότι η EMDI τα έλαβε. Το κουμπί Επαναφορά καλεί αυτόν τον σύνδεσμο, ώστε να διαγράψει τις ημερομηνίες επιβεβαίωσης λήψης.
Έτσι η επόμενη κλήση modifiedproducts/modifiedcustomers φέρνει όλη τη λίστα.

Χρειάζεται συμπληρωμένο το «Δημιουργία/αλλαγή είδους» (senditem). Η EMDI στέλνει POST multipart/form-data.

Στην Αποθήκη, μόνο για είδη με σήμανση internet:

• Καταχώρηση είδους — δεδομένα και φωτογραφίες.
• Μενού Αποστολή επιλεγμένων στο e-shop — Ναι σε όλα = με φωτό, Ναι = μόνο στοιχεία.

Αν ο συγχρονισμός βάσεων έχει ξεχωριστό «upload products», η αυτόματη αποστολή από την καταχώρηση παραλείπεται. Οι φωτογραφίες συμπιέζονται (μεγαλύτερη πλευρά/ποιότητα από τις ρυθμίσεις).

Το μενού Ενημέρωση διαθεσιμοτήτων στο e-shop στην αποθήκη καλεί μόνο productavailability, όχι uploadproduct.

Από τις ρυθμίσεις μπορεί να εμφανιστεί πρόσθετο κουμπί σε πελατολόγιο, αποθήκη και πωλήσεις. Η EMDI ανοίγει τον σύνδεσμο αντικαθιστώντας:

• πελάτης: customerid=#CID
• είδος: productid=#SID
• παραστατικό: orderid=#DID

Σημείωση

Κράτα τους ίδιους κωδικούς και στις δύο πλευρές. Αν κάτι δεν κατεβαίνει, άνοιξε τον σύνδεσμο στον browser: πρέπει να βλέπεις σκέτο CSV με την επικεφαλίδα στην πρώτη γραμμή.