Super Courier API

Γενικά

Για να βοηθήσει τους πελάτες της η Conquest έφτιαξε ενα API άμεσης επικοινωνίας με την cloud πλατφόρμα της

Το API λειτουργεί σαν ενα απλό webservice. Συγκεκριμένα:

είναι φτιαγμένο όμως σε PHP
οι απαντήσεις είναι σε δομή JSON Object
η σύνδεση και οι πληροφορίες ταυτότητας γίνονται με παραμέτρους GET
οι λεπτομέρειες 'voucher αποστολής' δίνονται με παραμέτρους POST, σε δομή JSON Object

Σύνδεση

Για να επικοινωνήσετε με το API θα χρειαστείτε:

το ειδικό API KEY που σας παρέχει η Conquest

Όλες οι λειτουργίες βρίσκονται στην ιντερνετική τοποθεσία που βρίσκεται και το παρόν documentation:
https://sc.hostmein.gr/

Λειτουργίες

Το API της Conquest αυτή την στιγμή παρέχει τις εξής δυνατότητες:

Προσθήκη Νέου Voucher Αποστολής
Επεξεργασία ή Ακύρωση Voucher Αποστολής
Ερώτηση για την Κατάσταση Αποστολής
Ερώτηση για Όλο το Ιστορικό Αποστολής
Ερώτηση για Όλες τις Αποστολές ενός Ημερολογιακού Διαστήματος

Προσθήκη Νέου Voucher Αποστολής

Για την επικοινωνία με το function Αποστολής Voucher, οι παράμετροι επικοινωνίας είναι οι

hash [Όπου εισάγετε το API KEY σας]

https://sc.hostmein.gr/initVoucher.php?hash=MY_API_KEY

Το function Αποστολής Voucher είναι ίσως και το πιο απαιτητικό, σε όλο το API

Για να πραγματοποιηθεί η εγγραφή της αποστολής σας στην πλατφόρμα, απαιτείται να στείλετε ενα JSON Object μέσω POST, με την εξής δομή δεδομένων:

{
	"sender":{
		"name":"Όνομα Αποστολέα", 
		"country_code":"Κωδικός Χώρας (π.χ. GR)", 
		"post_code":"Ταχυδρομικός Κώδικας", 
		"address":"Οδός και Αριθμός Αποστολής", 
		"area":"Περιοχή Αποστολής", 
		"phone1":"Τηλέφωνο Αποστολέα", 
		"phone2":"Κινητό Αποστολέα", 
		"email":"e-mail Αποστολέα",
		"notes":"Σημειώσεις Παραλαβής",
	}, 
	"recipient":{
		"name":"Όνομα Παραλήπτη", 
		"country_code":"Κωδικός Χώρας (π.χ. GR)", 
		"post_code":"Ταχυδρομικός Κώδικας", 
		"address":"Οδός και Αριθμός Παράδοσης", 
		"area":"Περιοχή Παράδοσης", 
		"phone1":"Τηλέφωνο Παραλήπτη", 
		"phone2":"Κινητό Παραλήπτη", 
		"email":"e-mail Παραλήπτη",
		"notes":"Σημειώσεις Παράδοσης",
	}, 
	"parcels":[
		{"name":"Πακέτο (α)", "type":"1", "fragile":"0", "weight":"4", "dim_m" : "10", "dim_p" : "10", "dim_y" : "10"},
		{"name":"Πακέτο (β)", "type":"2", "fragile":"0", "weight":"1", "dim_m" : "10", "dim_p" : "10", "dim_y" : "10"}
	],
	"overhead":"12.35",
	"merchandise_value":"12.35",
	"voucher_insurance":"Υ",
	"pickup_on_delivery":"Υ",
	"protocol_number":"Υ",
	"shipping_content":"3 κουτιά παπούτσια",
	"reference_numbers":"00124588745, 0114526636",
	"pickupDate":"11/05/2022",
	"sameday_delivery":"0",
	"saturday_delivery":"0",
	"selected_courier":"4",  
}

* Όλες οι ανωτέρω μετραβλητές είναι υποχρεωτικό να υπάρχουν στην δομή του JSON Object που θα λάβει το API, ενώ τα περισσότερα απο αυτά είναι και αναγκαία για την δημιουργία του Voucher. Εαν κάποια πληροφορία δεν είναι διαθέσιμη (π.χ. ο παραλήπτης δεν έχει e-mail), τότε δημιουγούμε την μεταβλητή ('email' - για να ολοκληρωθεί η εγγραφή), αλλά την αφήνουμε κενή

Επεξηγήσεις Δομής JSON:

το πεδίο overhead είναι το πεδίο αντικαταβολής.
το πεδίο merchandise_value είναι το πεδίο αξίας εμπορευμάτων.
το πεδίο voucher_insurance είναι το πεδίο επιλογής ασφάλισης της αποστολής (συμπληρώνουμε 'Y' από το YES, ή αφήνουμε κενό).
το πεδίο pickup_on_delivery είναι το πεδίο επιλογής παραλαβής κάποιου άλλου αντικειμένου με την παράδοση (συμπληρώνουμε 'Y' από το YES, ή αφήνουμε κενό).
το πεδίο protocol_number είναι το πεδίο επιλογής παραλαβής αριθμού πρωτοκόλλου με την παράδοση (συμπληρώνουμε 'Y' από το YES, ή αφήνουμε κενό).
το πεδίο shipping_content είναι το πεδίο καταχώρησης της περιγραφής του περιεχομένου της αποστολής.
το πεδίο reference_numbers είναι το πεδίο καταχώρησης σχετικών αριθμών αναφοράς.
το πεδίο sameday_delivery προγραμματίζει την αποστολή για αυθημερόν παράδοση (τιμή 1), με την ανάλογη χρέωση (αφήνουμε την τιμή 0, εαν δεν μας ενδιαφέρει).
το πεδίο saturday_delivery ανοίγει την δυνατότητα παράδοσης 'Σάββατο' (τιμή 1), με την ανάλογη χρέωση (αφήνουμε την τιμή 0, εαν δεν μας ενδιαφέρει).
το πεδίο print_position δηλώνει την θέση της πρώτης ετικέτας, στην σελίδα εκτύπωσης (αφήνουμε την τιμή 0, εαν δεν μας ενδιαφέρει)
το πεδίο type στο πακέτο αποστολής, είναι η επιλογή (1) Φάκελος (2) Κουτί (3) Παλέτα
το πεδίο weight στο πακέτο αποστολής, είναι το βάρος του πακέτου.
τα πεδία dim_m, dim_p, dim_y στο πακέτο αποστολής, είναι οι διαστάσεις του πακέτου, μήκος πλάτος και ύψος αντίστοιχα
το πεδίο selected_courier στο πακέτο αποστολής, είναι η επιλογή του ταχυμεταφορέα, από τον παρακάτω πίνακα

Κωδικός	Ταχυμεταφορέας
1	ACS
2	Γενική Ταχυδρομική
3	ΕΛΤΑ Courier
4	XP Courier

Μετά από μια επιτυχημένη εγγραφή του Νέου Voucher σας, το API θα απαντήσει μέσω POST ένα JSON Object, με την εξής δομή:

{
"barcode": "1000001474329",
"print": "https://sc.hostmein.gr/temp/voucher_1000001474329_1773934975.pdf"
}

Σε περίπτωση Σφάλματος, το API θα απαντήσει μέσω POST ένα JSON Object, με την εξής δομή:

{"error":
	{"error":"Περιγραφή Λάθους"}
}

Επεξεργασία ή Ακύρωση Voucher Αποστολής

Για την επικοινωνία με το function Επεξεργασίας Αποστολής Voucher, οι παράμετροι επικοινωνίας είναι οι

hash [Όπου εισάγετε το API KEY σας]

https://sc.hostmein.gr/updateVoucher.php?hash=MY_API_KEY

Για να πραγματοποιηθεί η εγγραφή της αποστολής σας στην πλατφόρμα, απαιτείται να στείλετε ενα JSON Object μέσω POST, με την εξής δομή δεδομένων:

{
	"barcode":"12.35",
	"status":"CANCEL",
	"selected_courier":"4",  
	"sender":{
		"name":"Όνομα Αποστολέα", 
		"country_code":"Κωδικός Χώρας (π.χ. GR)", 
		"post_code":"Ταχυδρομικός Κώδικας", 
		"address":"Οδός και Αριθμός Αποστολής", 
		"area":"Περιοχή Αποστολής", 
		"phone1":"Τηλέφωνο Αποστολέα", 
		"phone2":"Κινητό Αποστολέα", 
		"email":"e-mail Αποστολέα",
		"notes":"Σημειώσεις Παραλαβής",
	}, 
	"recipient":{
		"name":"Όνομα Παραλήπτη", 
		"country_code":"Κωδικός Χώρας (π.χ. GR)", 
		"post_code":"Ταχυδρομικός Κώδικας", 
		"address":"Οδός και Αριθμός Παράδοσης", 
		"area":"Περιοχή Παράδοσης", 
		"phone1":"Τηλέφωνο Παραλήπτη", 
		"phone2":"Κινητό Παραλήπτη", 
		"email":"e-mail Παραλήπτη",
		"notes":"Σημειώσεις Παράδοσης",
	}, 
	"parcels":[
		{"name":"Πακέτο (α)", "type":"1", "fragile":"0", "weight":"4", "dim_m" : "10", "dim_p" : "10", "dim_y" : "10"},
		{"name":"Πακέτο (β)", "type":"2", "fragile":"0", "weight":"1", "dim_m" : "10", "dim_p" : "10", "dim_y" : "10"}
	],
	"overhead":"12.35",
	"merchandise_value":"12.35",
	"voucher_insurance":"Υ",
	"pickup_on_delivery":"Υ",
	"protocol_number":"Υ",
	"shipping_content":"3 κουτιά παπούτσια",
	"reference_numbers":"00124588745, 0114526636",
	"pickupDate":"11/05/2022",
	"sameday_delivery":"0",
	"saturday_delivery":"0",
}

* Η μόνη απαραίτητες μεταβλητή από τις παραπάνω είναι το barcode.

* Η μεταβλητή status αφήνεται πάντα κενή. Η συγκεκριμένη μεταβλητή χρησιμοποιείται μόνο στην περίπτωση που επιθυμείται να ακυρωθεί η συγκεκριμένη αποστολή. Σε αυτή την περίπτωση χρησιμοποιούμε την τιμή "status" = "CANCEL".

Επεξηγήσεις Δομής JSON:

το πεδίο barcode είναι ο μοναδικός κωδικός αποστολής, όπως αυτός αναγράφεται και στην ετικέτα εκτύπωσης.
το πεδίο overhead είναι το πεδίο αντικαταβολής.
το πεδίο merchandise_value είναι το πεδίο αξίας εμπορευμάτων.
το πεδίο voucher_insurance είναι το πεδίο επιλογής ασφάλισης της αποστολής (συμπληρώνουμε 'Y' από το YES, ή αφήνουμε κενό).
το πεδίο pickup_on_delivery είναι το πεδίο επιλογής παραλαβής κάποιου άλλου αντικειμένου με την παράδοση (συμπληρώνουμε 'Y' από το YES, ή αφήνουμε κενό).
το πεδίο protocol_number είναι το πεδίο επιλογής παραλαβής αριθμού πρωτοκόλλου με την παράδοση (συμπληρώνουμε 'Y' από το YES, ή αφήνουμε κενό).
το πεδίο shipping_content είναι το πεδίο καταχώρησης της περιγραφής του περιεχομένου της αποστολής.
το πεδίο reference_numbers είναι το πεδίο καταχώρησης σχετικών αριθμών αναφοράς.
το πεδίο sameday_delivery προγραμματίζει την αποστολή για αυθημερόν παράδοση (τιμή 1), με την ανάλογη χρέωση (αφήνουμε την τιμή 0, εαν δεν μας ενδιαφέρει).
το πεδίο saturday_delivery ανοίγει την δυνατότητα παράδοσης 'Σάββατο' (τιμή 1), με την ανάλογη χρέωση (αφήνουμε την τιμή 0, εαν δεν μας ενδιαφέρει).
το πεδίο print_position δηλώνει την θέση της πρώτης ετικέτας, στην σελίδα εκτύπωσης (αφήνουμε την τιμή 0, εαν δεν μας ενδιαφέρει)
το πεδίο type στο πακέτο αποστολής, είναι η επιλογή (1) Φάκελος (2) Κουτί (3) Παλέτα
το πεδίο weight στο πακέτο αποστολής, είναι το βάρος του πακέτου.
τα πεδία dim_m, dim_p, dim_y στο πακέτο αποστολής, είναι οι διαστάσεις του πακέτου, μήκος πλάτος και ύψος αντίστοιχα

Μετά από μια επιτυχημένη εγγραφή του Νέου Voucher σας, το API θα απαντήσει μέσω POST ένα JSON Object, με την εξής δομή:

{	
"voucher_id":123456789012,
"print":"https://sc.hostmein.gr/η_τοποθεσία_του_PDF_με_τις_ετικέτες_εκτύπωσης_του_voucher.pdf"
}

Σε περίπτωση Σφάλματος, το API θα απαντήσει μέσω POST ένα JSON Object, με την εξής δομή:

{"error":
	{"error":"Περιγραφή Λάθους"}
}

Κατάσταση Αποστολής

Για την επικοινωνία με το function Κατάστασης Voucher, οι παράμετροι επικοινωνίας είναι οι

hash [το ειδικό API KEY που σας παρέχει η Conquest]
voucher_id [Όπου εισάγετε το ID της αποστολής που σας ενδιαφέρει]

https://sc.hostmein.gr/getStatus.php?hash=MY_API_KEY&voucher_id=123456789012

Μετά απο μια επιτυχημένη επικοινωνία, το API θα απαντήσει μέσω POST ένα JSON Object, με την εξής δομή:

{
	"voucher":{
		"voucher_id":"143928170214",
		"last_status_id":"5",
		"last_status":"έχει παραδοθεί",
		"last_status_time":"2015-09-07 08:30:52",
		"comment":"Κατάσταση: έχει παραδοθεί",
		"receiver_name":"Όνομα Παραλήπτη",
		"delivery_request":"1/1/2016 | Όλη την ημέρα"
	}
}

Ιστορικό Αποστολής

Για την επικοινωνία με το function Ιστορικού ενός Voucher, οι παράμετροι επικοινωνίας είναι οι

hash [το ειδικό API KEY που σας παρέχει η Conquest]
voucher_id [Όπου εισάγετε το ID της αποστολής που σας ενδιαφέρει]

https://sc.hostmein.gr/getStatusLog.php?hash=MY_API_KEY&voucher_id=123456789012

Μετά απο μια επιτυχημένη επικοινωνία, το API θα απαντήσει μέσω POST ένα JSON Object, με την εξής δομή:

{"voucher":[
	{
		"voucher_id":"123456789012",
		"status_id":"1",
		"status":"είναι προς παραλαβή από τον μεταφορέα",
		"status_time":"2016-01-01 08:08:37"
	},
	{
		"voucher_id":"123456789012",
		"status_id":"2",
		"status":"έχει παραληφθεί από τον μεταφορέα",
		"status_time":"2016-01-01 10:16:46"
	},
	{
		"voucher_id":"123456789012",
		"status_id":"4",
		"status":"είναι στον δρόμο προς παράδοση",
		"status_time":"2016-01-01 10:48:53"
	},
	{
		"voucher_id":"123456789012",
		"status_id":"5",
		"status":"έχει παραδοθεί",
		"status_time":"2016-01-01 11:13:52"
	}
]}

Οι Αποστολές μου

Για την επικοινωνία με το function Ιστορικού του λογαριασμού σας, οι παράμετροι επικοινωνίας είναι οι

hash [το ειδικό API KEY που σας παρέχει η Conquest]
voucher_id [Όπου εισάγετε το ID της αποστολής που σας ενδιαφέρει]

https://sc.hostmein.gr/getDailyReport.php?hash=MY_API_KEY&date_from=2015-01-01&date_to=2015-12-31

Μετά απο μια επιτυχημένη επικοινωνία, το API θα απαντήσει μέσω POST ένα JSON Object, με την εξής δομή:

{"voucher":[
	{
		"voucher_id":"123456789012",
		"submit_date":"2015-09-14 09:00:26",
		"receiver_name":"Όνομα Παραλήπτη",
		"last_status_id":"5",
		"last_status":"έχει παραδοθεί",
		"last_status_time":"2015-09-14 11:09:43"
	},
	{
		"voucher_id":"123456789013",
		"submit_date":"2015-11-25 14:05:17",
		"receiver_name":"Όνομα Παραλήπτη 2",
		"last_status_id":"5",
		"last_status":"έχει παραδοθεί",
		"last_status_time":"2015-11-25 16:39:37"
	},
	{
		"voucher_id":"123456789014",
		"submit_date":"2015-12-20 10:12:00",
		"receiver_name":"Όνομα Παραλήπτη 3",
		"last_status_id":"4",
		"last_status":"είναι στον δρόμο προς παράδοση",
		"last_status_time":"2015-12-20 11:25:19"
	}
]}