Οδηγός χρήσης για διαχειριστή

Ο οδηγός αυτός αφορά τη ρύθμιση και την καθημερινή χρήση της επέκτασης BoxNow για Magento 2. Απευθύνεται σε διαχειριστές καταστήματος, ανθρώπους που διαχειρίζονται αποστολές, τεχνικούς διαχειριστές και ομάδα υποστήριξης.

1. Τι κάνει η επέκταση

Η επέκταση Ioweb_Boxnow προσθέτει υποστήριξη αποστολών BoxNow σε Magento 2. Περιλαμβάνει μέθοδο αποστολής, επιλογή θυρίδας στο checkout, αποθήκευση του σημείου παραλαβής σε quote και order, δημιουργία delivery requests, λήψη PDF labels, integration logs, queue processing, parcel reconciliation, webhooks και CLI εντολές.

Η μέθοδος αποστολής εμφανίζεται ως BoxNow και ο εσωτερικός carrier code είναι boxnow_bestway.

2. Ποιοι το χρησιμοποιούν

• Διαχειριστές καταστήματος: ρυθμίζουν carrier, credentials, table rates και retention settings.
• Fulfillment operators: δημιουργούν BoxNow delivery requests, προσθέτουν tracking σε shipments και κατεβάζουν labels.
• Τεχνικοί διαχειριστές: ελέγχουν cron, credentials, webhooks, logs και CLI diagnostics.
• Ομάδα υποστήριξης: ελέγχει προβλήματα checkout, pickup point, queue, provider calls και labels.

3. Προϋποθέσεις

• Εγκατεστημένο και ενεργό module Ioweb_Boxnow στο Magento 2.
• Magento Admin χρήστες με τα σωστά ACL permissions κάτω από το BoxNow resource.
• Ενεργό Magento checkout και shipping rate collection.
• Magento cron ενεργό για queue processing, parcel reconciliation και cleanup εργασίες.
• BoxNow merchant account με sandbox ή production credentials.
• BoxNow table rates, ώστε να επιστρέφεται κόστος αποστολής στο checkout.
• Δημόσια προσβάσιμο webhook endpoint, αν θα χρησιμοποιούνται αυτόματες ενημερώσεις κατάστασης από BoxNow.

4. Πού βρίσκεται στο Magento Admin

• Ρυθμίσεις carrier: Stores > Configuration > Sales > Shipping Methods > BoxNow
• Delivery Requests: Sales > BoxNow > Delivery Requests
• Labels: Sales > BoxNow > Labels
• Integration Log: Sales > BoxNow > Integration Log
• Table Rates: Sales > BoxNow > Table Rates
• Παραγγελίες: Sales > Orders
• Shipment: από τη σελίδα παραγγελίας με Ship ή από υπάρχον shipment.
• Queue: άμεσο admin route io_boxnow_queue/queue/index, όταν υπάρχει σχετικό δικαίωμα πρόσβασης.

5. Δικαιώματα διαχειριστή

Τα BoxNow admin permissions ελέγχονται από Magento ACL roles. Αν ένας χρήστης δεν βλέπει κάποιο μενού ή κουμπί, πρέπει να ελεγχθεί ο ρόλος του.

• Delivery Requests
• Order Shipment
• Labels
• Integration Log
• Table Rates
• Queue

Το queue menu μπορεί να μην εμφανίζεται ως κανονικό μενού, αλλά η πρόσβαση υπάρχει για λειτουργικούς ελέγχους μέσω route.

6. Βασική ρύθμιση carrier

Οι βασικές ρυθμίσεις βρίσκονται στο:

Stores > Configuration > Sales > Shipping Methods > BoxNow

General

• Enabled: ενεργοποιεί ή απενεργοποιεί τη μέθοδο BoxNow στο checkout.
• Title: τίτλος carrier που βλέπει ο πελάτης.
• Method Name: όνομα μεθόδου κάτω από τον carrier.
• Sort Order: σειρά εμφάνισης στις μεθόδους αποστολής.
• Free Shipping Threshold: ποσό από το οποίο η BoxNow γίνεται δωρεάν.
• Condition: κριτήριο table rates, όπως βάρος, αξία ή ποσότητα.
• Maximum Package Weight: κρύβει τη μέθοδο όταν το δέμα ξεπερνά το όριο βάρους.
• Handling Fee: προσθέτει επιπλέον χρέωση αποστολής.
• Ship to Applicable Countries: περιορίζει τη μέθοδο ανά χώρα.
• Displayed Error Message: μήνυμα όταν η μέθοδος εμφανίζεται αλλά δεν είναι διαθέσιμη.

Rate Files

Τα BoxNow table rates εισάγονται ή εξάγονται από το group Rate Files. Μπορούν επίσης να διαχειριστούν από:

Sales > BoxNow > Table Rates

Οι τιμές επηρεάζουν άμεσα το checkout. Αν δεν υπάρχει table rate που ταιριάζει με το καλάθι και τη διεύθυνση, η BoxNow δεν θα επιστρέψει κόστος αποστολής.

Widget & Checkout Behavior

• BoxNow Widget Type: ορίζει αν ο selector ανοίγει ως iframe ή popup.
• Allow Return: περνά πληροφορία δυνατότητας επιστροφής προς τη BoxNow ροή.
• Default Parcel Size: προεπιλεγμένο μέγεθος δέματος στη φόρμα shipment.
• Allow Multiple Delivery Requests Per Order: ελέγχει αν επιτρέπονται πολλαπλά ενεργά requests για την ίδια παραγγελία.
• Show Label PDF Modal After Tracking Append: ανοίγει το PDF label μετά την προσθήκη tracking.
• Cash on Delivery Methods: μέθοδοι αντικαταβολής που απενεργοποιούνται όταν επιλεγεί BoxNow.

Troubleshooting

• Enable BoxNow Widget Debug Logging: γράφει αναλυτικά checkout widget diagnostics.
• Debug Customer Email: εμφανίζει BoxNow rates μόνο σε συγκεκριμένο customer email. Πρέπει να καθαρίζεται πριν τη γενική παραγωγική χρήση, εκτός αν χρησιμοποιείται σκόπιμα.

Environment and Authentication

Εδώ ορίζονται mode, retry policy και credentials για sandbox και production. Τα βασικά πεδία είναι API URL, Location API URL, Client ID, Client Secret, Webhook Secret, Partner ID και Origin Location ID.

Το Mode καθορίζει αν η επέκταση μιλάει με sandbox ή production BoxNow APIs. Το Origin Location ID πρέπει να αντιστοιχεί στην αποθήκη/σημείο προέλευσης που χρησιμοποιεί το κατάστημα.

Operations

Οι ρυθμίσεις retention καθορίζουν για πόσες ημέρες κρατούνται runtime logs και integration log rows. Αν η τιμή είναι 0, τα δεδομένα διατηρούνται επ’ αόριστον.

7. Ρύθμιση και έλεγχος carrier

1. Πηγαίνετε στο Stores > Configuration > Sales > Shipping Methods > BoxNow.
2. Ορίστε Enabled σε Yes.
3. Συμπληρώστε Title, Method Name και Sort Order.
4. Συμπληρώστε credentials και API URLs για sandbox ή production.
5. Επιλέξτε Origin Location ID.
6. Ρυθμίστε widget behavior, troubleshooting και retention settings.
7. Πατήστε Save Config.
8. Καθαρίστε Magento cache.
9. Κάντε δοκιμαστικό checkout με επιλέξιμη διεύθυνση και προϊόν.

8. Import και export table rates

Για import:

1. Πηγαίνετε στο configuration της BoxNow.
2. Επιλέξτε το σωστό scope, συνήθως Website.
3. Ανοίξτε το group Rate Files.
4. Επιλέξτε CSV αρχείο.
5. Πατήστε Save Config.
6. Καθαρίστε cache και ελέγξτε checkout.

Για export, χρησιμοποιήστε το κουμπί Export στο ίδιο group. Το αρχείο μπορεί να χρησιμοποιηθεί ως backup ή βάση για αλλαγές.

Οι table rates μπορούν να γίνουν και χειροκίνητα από Sales > BoxNow > Table Rates, με δημιουργία, αλλαγή ή διαγραφή γραμμών.

9. Συμπεριφορά στο checkout

Η BoxNow εμφανίζεται ως μέθοδος αποστολής όταν:

• ο carrier είναι ενεργός,
• η χώρα αποστολής επιτρέπεται,
• το βάρος είναι μέσα στα όρια,
• υπάρχει table rate που ταιριάζει,
• δεν μπλοκάρει το Debug Customer Email,
• το request δεν γίνεται από admin area.

Όταν ο πελάτης επιλέξει BoxNow, εμφανίζεται selector για επιλογή θυρίδας ή σημείου παραλαβής. Ανάλογα με τη ρύθμιση, ο selector μπορεί να ανοίγει ως iframe ή popup.

Η επιλογή σημείου είναι υποχρεωτική. Αν ο πελάτης προσπαθήσει να ολοκληρώσει παραγγελία χωρίς σημείο παραλαβής, το checkout μπλοκάρεται και εμφανίζεται μήνυμα επιλογής BoxNow pickup point.

10. Δημιουργία αποστολής από shipment page

Για μεμονωμένη παραγγελία:

1. Ανοίξτε την παραγγελία από Sales > Orders.
2. Πατήστε Ship ή ανοίξτε υπάρχον shipment.
3. Στην περιοχή BoxNow πατήστε το κουμπί δημιουργίας BoxNow delivery request.
4. Ελέγξτε parcel size, στοιχεία πελάτη, αντικαταβολή, βάρος και λοιπά στοιχεία.
5. Υποβάλετε τη φόρμα.
6. Σε επιτυχία, προστίθεται tracking number στο Magento shipment.
7. Αν είναι ενεργό, ανοίγει modal με το PDF label.
8. Ολοκληρώστε και αποθηκεύστε το Magento shipment.

Αν το κουμπί δεν εμφανίζεται, ελέγξτε ότι η παραγγελία είναι BoxNow, έχει pickup point, ο χρήστης έχει ACL permission και δεν υπάρχει ήδη ενεργό delivery request όταν απαγορεύονται πολλαπλά requests.

11. Μαζική αποστολή από Sales Orders

Για πολλά BoxNow orders:

1. Πηγαίνετε στο Sales > Orders.
2. Επιλέξτε τις παραγγελίες.
3. Από το Actions επιλέξτε Ship Orders with BoxNow.
4. Επιβεβαιώστε την ενέργεια.
5. Ελέγξτε τα admin messages για queued, skipped ή failed παραγγελίες.

Η ενέργεια δεν δημιουργεί όλες τις αποστολές άμεσα. Δημιουργεί queue records και η επεξεργασία γίνεται ασύγχρονα από cron.

12. Delivery Requests

Τα delivery requests βρίσκονται στο:

Sales > BoxNow > Delivery Requests

Εκεί ο διαχειριστής βλέπει κατάσταση, παραγγελία, pickup point, request IDs, provider references, parcels, payload details και σφάλματα.

Διαθέσιμες ενέργειες, ανάλογα με την κατάσταση:

• View Order: άνοιγμα σχετικής παραγγελίας.
• Retry Submission: επανάληψη αποτυχημένης αποστολής.
• Fetch Label: λήψη label από BoxNow.
• Download Label: κατέβασμα αποθηκευμένου PDF label.
• Fetch Provider Updates: ενημέρωση parcel status από BoxNow.
• Cancel Parcel: ακύρωση parcel όπου επιτρέπεται.

Τα records δεν πρέπει να αλλάζουν χειροκίνητα από τη βάση. Οι αλλαγές πρέπει να γίνονται από τις διαθέσιμες ενέργειες.

13. Queue processing

Η ουρά χρησιμοποιείται για μαζική και ασφαλή επεξεργασία αποστολών. Queue rows δημιουργούνται κυρίως από τη μαζική ενέργεια στο Sales Order grid.

Η επεξεργασία queue μπορεί να:

• δημιουργήσει ή επαναχρησιμοποιήσει BoxNow delivery request,
• κατεβάσει και αποθηκεύσει label,
• δημιουργήσει ή φορτώσει Magento shipment,
• προσθέσει tracking number,
• στείλει shipment email,
• κρατήσει idempotency flags για να μην επαναληφθούν βήματα άσκοπα.

Αν ένα queue item αποτύχει, ελέγξτε attempts, lock status, related order, delivery request και logs. Τα locked items μπορεί να επεξεργάζονται ήδη από cron.

14. Labels

Τα labels βρίσκονται στο:

Sales > BoxNow > Labels

Τα label records δημιουργούνται αυτόματα από label fetch operations. Από το grid μπορείτε να δείτε metadata και να κατεβάσετε το PDF label. Δεν προορίζονται για χειροκίνητη δημιουργία ή διαγραφή.

15. Integration Log και file logs

Το Sales > BoxNow > Integration Log εμφανίζει inbound και outbound payloads για API calls και webhooks. Χρησιμοποιείται για operational audit και debugging. Sensitive στοιχεία όπως secrets και bearer tokens πρέπει να εμφανίζονται masked.

Runtime logs και widget errors γράφονται σε file-based logs στο Magento server. Η αυτόματη διαγραφή παλιών logs γίνεται από cron με βάση τα retention settings.

16. Webhooks

Το webhook endpoint είναι:

https://<your-magento-domain>/io_boxnow/webhook/notify

Τα webhooks ενημερώνουν αυτόματα delivery request records στο Magento. Η επέκταση ελέγχει την υπογραφή με το configured Webhook Secret. Αποδεκτά και απορριφθέντα webhook updates καταγράφονται στο Integration Log.

17. Cron jobs

• ioweb_boxnow_process_queue: επεξεργάζεται queued delivery requests.
• ioweb_boxnow_reconcile_parcels: φέρνει parcel status updates από τον provider.
• ioweb_boxnow_cleanup_integration_logs: καθαρίζει παλιές εγγραφές integration log.
• ioweb_boxnow_cleanup_runtime_logs: καθαρίζει παλιά runtime log files.

Αν οι μαζικές αποστολές, τα updates ή τα cleanups δεν τρέχουν, ελέγξτε πρώτα το Magento cron.

18. CLI εντολές

bin/magento ioweb:boxnow:auth:test
bin/magento ioweb:boxnow:credentials:active
bin/magento ioweb:boxnow:credentials:list
bin/magento ioweb:boxnow:mode:set sandbox
bin/magento ioweb:boxnow:mode:set production

• auth:test: ελέγχει σύνδεση με BoxNow API.
• credentials:active: δείχνει active mode και credentials με κρυμμένα sensitive στοιχεία.
• credentials:list: δείχνει κατάσταση credentials ανά scope.
• mode:set: αλλάζει sandbox ή production mode.

19. Αντικαταβολή και μέθοδοι πληρωμής

Οι μέθοδοι πληρωμής που έχουν οριστεί στο Cash on Delivery Methods απενεργοποιούνται στο checkout όταν ο πελάτης επιλέξει BoxNow. Αυτό αποτρέπει παραγγελίες αντικαταβολής όταν ο merchant δεν θέλει να τις επιτρέπει με BoxNow.

20. Emails Magento

Η επέκταση δεν προσθέτει custom email templates. Προσθέτει δυναμικά τα στοιχεία BoxNow pickup point στο shipping description των στάνταρ Magento emails, όπως order, invoice και shipment emails. Μετά την αποστολή, το αρχικό shipping description επανέρχεται.

21. Συχνά προβλήματα

Η BoxNow δεν εμφανίζεται στο checkout

• Ελέγξτε αν το Enabled είναι Yes.
• Ελέγξτε table rates.
• Ελέγξτε χώρα, βάρος, cache και Debug Customer Email.
• Δοκιμάστε με διεύθυνση και καλάθι που ταιριάζουν στους κανόνες.

Η BoxNow εμφανίζεται με λάθος τίτλο

• Ελέγξτε Title και Method Name στο σωστό Store View scope.
• Ελέγξτε αν υπάρχει override σε store view.

Το checkout μπλοκάρει την παραγγελία

• Ελέγξτε ότι έχει αποθηκευτεί pickup point.
• Επιλέξτε ξανά θυρίδα.
• Ελέγξτε AJAX responses για pickup point save.
• Ελέγξτε frontend JavaScript errors.

Δεν εμφανίζεται το admin shipment button

• Ελέγξτε αν η παραγγελία είναι BoxNow order.
• Ελέγξτε αν έχει pickup point.
• Ελέγξτε ACL permissions.
• Ελέγξτε αν υπάρχει ήδη active delivery request και αν απαγορεύονται multiple requests.

Αποτυγχάνει η δημιουργία delivery request

• Τρέξτε bin/magento ioweb:boxnow:auth:test.
• Ελέγξτε active mode και credentials.
• Ελέγξτε Origin Location ID.
• Δείτε Delivery Requests και Integration Log.

Δεν επεξεργάζονται queue items

• Ελέγξτε Magento cron.
• Ελέγξτε queue status, attempts και locks.
• Ελέγξτε αν η παραγγελία είναι shippable.
• Ελέγξτε Delivery Requests, order comments και runtime logs.

Δεν κατεβαίνει label

• Χρησιμοποιήστε Fetch Label από Delivery Requests.
• Ελέγξτε Labels grid.
• Ελέγξτε permissions και Integration Log.
• Ελέγξτε αν υπάρχει stale ή missing file path.

Τα webhooks δεν ενημερώνουν requests

• Ελέγξτε το URL /io_boxnow/webhook/notify.
• Ελέγξτε Webhook Secret στο σωστό mode.
• Ελέγξτε signature validation.
• Ελέγξτε αν τα provider identifiers ταιριάζουν με τα records στο Magento.

22. Προσωρινή απενεργοποίηση

Για να κρυφτεί η BoxNow από το checkout χωρίς να χαθούν ρυθμίσεις και ιστορικό:

1. Πηγαίνετε στο Stores > Configuration > Sales > Shipping Methods > BoxNow.
2. Ορίστε Enabled σε No.
3. Αποθηκεύστε τη ρύθμιση.
4. Καθαρίστε Magento cache.

Αυτό σταματά νέες checkout επιλογές BoxNow, αλλά κρατά υπάρχουσες παραγγελίες, delivery requests, labels, logs και table rates.