User Guide – BoxNow Shipping για OpenMage / Magento 1

Ο οδηγός καλύπτει τις λειτουργίες που μπορεί να χειριστεί ο διαχειριστής από το Magento admin και ο πελάτης από το checkout.

1. Κεντρική παραμετροποίηση

Admin path: System -> Configuration -> Sales -> Shipping Methods -> BoxNow

General Settings

• Enabled: ενεργοποιεί ή απενεργοποιεί το BoxNow carrier.
• Title: τίτλος carrier που εμφανίζεται στο checkout.
• Method Name: όνομα μεθόδου κάτω από το carrier.
• Sort Order: σειρά εμφάνισης ανάμεσα στις μεθόδους αποστολής.
• Free Shipping Threshold: ποσό παραγγελίας από το οποίο η αποστολή γίνεται δωρεάν.
• Condition: table-rate condition για τον υπολογισμό κόστους.
• Maximum Package Weight: κρύβει το BoxNow όταν το βάρος ξεπερνά το όριο.
• Calculate Handling Fee / Handling Fee: προσθέτει handling fee στο shipping rate.
• Include Virtual Products in Price Calculation: ορίζει αν virtual προϊόντα επηρεάζουν το rate calculation.
• Ship to Applicable Countries / Specific Countries: χώρες όπου προσφέρεται το BoxNow.
• Show Method if Not Applicable / Error Message: συμπεριφορά όταν η μέθοδος δεν είναι διαθέσιμη.

Rate Files

Το module χρησιμοποιεί δικό του BoxNow table-rate table. Ο διαχειριστής μπορεί να κάνει export το τρέχον CSV και import νέο CSV ανά website scope. Το αρχείο περιλαμβάνει country, region/state, postcode, condition value και shipping price.

Widget & Checkout Behavior

• BoxNow Widget Type: iframe ή popup.
• Allow Return: στέλνει return flag στο provider request.
• Default Parcel Size: small, medium ή large ως default compartment size.
• Admin Submission Mode: sync για άμεση αποστολή ή async για background queue.
• Cash on Delivery Methods: payment methods που στέλνονται στο BoxNow ως COD με amount to be collected.

Troubleshooting

• Enable BoxNow Widget Debug Logging: πρόσθετα frontend diagnostics.
• Test Email for Method Availability: περιορίζει την εμφάνιση του BoxNow σε συγκεκριμένο customer/quote email για ελεγχόμενες δοκιμές.

Environment and Authentication

• Mode: sandbox ή production.
• API URL / Location API URL: provider endpoints ανά περιβάλλον.
• Client ID / Client Secret: credentials για API calls.
• Partner ID: provider partner id.
• Origin: σημείο αποστολέα που χρησιμοποιείται στα delivery requests.
• Webhook Secret: μυστικό για HMAC validation των inbound webhooks.

2. Checkout flow

1. Ο πελάτης επιλέγει BoxNow ως shipping method.
2. Εμφανίζεται ο pickup point selector.
3. Ο πελάτης αναζητά και επιλέγει pickup point.
4. Το module αποθηκεύει pickup point id και details στο quote.
5. Πριν το order placement, το module ελέγχει ότι έχει γίνει επιλογή pickup point.
6. Στο submit, τα δεδομένα μεταφέρονται από quote σε order.

3. Checkout compatibility

Το module περιλαμβάνει layout integration για native Magento/OpenMage checkout, Amasty checkout και TM FireCheckout. Στο FireCheckout ο selector φορτώνεται κάτω από τις shipping methods τόσο στο αρχικό checkout render όσο και στα AJAX refreshes του checkout.

4. Τιμές αποστολής

Το rate υπολογίζεται από τα BoxNow table rates και σέβεται active status, χώρες, test email, max package weight, free shipping threshold, Magento free-shipping flag, handling fee και virtual product price option. Αν δεν βρεθεί rate στο website scope, μπορεί να χρησιμοποιηθεί default-scope rate.

5. Admin order flow

Στο BoxNow order εμφανίζεται pickup point summary και action Ship with BoxNow όταν δεν υπάρχει ήδη ενεργό/successful delivery request. Η φόρμα επιτρέπει έλεγχο και αλλαγή customer name, phone, email, parcel size, delivery street/city/postcode/region/country, parcel description, parcel weight, parcel value και preferred time window.

6. Delivery Requests

Admin path: Sales -> BoxNow -> Delivery Requests

Το grid εμφανίζει και αποθηκεύει order ids, pickup point, request id, delivery request reference, provider order/delivery id, status, errors, labels, parcels, outbound payload, provider response και fulfillment flags. Από εδώ ο διαχειριστής μπορεί να κάνει CSV/Excel export, label download, label fetch, parcel cancellation, Magento shipment update, tracking update και customer notification.

7. Queue

Admin path: Sales -> BoxNow -> Queue

Χρησιμοποιείται για background processing. Τα queue rows περιέχουν order increment id, request id, payload, status, attempts, last attempt, processed at και created at.

8. Integration Log

Admin path: Sales -> BoxNow -> Integration Log

Καταγράφει inbound webhook calls και provider/API diagnostics: request method, URL, body, query params, masked token/signature metadata, response status/body και linked entity.

9. Webhook

Endpoint: POST /ioweb_boxnow/webhook/notify

Όταν έχει οριστεί webhook secret, το module κάνει signature validation. Invalid method, invalid payload και invalid signature απορρίπτονται και καταγράφονται. Τα αποδεκτά events μπορούν να ενημερώσουν delivery request status με request id/order number, delivery request reference ή parcel id.

10. Cron

Απαιτείται να λειτουργεί το Magento cron του server. Το module δηλώνει:

• ioweb_boxnow_process_queue: κάθε 5 λεπτά.
• ioweb_boxnow_reconcile_parcels: κάθε 15 λεπτά.
• ioweb_boxnow_cleanup_logs: καθημερινά στις 02:17.

Τυπικό server cron: */5 * * * * /usr/bin/php /path/to/magento/cron.php

11. Go-live checklist

1. Ρυθμίστε sandbox credentials και origin.
2. Κάντε import test table rates.
3. Χρησιμοποιήστε Test Email για ελεγχόμενο checkout test.
4. Δοκιμάστε pickup point selection.
5. Υποβάλετε delivery request από admin.
6. Ελέγξτε label download, shipment και tracking.
7. Ρυθμίστε production credentials, origin, partner id και webhook secret.
8. Επιβεβαιώστε ότι τρέχει Magento cron.
9. Αφαιρέστε το test email gate και ενεργοποιήστε το carrier στο production scope.