Webhooks

Τεχνική Ορολογία

Η παρακάτω διαδικασία απαιτεί πρόσβαση στις ρυθμίσεις του διαχειριστή της ιστοσελίδας σας.

Τα Webhooks επιτρέπουν στο CourierHub να λαμβάνει ειδοποιήσεις σε πραγματικό χρόνο όταν συμβαίνει ένα γεγονός στο e-shop σας (π.χ. δημιουργία νέας παραγγελίας).

Endpoints

Ανάλογα με την πλατφόρμα που χρησιμοποιείτε, θα πρέπει να ορίσετε το αντίστοιχο URL webhook στις ρυθμίσεις του καταστήματός σας.

Shopify

Για το Shopify, η σύνδεση γίνεται αυτόματα μέσω OAuth - δεν χρειάζεται να ορίσετε χειροκίνητα κανένα webhook URL.

1. Πηγαίνετε στις Ρυθμίσεις → Διασύνδεση & Καταστήματα
2. Επιλέξτε το Shopify κατάστημά σας
3. Πατήστε Σύνδεση Shopify
4. Εγκρίνετε τα δικαιώματα στο Shopify Partners
5. Το CourierHub καταχωρεί αυτόματα τα webhooks orders/create και orders/updated

Μπορείτε να ελέγξετε οποιαδήποτε στιγμή την κατάσταση της σύνδεσης ή να επαναλάβετε την εγγραφή webhooks από την ίδια σελίδα (Έλεγχος Σύνδεσης / Ανανέωση Webhooks).

WooCommerce

Για το WooCommerce, πηγαίνετε στο Settings > Advanced > Webhooks.

Σημαντική Σημείωση

Θα πρέπει να δημιουργήσετε 2 webhooks - ένα για Order Created και ένα για Order Updated.

Webhook #1 - Νέες Παραγγελίες

Πεδίο	Τιμή
Όνομα	CourierHub Orders (Create)
Status	Ενεργοποιημένο
Topic	Order Created (Η Παραγγελία Δημιουργήθηκε)
Delivery URL	https://app.courierhub.gr/webhooks/woocommerce/orders/{CUSTOMER_ID}
Secret	(αφήστε κενό - θα δημιουργήσει το WooCommerce δικό του)
API Version	Τελευταία σταθερή έκδοση

Webhook #2 - Ενημερωμένες Παραγγελίες

Πεδίο	Τιμή
Όνομα	CourierHub Orders (Update)
Status	Ενεργοποιημένο
Topic	Order Updated (Η Παραγγελία Ενημερώθηκε)
Delivery URL	https://app.courierhub.gr/webhooks/woocommerce/orders/{CUSTOMER_ID}
Secret	(αφήστε κενό)
API Version	Τελευταία σταθερή έκδοση

TIP

Με την ενέργεια Order Created ενημερώνετε το CourierHub για τις νέες σας παραγγελίες, ενώ με την ενέργεια Order Updated ενημερώνετε το CourierHub για αλλαγές σε υπάρχουσες παραγγελίες (π.χ. αλλαγές προϊόντων, τιμών, μεταφορικών).

Πού να βρείτε το

Το {CUSTOMER_ID} είναι μοναδικό για κάθε λογαριασμό CourierHub και μπορείτε να το βρείτε στις Ρυθμίσεις του προφίλ σας ή στη σελίδα Διασύνδεσης Καταστημάτων.

Wix

Για το Wix, θα πρέπει να ρυθμίσετε το αντίστοιχο Automation ή Developer Trigger.

URL Format:https://app.courierhub.gr/webhooks/wix/orders/{CUSTOMER_ID}

---

Αντικαταβολές στο Shopify: Σήμανση ως Πληρωμένη

Όταν εισάγετε τις εισπραχθείσες αντικαταβολές από το tab Ταμείο (βλ. Ταμείο: Αντικαταβολές & Αναφορές), το CourierHub στέλνει για κάθε παραγγελία του καταστήματος την κλήση orderMarkAsPaid στο Shopify, ώστε η παραγγελία να φαίνεται πληρωμένη στο e-shop σας.

Η κλήση εκκαθαρίζει όλο το υπόλοιπο ποσό και δεν δέχεται ποσό. Αυτό ακριβώς χρειάζεται η αντικαταβολή: πριν την κλήση ελέγχεται ότι το ποσό που αποδίδει ο courier ταιριάζει με το total_amount της παραγγελίας.

Κατάσταση στο Shopify

Ο συγχρονισμός είναι best-effort και δεν μπλοκάρει την εισαγωγή των εισπραχθεισών αντικαταβολών. Κάθε παραγγελία καταλήγει σε μία από τρεις καταστάσεις:

Κατάσταση	Τι σημαίνει
paid	Το Shopify δείχνει την παραγγελία ως πληρωμένη, είτε επειδή τη σημειώσαμε εμείς είτε επειδή ήταν ήδη πληρωμένη
not_markable	Μόνιμη άρνηση: ακυρωμένη ή πλήρως επιστρεμμένη παραγγελία, μηδενικό ή αρνητικό ποσό, παραγγελία που δεν υπάρχει στο Shopify, μη Shopify κατάστημα, ή παραγγελία χωρίς Shopify order id. Επανάληψη δεν βοηθά
failed	Προσωρινή αποτυχία: σφάλμα δικτύου, GraphQL errors, missing credentials ή παραγγελία που περιμένει συναλλαγή Shopify Payments. Η επανάληψη μπορεί να βοηθήσει

Κάθε αποτυχία καταγράφεται στα logs με το internal_order_id, το shopify_order_id, το store_id και το shop_domain του καταστήματος.

Χρησιμοποιήστε την ενέργεια Επανάληψη σήμανσης πληρωμής στο Shopify στον πίνακα παραγγελιών. Εμφανίζεται σε κάθε παραγγελία αντικαταβολής Shopify με καταχωρημένη πληρωμή και είναι ασφαλής να εκτελείται ξανά, γιατί μια παραγγελία που είναι ήδη πληρωμένη στο Shopify θεωρείται επιτυχία.

Άδεια στο Shopify

Το orderMarkAsPaid απαιτεί την επιπλέον άδεια mark_orders_as_paid πέρα από το scope write_orders. Αν το Shopify απαντήσει ACCESS DENIED, δώστε την άδεια στο Shopify admin και εγκαταστήστε ξανά το custom app. Η άρνηση καταγράφεται ξεχωριστά στα logs.

Χρονικό όριο συγχρονισμού

Οι κλήσεις γίνονται σύγχρονα μέσα στην ίδια εισαγωγή, οπότε υπάρχει ανώτατο όριο χρόνου: cod.shopify_sync_budget_seconds (προεπιλογή 20 δευτερόλεπτα, μεταβλητή περιβάλλοντος COD_SHOPIFY_SYNC_BUDGET_SECONDS). Όταν εξαντληθεί, οι υπόλοιπες παραγγελίες παραλείπονται, καταγράφεται προειδοποίηση στα logs και η ειδοποίηση της εισαγωγής σας ενημερώνει πόσες παραγγελίες παραλείφθηκαν.

Τοπικό πεδίο cod_paid

Ο συγχρονισμός δεν ενημερώνει το τοπικό πεδίο cod_paid. Αυτό το πεδίο σημαίνει ότι ο courier μας παρέδωσε τα μετρητά και αλλάζει μόνο χειροκίνητα από τη Διαχείριση COD.

Εκκρεμείς παραγγελίες στο Shopify

Οι παραγγελίες αντικαταβολής που έχουμε ήδη εγγράψει τοπικά (υπάρχει εγγραφή πληρωμής) αλλά δεν έχουμε επιβεβαιώσει στο Shopify εμφανίζονται στον πίνακα παραγγελιών με μικρό προειδοποιητικό τρίγωνο δίπλα στον αριθμό παραγγελίας. Το τρίγωνο είναι καθαρά τοπικό: δεν κάνει κλήση στο Shopify κατά την εμφάνιση της σελίδας.

Το τρίγωνο εμφανίζεται όταν η στήλη shopify_marked_paid_at της παραγγελίας είναι κενή, δηλαδή όταν δεν έχει συμβεί ποτέ επιτυχής σήμανση. Η στήλη γεμίζει μόνο στην κατάσταση paid: στην εισαγωγή του Ταμείου και στην ενέργεια Επανάληψη σήμανσης πληρωμής στο Shopify. Οι καταστάσεις not_markable και failed δεν γράφουν τίποτα και δεν καθαρίζουν μια προηγούμενη σήμανση, οπότε το κενό σημαίνει «ποτέ δεν επιβεβαιώθηκε», όχι «απέτυχε». Αν το τρίγωνο εμφανίζεται, εκτελέστε την επανάληψη σήμανσης.

Παλιότερες παραγγελίες

Οι παραγγελίες που σημειώθηκαν ως πληρωμένες στο Shopify πριν υπάρξει η στήλη έχουν shopify_marked_paid_at κενή, άρα δείχνουν το τρίγωνο μέχρι να τις σημείωσετε ξανά με την επανάληψη σήμανσης ή να συμπληρωθεί η στήλη χειροκίνητα με backfill.

Προστασία τελικών καταστάσεων

Η orderMarkAsPaid κάνει το Shopify να στείλει ξανά το webhook orders/updated προς το CourierHub. Για να μην γυρίζει πίσω μια ολοκληρωμένη παραγγελία, ο OrderUpsertService αγνοεί τις αλλαγές στις τελικές καταστάσεις (SHOPIFY_TERMINAL_STATUSES): shipped, delivered, store_pickup, store_pickup_ready, store_pickup_completed, cancelled, refunded. Σε αυτές τις παραγγελίες το status δεν αλλάζει από webhook και το payment_method διατηρεί την τοπική τιμή.

Συνέπεια

Οι τελικές παραγγελίες δεν ακολουθούν πλέον αλλαγές payment gateway που έρχονται από το Shopify, και οι παραγγελίες shipped ή delivered δεν περνούν σε refunded ή cancelled μέσω webhook. Τέτοιες αλλαγές γίνονται χειροκίνητα από τον πίνακα παραγγελιών.

---

❓ Συχνές Ερωτήσεις (FAQ)

❌ Τα webhooks δεν στέλνονται

Αν παρατηρείτε ότι τα webhooks δεν φτάνουν στο CourierHub:

1. Ελέγξτε το URL του webhook

   • Βεβαιωθείτε ότι είναι ακριβώς https://app.courierhub.gr/webhooks/woocommerce/orders/{CUSTOMER_ID}
   • Αντικαταστήστε το {CUSTOMER_ID} με το σωστό ID από τη σελίδα Διασύνδεσης Καταστημάτων

2. Βεβαιωθείτε ότι το webhook είναι ενεργό

   • Πηγαίνετε στο WooCommerce: Settings > Advanced > Webhooks
   • Ελέγξτε ότι το webhook έχει κατάσταση "Active"

3. Ελέγξτε τα WooCommerce logs

   • Πηγαίνετε στο φάκελο wp-content/uploads/wc-logs/
   • Αναζητήστε αρχεία που ξεκινούν με webhook-
   • Εκεί θα βρείτε πληροφορίες για τα σφάλματα

4. Δοκιμάστε να δημιουργήσετε μια νέα παραγγελία

   • Δημιουργήστε μια δοκιμαστική παραγγελία στο WooCommerce
   • Στις ρυθμίσεις του webhook, κάντε κλικ στο Webhook και δείτε την ενότητα Deliveries για τις Αποστολές
   • Εκεί θα δείτε αν το webhook στάλθηκε και ποιο ήταν το σφάλμα (εάν υπάρχει)

5. Επικοινωνήστε με την υποστήριξη

   • Αν το πρόβλημα παραμένει, συλλέξτε ένα screenshot από τα logs και επικοινωνήστε με την ομάδα υποστήριξης.