Skroutz Smart Cart Webhook for PrestaShop

Η ενσωμάτωση των παραγγελιών του Skroutz Smart Cart στο PrestaShop 8 παρουσιάζει σύνθετες τεχνικές και λογιστικές προκλήσεις: το PrestaShop περιορίζει εκ κατασκευής το πεδίο Order Reference σε 9 χαρακτήρες (ενώ οι κωδικοί παραγγελίας του Skroutz αριθμούν 13-14+ χαρακτήρες), οι τελικές τιμές με ΦΠΑ που αποστέλλει το marketplace προκαλούν αποκλίσεις στρογγυλοποίησης, και οι αυστηροί έλεγχοι τύπων (Strict Typing) του PrestaShop 8 απορρίπτουν ονόματα ή διευθύνσεις με κενά πεδία.

Επιπλέον, τα καταστήματα χρειάζονται έναν αξιόπιστο τρόπο να απομονώνουν τους μεταφορείς του Skroutz (Courier και Παραλαβή από το Κατάστημα) ώστε να μην εμφανίζονται στους απλούς πελάτες λιανικής, καθώς και αυτόματη καταχώρηση των στοιχείων τιμολογίου (ΑΦΜ, ΔΟΥ, Επωνυμία) όταν ο αγοραστής επιλέγει έκδοση τιμολογίου.

Το Skroutz Smart Cart Webhook (v3.2.0) είναι ένα εξειδικευμένο πρόσθετο (module) για το PrestaShop 8.x, σχεδιασμένο από τον Ηλία Δαμιανίδη (DamiansLab), το οποίο αυτοματοποιεί σε πραγματικό χρόνο την εισαγωγή παραγγελιών από το Skroutz Smart Cart με πλήρη λογιστική ακρίβεια ΦΠΑ, ανίχνευση τιμολογίων ΑΦΜ/ΔΟΥ και απομόνωση μεταφορικών.

Απρόσκοπτη γεφύρωση Skroutz Marketplace και PrestaShop 8

Κάθε φορά που ολοκληρώνεται μια αγορά μέσω του Skroutz Smart Cart, το webhook endpoint του module (/module/skroutzwebhook/webhook) υποδέχεται το JSON payload, επαληθεύει τη διεύθυνση αποστολής μέσω CIDR IP Whitelist και δημιουργεί αυτόματα τον πελάτη, τη διεύθυνση, το καλάθι και την τελική παραγγελία στο PrestaShop — χωρίς καμία χειροκίνητη καταχώρηση και χωρίς την αποστολή ανεπιθύμητων αυτοματοποιημένων emails στον αγοραστή.

Συνδυάζεται εγγενώς με το συνοδευτικό module πληρωμών Πληρωμή μέσω Skroutz (skroutzpayment), αποτυπώνοντας με ακρίβεια τον τρόπο εξόφλησης και τον πραγματικό κωδικό συναλλαγής του marketplace.

Βασικές δυνατότητες και αρχιτεκτονικές καινοτομίες

1. Έξυπνη ταύτιση προϊόντων 5 επιπέδων (Smart Product Matching Cascade)

• Πολυεπίπεδη αναζήτηση κωδικού (findProduct): Για κάθε γραμμή προϊόντος (shop_uid), ο αλγόριθμος ελέγχει διαδοχικά: (1) το Product ID, (2) το κύριο Reference (SKU) του προϊόντος, (3) το Reference του συνδυασμού/παραλλαγής στον πίνακα ps_product_attribute, (4) το MPN του κύριου προϊόντος και (5) το MPN του συνδυασμού.
• Πλήρης υποστήριξη συνδυασμών (Combinations): Αποτρέπει τις αστοχίες αποθέματος σε καταστήματα με μεγέθη, χρώματα ή τεχνικές παραλλαγές, δεσμεύοντας ακριβώς το σωστό id_product_attribute.

2. Μηχανή αποφορολόγησης ακριβείας 6 δεκαδικών (Net Price & VAT Engine)

• Μηδενικές αποκλίσεις στρογγυλοποίησης: Επειδή το Skroutz αποστέλλει τελικές τιμές με ΦΠΑ (unit_price), το module ανακτά δυναμικά τον συντελεστή ΦΠΑ του προϊόντος για τη διεύθυνση παράδοσης ($productObj->getTaxesRate($address)) και υπολογίζει την καθαρή τιμή με ακρίβεια 6 δεκαδικών ψηφίων: round($skroutzPriceGross / (1 + ($taxRate / 100)), 6).
• Δυναμικό SpecificPrice ανά καλάθι: Δημιουργεί εξατομικευμένη εγγραφή SpecificPrice συνδεδεμένη αποκλειστικά με το id_cart της παραγγελίας, εξασφαλίζοντας 100% ταύτιση του τελικού ποσού πληρωμής.

3. Αυτόματη επέκταση βάσης δεδομένων για 14+ ψηφία Order Reference

• Αυτόματο Schema Migration (installDb): Κατά την εγκατάσταση, το module εκτελεί αυτόματα ALTER TABLE ps_orders MODIFY reference VARCHAR(32) και ALTER TABLE ps_order_payment MODIFY order_reference VARCHAR(32).
• Άμεση αναζήτηση με τον κωδικό Skroutz: Αντικαθιστά τον τυχαίο 9ψήφιο κωδικό του PrestaShop με τον πραγματικό κωδικό παραγγελίας του Skroutz (π.χ. 261016-849201) τόσο στην παραγγελία όσο και στην εγγραφή πληρωμής.

4. Απομόνωση μεταφορικών (Hidden Carrier Logic) και Store Pickup

• Αποκλειστική ομάδα πελατών: Μέσω των μεθόδων $customer->cleanGroups() και $customer->addGroups([$targetGroupId]), οι πελάτες του Skroutz εντάσσονται αποκλειστικά στην ειδική ομάδα (π.χ. Skroutz Only), κρατώντας τους μεταφορείς του marketplace αόρατους από το κοινό της λιανικής.
• Αυτόματη ανίχνευση Παραλαβής από το Κατάστημα: Ελέγχει τα πεδία dispatch_method και courier του payload και, εφόσον εντοπίσει store_pickup, δρομολογεί αυτόματα την παραγγελία στον ξεχωριστό μεταφορέα SKROUTZ_CARRIER_PICKUP.

5. Υποστήριξη τιμολογίων (ΑΦΜ / ΔΟΥ) και Silent Order Status

• Καταγραφή στοιχείων τιμολόγησης B2B: Όταν η παραγγελία απαιτεί τιμολόγιο (invoice: true), το module αποθηκεύει την Επωνυμία, το Επάγγελμα, το ΑΦΜ (vat_number) και τη ΔΟΥ τόσο στον πίνακα invoice της βάσης όσο και ως ιδιωτικό μήνυμα (Private Order Message) μέσα στην καρτέλα της παραγγελίας.
• Κατάσταση παραγγελίας χωρίς ειδοποιήσεις email: Δημιουργεί αυτόματα την κατάσταση Payment Accepted (Skroutz) με send_email = false, αποφεύγοντας τις διπλές ειδοποιήσεις προς τον πελάτη.

Οι οθόνες της εφαρμογής σε desktop και mobile

Σημείωση: Για λόγους προστασίας προσωπικών δεδομένων, όλες οι οθόνες απεικονίζουν αποκλειστικά συνθετικά δεδομένα δοκιμών (εικονικά ονόματα, τηλέφωνα 21000000xx και εικονικά ΑΦΜ).

Στο παρασκήνιο: Ασφάλεια, Idempotency και Strict Typing

• Έλεγχος IP & CIDR Subnet Filtering (isIpAllowed): Ο SkroutzWebhookWebhookModuleFrontController επαληθεύει τη διεύθυνση REMOTE_ADDR έναντι των επίσημων IP subnets της Skroutz (π.χ. 185.6.76.0/22) με bitwise mask calculation, απορρίπτοντας κάθε μη εξουσιοδοτημένη κλήση με 403 Forbidden.
• Προστασία Διπλοεγγραφών (Idempotency Guard): Η μέθοδος orderExists($skroutzCode) ελέγχει ταυτόχρονα τα πεδία ps_orders.reference, ps_orders.note και ps_order_payment.transaction_id ώστε καμία παραγγελία να μην καταχωρηθεί διπλή ακόμη κι αν το Skroutz επαναλάβει την αποστολή του webhook.
• Συμβατότητα με PHP 8.1+ & PrestaShop 8 Strict Typing: Αρχικοποίηση όλων των προαιρετικών πεδίων του πίνακα ps_address σε κενό αλφαριθμητικό ("" αντί NULL) και ενσωμάτωση του override/classes/Validate.php (isName / isCustomerName) για απρόσκοπτη επεξεργασία πελατών στο Back-Office.

Αναπτύχθηκε το Skroutz Smart Cart Webhook v3.2.0 σε συνδυασμό με το module πληρωμής skroutzpayment, ενσωματώνοντας αυτόματη επέκταση των πεδίων reference της βάσης σε 32 χαρακτήρες, μηχανή αποφορολόγησης 6 δεκαδικών ψηφίων μέσω SpecificPrice και 5-επίπεδη αναζήτηση προϊόντων και συνδυασμών (ID, SKU, Combination SKU, MPN).

Παράλληλα, υλοποιήθηκε αυτόματη απομόνωση πελατών σε αποκλειστικό Customer Group, δυναμική εναλλαγή μεταφορέα για Store Pickup, καταχώρηση στοιχείων τιμολογίου (ΑΦΜ/ΔΟΥ) και πίνακας Webhook Logs με δυνατότητα επανεκτέλεσης (Manual Retry) με ένα κλικ.

Η ροή παραγγελιών από το Skroutz Smart Cart αυτοματοποιήθηκε πλήρως, εκμηδενίζοντας τον χρόνο χειροκίνητης καταχώρησης και εξασφαλίζοντας 100% λογιστική ταύτιση μεταξύ των παραστατικών του e-shop και των εκκαθαρίσεων του marketplace.

Τα αποθέματα ενημερώνονται ακαριαία ακόμα και σε προϊόντα με συνδυασμούς, τα τιμολόγια B2B καταγράφονται αυτόματα και η ομάδα εξυπηρέτησης διαθέτει πλήρη εικόνα και δυνατότητα επανεκτέλεσης κάθε webhook μέσα από το PrestaShop Back-Office.