Tailor Made

Πριν ξεκινήσετε

Βήμα 1: Στήσιμο

OAUTH_CLIENT_ID

Κρατήστε αυτή την τιμή ιδιωτική και ασφαλή! Αυτή είναι η OAuth2 Client ID που θα χρησιμοποιήσετε για να πιστοποιηθείτε με τα Partner API.

OAUTH_CLIENT_SECRET

Κρατήστε αυτή την τιμή ιδιωτική και ασφαλή! Αυτή είναι η OAuth2 Client Secret που θα χρησιμοποιήσετε για να πιστοποιηθείτε με τα Partner API.

API_URL

Αυτή είναι η Base URL για το Partner API, στo οποίο θα πρέπει να προσαρτίσετε τα σχετικά endpoint paths.

Βήμα 2: Περιβάλλοντα

Sandbox /Stage

Περιβάλλον με περιορισμένες δυνατότητες όπου θα μπορείτε να δοκιμάσετε την διασύνδεση.

Production

Χρησιμοποιείτε αυτό το περιβάλλον με προσοχή, καθώς είναι ζωντανό και απευθύνετε σε πραγματικούς χρήστες.

Βήμα 3: Διαδικασία requesting a delivery

Ακολουθήστε τα βήματα ώστε να ζητήσετε επιτυχώς μία παράδοση και να πράξετε με τους σχετικούς τρόπους:

3.1 Πιστοποιείστε τον εαυτό σας /auth sessions

Η πιστοποίηση γίνεται βάση του OAuth 2.0 standard, μέσω των Client Credentials.

Για να χρησιμοποιήσετε τα API, πρέπει να βάλετε το access token στην επικεφαλήδα Authorization ως Bearer token.

Παράδειγμα ορθής διασύνδεσης:

POST /api/v1/ auth sessions

{

"grant_type”: "client_credentials”,

"client_id": “string”,

"client_secret": “string”

}

Status Code 200

{

"access_token”: “client_credentials”,

"token_type": “Bearer”,

"expires_in”: 3600

}

Επιπλέον απαντήσεις που μπορούν να προκύψουν:

400

Ο σέρβερ δεν μπορεί ή δε θα προχωρήσει το αίτημα λόγω κάποιου δικού σας λάθους (π.χ. λάθος σύνταξη, λάθος μήνυμα request). Πρέπει να ξαναδιαμορφώσετε το request πρωτού το ξαναστείλετε.

401

Μη εξουσιοδωτημένος. Χρησιμοποιείτε ένα ληγμένο Αccess token ή προσπαθείτε να ξεκινήσετε ένα Auth session με λάθος δεδομένα.

403

Ο λογαριασμός σας απενεργοποιήθηκε. Επικοινωνήστε με την υποστήριξη πελατών.

3.2 Λίστα με όλες τις διαθέσιμες origins /origins

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

Μπορείτε να δείτε όλες τις αποθήκες σας χρησιμοποιόντας /origins που έχει τις ίδιες παραμέτρους σαν την /destinations όπου δεν δηλώνετε συγκεκριμλενε παραμλετρους latlng, radius ή requiredSize, αλλά το locationType σαν “warehouse”. Αναφέρεστε σε αυτή την τοποθεσία μέσω του ID (locationid).

Επιπέον υπάρχει μια συγκεκριμένη τοποθεσία, η any-apm που μπορεί να δηλωθεί με τον ίδιο τροπο χρησιμοποιώντας locationType ως “any-apm”, επιστρέφει μόνο ένα location-any-apm. Μπορείτε να αναφέρεστε σε αυτό με τοs ID (locationid) του. Αυτή η χρήση θα επεξηγηθεί στην επόμενη ενότητα.

Παρακάτω βρίσκονται οι παράμετροι, διαθέσιμες σε εσάς για για να φιλτράρετε όλα τα Origin locations:

Παράδειγμα ορθής διασύνδεσης:

GET /api/v1/ origins

curl -X ‘GET’\

'…/origins\

-H 'accept: application/json’

Status Code 200

{

"data": [

{

"id": "string",

"type": "warehouse",

"image": "https://via.placeholder.com/175",

"lat": "48.940819584637266",

"lng": "12.366962491028423",

"title": "Warehouse 1",

"name": "Main Warehouse",

"addressLine1": "ΛΕΩΦΟΡΟΣ ΚΗΦΙΣΙΑΣ 155",

"addressLine2": "ΑΘΗΝΑ",

"postalCode": "14661",

"country": "GR",

"note": "Next to Super market"// can be noll

}

]

}

Επιπλέον απαντήσεις που μπορεί να προκύψουν:

Error Code

400

Ο σέρβερ δεν μπορεί ή δε θα προχωρήσει το αίτημα λόγω κάποιου δικού σας λάθους (π.χ. λάθος σύνταξη, λάθος μήνυμα request). Πρέπει να ξαναδιαμορφώσετε το request πρωτού το ξαναστείλετε.

401

Μη εξουσιοδωτημένος. Χρησιμοποιείτε ένα ληγμένο Αccess token ή προσπαθείτε να ξεκινήσετε ένα Auth session με λάθος δεδομένα.

403

Ο λογαριασμός σας απενεργοποιήθηκε. Επικοινωνήστε με την υποστήριξη πελατών.

3.3.Λίστα με όλες τους διαθέσιμους προορισμούς /destinations

Αυτή ή κλήση θα απαριθμήσει όλες τα διαθέσιμες τοποθεσίες ΑPM (Automatic Parcel Machine) που μπορούμε να παραδώσουμε τα δέματά σας.

Παρακάτω βρίσκοντε οι παράμετροι διαθέσιμες ώστε να φιλτράρετε όλες τις τοποθεσίες των ΑΡΜ:

Παράδειγμα ορθής διασύνδεσης:

GET api/v1/ destinations

curl X ‘GET’\

‘.../destinations\

-H 'accept: application/json'

Status Code 200

{

"data": [

{

"id": "string",

"type": "apm",

"image": "https://via.placeholder.com/150",

"lat": "48.78081955454138",

"lng": "12.446962472273063",

"title": "ΠΑΝΤΕΛΟΓΛΟΥ ΔΗΜΗΤΡΗΣ",

"name": "ΠΑΝΤΕΛΟΓΛΟΥ ΔΗΜΗΤΡΗΣ",

"addressLine1": "ΛΕΩΦΟΡΟΣ ΕΙΡΗΝΗΣ 28",

"addressLine2": "string",

"postalCode": "15121",

"country": "GR",

"note": "You can find it behind the pet shop"

}

]

}

Αλλιώς, αναφερθείτε στο χωρίο 4 για ένα απόσπασμα Java Script που μπορείτε να συμπεριλάβετε στην σελίδα σας για να φαίνονται όλα τα διαθέσιμα ΑΡΜ μέσω ενός pop-up/iframe widget, ή για μια σύντομη περιγραφή επιτυχούς διασύνδεσης custom map.

id

Όταν ζητάτε μία παράδοση, θα αναφέρεστε σε αυτά τα αρχεία με το ID τους, συχνότερα το:

locationId

Επιπλέον απαντήσεις που μπορεί να προκύψουν:

Error Code

400

Ο σέρβερ δεν μπορεί ή δε θα προχωρήσει το αίτημα λόγω κάποιου δικού σας λάθους (π.χ. λάθος σύνταξη, λάθος μήνυμα request). Πρέπει να ξαναδιαμορφώσετε το request πρωτού το ξαναστείλετε.

401

Μη εξουσιοδωτημένος. Χρησιμοποιείτε ένα ληγμένο Αccess token ή προσπαθείτε να ξεκινήσετε ένα Auth session με λάθος δεδομένα.

403

Ο λογαριασμός σας απενεργοποιήθηκε. Επικοινωνήστε με την υποστήριξη πελατών.

3.4 Ζήτησε μία παράδοση /delivery requests

Χρησιμοποιήστε αυτό για να ζητήετε μία παραγγελία δέματος (ή πολλών δεμάτων). Αυτή είναι η κύρια κλήση που θα χρησιμοποιείτε για να δημιουργήσετε κάθε τύπο παραγγελιών.

Μόλις μία επιτυχή παραγγελία δημιουργηθεί:

• (optional) Θα σας αποστέλλουμε e-mail που θα σας ειδοποιεί για μία επιτυχώς δημιουργημένη παραγγελία με μία ετικέτα PDF. Η παράμετρος notifyOnAccepted αναπαράγεται από αυτήν τη λειτουργία (Βλέπε Appendix 6.3).
• (Described below) Εναλλακτικά, μπορείτε να λάβετε το αρχείο PDF για κάθε πακέτο μέσω της κλήσης: GET/parcels/{id}/label.pdf έπειτα εκυπώνετε το PDF και το κολλάτε στο πακέτο/πακέτα.
• Στέλνουμε τον courier να παραλλάβει τα πακέτα στις προκαθορισμένες ώρες παραλαβής.
• Επίσης ενημερώνουμε τον πελάτη.

1. Παραλάβαμε την εντολή παραγγελίας και ένα δέμα θα παραδοθεί σε αυτούς.
2. Παραδόσαμε επιτυχώς το πακέτο τους στο καθορισμένο APM με τις απαραίτητες λεπτομέριες για την παραλαβή του πακέτου.

Παράδειγμα επιτυχούς διασύνδεσης:

POST api/v1/ delivery requests

{

"orderNumber": “string”,

"invoiceValue": “25.50”,

"paymentMode":”prepaid”,

”amountToBeCollected": “0.00",

"allowReturn”: true,

"origin”:{

"contactNumber":“+30 21 4 655 1234”,

"contactEmail”: “partner.example@boxnow.gr”,

"contactName": “Kostas Kostantinidis",

"locationId":”string”

},

“destination”:{

"contactNumber": "+30 69 1 234 1234”,

"contactEmail”: “customer.example@boxnow.gr”,

"contactName” "Yiannis Papadopoolos",

"locationId":”string”

},

"items”: [

{

"id": “string”,

"name": “Smartphone”

"value”: “3.45”,

"weight”: 0

}

]

}

items: weight

Αν το βάρος του ατικειμένου είναι άγνωστο δώστε 0.

Ο αριθμός που δίνεται σε αυτό το πεδίο θα πρέπει να είναι ακέραιος

Αυτοί οι παράμετροι είναι το κύριο αναγνωριστικό για τις τοποθεσίες παραλαβής και παράδοσης:

origin: locationId

Η αποθήκη όπου το δέμα θα παραληφθεί.

destination: locationId

Automatic Parcel Machine (APM) τοποθεσία της θυρίδας παράδοσης

Επίσης,

μη ξεχνάτε να μας μεταφέρετε τα ακόλουθα προσωπικά στοιχία με κάθε παραγγελία:

Αποστολέας:

1. Όνομα

Παραλήπτης:

1. Όνομα
2. Τηλεφωνικός αριθμός
3. Email

Status Code 200

{

"referenceNumber":”string”,

"parcels”:[

{

"id":”string”

}

]

}

Σημείωση: Στο παραπάνω παράδειγμα, το αντικείμενο αφορά στο πακέτο, αλλά το ID του πακέτου είναι μοναδικό ID μέσω του e-shop (νούμερο αναφοράς, αν θέλετε). Εάν δεν έχετε μοναδικό ID για κάθε αντικείμενο τότε δημιουργείτε μέσω του αριθμού παραγγελίας με ακόλουθο το νούμερο του αντικειμένου ή με όποια σειρά θέλετε εσείς. Ενώ η ταυτότητα δέματος (parcel ID) είναι εσωτερική στην BoxNow, μια μοναδική ID χρησιμοποιείται επιπλέον που αφορά αυτό το δέμα.

Για αποστολές από APM μπορείτε να χρησιμοποιείτε ως origin το any APM και προορισμό συγκεκριμένο APM.

Για παράδοση στο APM όπου θα παραλλάβει ο πελάτης μπορείτε να χρησιμοποιείτε και origin and destination location any-APM.

Επιπλέον απαντήσεις, που μπορεί να προκύψουν:

Error Code

400

Ο σέρβερ δεν μπορεί ή δε θα προχωρήσει το αίτημα λόγω κάποιου δικού σας λάθους (π.χ. λάθος σύνταξη, λάθος μήνυμα request). Πρέπει να ξαναδιαμορφώσετε το request πρωτού το ξαναστείλετε.

401

Μη εξουσιοδωτημένος. Χρησιμοποιείτε ένα ληγμένο Αccess token ή προσπαθείτε να ξεκινήσετε ένα Auth session με λάθος δεδομένα.

403

Ο λογαριασμός σας απενεργοποιήθηκε. Επικοινωνήστε με την υποστήριξη πελατών.

3.5 Fetch a PDF label /parcels/{id}/label.pdf

Use this call to request a .pdf file with a label you shoold print a stick onto each parcel.

Only this parameter is available to you:

    
<div id="boxnowmap"></div>
    
<script type="text/javascript">
    
var _bn_map_widget_config = {
    
partnerId: 123,
    
parentElement: "#boxnowmap"
    
afterSelect: function(selected){
    
alert(selected.boxnowLockerPostalCode);
    
    
alert(selected.boxnowLockerAddressLine1);
    
    
alert(selected.boxnowLockerId);

    
    
}
    
};
    
    
(function(d){var e = d.createElement("script");e.src = "https://widget-cdn.boxnow.gr/map-widget/client/v5.js";e.async = true;e.defer = true;d.getElementsByTagName("head")[0].appendChild(e);})(document);</script>

	

<div id="boxnowmap"></div>