Courier API 1.4 - Διασύνδεση εταιριών ταχυμεταφορών (courier) με την EMDI

Η EMDI εκδίδει και ακυρώνει voucher ταχυμεταφορών καλώντας το script που ορίζεις στο αρχείο courier.ini (κύριος φάκελος EMDI/ρυθμίσεις courier).

Στον τρόπο αποστολής του παραστατικού συμπλήρωσε συντομογραφία εταιρίας (courier), χρήστη, κωδικό και sender id. Άνοιξε παραστατικό πωλήσεων και πάτησε το κουμπί voucher: αν το πεδίο voucher είναι κενό γίνεται δημιουργία· αν έχει αριθμό, ανοίγει παράθυρο κατάστασης (εκτύπωση/ακύρωση). Με δεξί κλικ στο κουμπί επιλέγεις επωνυμία αποστολέα, αν θα σταλούν είδη, και από ποια καρτέλα διεύθυνσης παίρνει τον παραλήπτη (πελάτης/αποστολή/παραλήπτης).

Πριν την κλήση η EMDI ελέγχει διεύθυνση+πόλη/περιοχή, ΤΚ, στοιχεία courier και βάρος > 0 (άθροισμα γραμμών ειδών, αν υπάρχει όγκος/εμβαδόν, χρησιμοποιεί το μεγαλύτερο από βάρος και ογκομετρικό βάρος = εμβαδόν/5000).

Ειδικές φράσεις γραμμών για έκδοση voucher

Στις γραμμές παραστατικού, με μονάδα μέτρησης ως πρόσθετο, η EMDI διαβάζει την περιγραφή και στέλνει παραμέτρους στο Courier API κατά την έκδοση voucher.

Φράση (ακριβώς / πρόθεμα)	Χρήση στην έκδοση voucher	Παράμετρος API
`ΠΑΡΑΔΟΣΗ ΣΑΒΒΑΤΟ`	Ενεργοποιεί παράδοση Σάββατο.	`saturday=1`
`ΕΙΔΙΚΗ ΔΙΑΧΕΙΡΙΣΗ`	Ακριβής τίτλος → `special=1`. Αν η περιγραφή ξεκινά/περιέχει τη φράση με επιπλέον κείμενο, στέλνεται το υπόλοιπο κείμενο.	`special`
`ΑΝΤΙΚΑΤΑΒΟΛΗ` ή `ΚΟΣΤΟΣ ΤΡΟΠΟΥ ΠΛΗΡΩΜΗΣ`	Θεωρεί αντικαταβολή ίση με το σύνολο του παραστατικού (μαζί με τον κανόνα `check_payment`).	`cashondelivery`
`ΔΕΜΑΤΑ ΑΠΟΣΤΟΛΗΣ`	Ποσότητα γραμμής = αριθμός δεμάτων. Αν υπάρχει επιπλέον κείμενο μετά τη φράση: `ποσότητα*κείμενο`.	`quantity`
`ΠΑΡΑΛΑΒΗ ΑΠΟ ΚΑΤΑΣΤΗΜΑ ΤΑΧΥΜΕΤΑΦΟΡΩΝ`	Παραλαβή από κατάστημα courier.	`office=1`
`ΑΠΟΣΤΟΛΗ ΜΕ ΧΡΕΩΣΗ ΠΑΡΑΛΗΠΤΗ`	Χρέωση παραλήπτη.	`recipientbilling=1`
`LOCKER: κωδικός`	Κωδικός locker (π.χ. Box Now / Skroutz Point). Παράδειγμα: `LOCKER: 11474`. Από e-shop bridge δημιουργείται όταν το VOUCHER είναι `\|κωδικός` (κενός αριθμός voucher).	`locker`
`ΚΟΣΤΟΣ ΜΕΤΑΦΟΡΙΚΩΝ`	Γραμμή κόστους μεταφορικών (αξία από παραγγελία e-shop / παραστατικό). Δεν αλλάζει ξεχωριστό query flag· είναι γραμμή αξίας.	—

Παράδειγμα courier.ini:

[general]
temp=https://www.sbzsystems.com/apps/emdi/tmp/
script=https://www.sbzsystems.com/apps/emdi/courier.php
pdf_software=
pdf_attributes=
check_payment=1

[general]

temp=https://www.sbzsystems.com/apps/emdi/tmp/

script=https://www.sbzsystems.com/apps/emdi/courier.php

pdf_software=

pdf_attributes=

check_payment=1

script = βασική διεύθυνση κλήσεων. temp = URL φακέλου PDF (η EMDI κατεβάζει {courier}_{voucher}.pdf). Προαιρετικά pdf_software / pdf_attributes για τοπική εκτύπωση. Με check_payment=1, αν το παραστατικό δεν είναι εξοφλημένο, η αντικαταβολή γίνεται ίση με το σύνολο· διαφορετικά 0 (εκτός αν υπάρχει γραμμή αντικαταβολής).

Η εκτύπωση ετικέτας δεν διαβάζει πλέον ενότητα [print] ανά εταιρία: μετά τη δημιουργία καλείται πάντα {script}?action=print+συντομογραφία+&voucher=…&cppass=…. Τοπικό exe μπορεί ακόμα να χρησιμοποιεί placeholders:

Placeholder	Περιγραφή
`#senderid`	Κωδικός αποστολέα
`#courieruser`/`#courierpass`	Σύνδεση courier
`#cpuser`/`#cppass`	Χρήστης/κωδικός εφαρμογής
`#voucherno`	Αριθμός voucher

Endpoints

Μέθοδος	Όνομα	Παράδειγμα
POST	`print` (δημιουργία)	`{script}?…&action=print&…` + form body
GET	`view`	`{script}?…&action=view&…`
GET	`cancel{courier}`	`…&action=cancelspeedex&…`
GET	`print{courier}`	`{script}?action=printspeedex&voucher=…`

Δημιουργία = POST hybrid (παράμετροι στο URL + σώμα company_data, products, προαιρετικά pdf). Άνοιγμα/ακύρωση/εκτύπωση ετικέτας = GET. Στην ELTA τα κουμπιά εκτύπωσης/ακύρωσης στο παράθυρο voucher κρύβονται.

POSTprint· δημιουργία voucher · text/plain

{script}?courier=&rec_date=&courieruser=&courierpass=&cpuser=&cppass=&senderid=&rec_name=&rec_company=&rec_floor=&rec_address=&rec_area=&rec_zip=&rec_telephone=&rec_mobile=&rec_email=&quantity=&weight=&notes=&cashondelivery=&relateddoc=&rec_country=&sendername=&action=print&emdiuser=&saturday=&exact=&special=&office=&recipientbilling=&locker=

Απάντηση: αριθμός_voucher|μήνυμα. Αν λείπει ο αριθμός (ή περιέχει αλλαγή γραμμής), η EMDI δείχνει το μήνυμα μετά το | και σταματά.

Query	Περιγραφή
`courier`	Συντομογραφία (speedex, acs, elta, dhl, …)
`rec_date`	Ημ/νία αποστολής `yyyymmdd` (παράδοση ή ημ/νία παραστατικού)
`courieruser`/`courierpass`	Στοιχεία σύνδεσης
`cpuser`/`cppass`	Χρήστης/κωδικός εφαρμογής
`senderid`	Κωδικός αποστολέα
`rec_*`	Παραλήπτης: όνομα, εταιρία, όροφος (ΤΘ), διεύθυνση, περιοχή+πόλη, ΤΚ, τηλ., κινητό, email, χώρα
`quantity`	ΔΕΜΑΤΑ ΑΠΟΣΤΟΛΗΣ (προεπιλογή 1· από γραμμή `ΔΕΜΑΤΑ ΑΠΟΣΤΟΛΗΣ`)
`weight`	Υπολογισμένο βάρος
`notes`	Σχόλιο παραστατικού (`#` → κενό)
`cashondelivery`	Αντικαταβολή (βλ. check_payment/γραμμές)
`relateddoc`	Σειρά + αριθμός παραστατικού
`sendername`	Επωνυμία αποστολέα (εταιρία ή επιλογή μενού)
`action`	Πάντα `print`
`emdiuser`	Χρήστης άδειας EMDI
`saturday`	ΠΑΡΑΔΟΣΗ ΣΑΒΒΑΤΟ: 1/0
`exact`	Ώρα `HH:nn` ή `HH:nn-HH:nn` αν είναι συμπληρωμένα ταυτόχρονα τα Παραλαβή από και Παραλαβή έως
`special`	ΕΙΔΙΚΗ ΔΙΑΧΕΙΡΙΣΗ (1 ή κείμενο μετά τον τίτλο)
`office`	ΠΑΡΑΛΑΒΗ ΑΠΟ ΚΑΤΑΣΤΗΜΑ ΤΑΧΥΜΕΤΑΦΟΡΩΝ: 1/0
`recipientbilling`	ΑΠΟΣΤΟΛΗ ΜΕ ΧΡΕΩΣΗ ΠΑΡΑΛΗΠΤΗ: 1 ή κενό
`locker`	Κωδικός locker από γραμμή `LOCKER: κωδικός`

Σώμα POST (form fields):

Field	Περιγραφή
`company_data`	Στοιχεία εταιρίας EMDI: `διεύθυνση\|ΤΚ\|πόλη\|χώρα\|τηλέφωνα\|ΑΦΜ`
`products`	Γραμμές ειδών αν ενεργό «είδη στο voucher» ή courier=`dhl`. Μορφή ανά γραμμή: `κωδικός\|περιγραφή\|ποσότητα\|σύνολο_με_ΦΠΑ\|βάρος` και προαιρετικά `\|taric`· τέλος γραμμής `\n`. Σε DHL με είδη ξεκινά με `_`.
`pdf`	Base64 PDF παραστατικού — υποχρεωτικό αρχείο για DHL εκτός ΕΕ (ζώνη παραλήπτη ≠ EU)· αλλιώς παραλείπεται αν δεν υπάρχει αρχείο.

GETview· άνοιγμα και ιχνηλάτηση

{script}?courier=&rec_date=&courieruser=&courierpass=&cpuser=&cppass=&senderid=&relateddoc=&voucher=&action=view&emdiuser=&lang=

Καλείται όταν υπάρχει ήδη αριθμός voucher. Η EMDI ανοίγει τον σύνδεσμο και δείχνει το HTML στο παράθυρο voucher.

GETcancel{courier}· ακύρωση

{script}?courier=&…&voucher=&action=cancel{courier}&emdiuser=&lang=

Από το URL του view αντικαθιστά το action=view με action=cancel + συντομογραφία (π.χ. cancelspeedex). Όχι σκέτο action=cancel. Μετά καθαρίζει το πεδίο voucher στο παραστατικό.

GETprint{courier}· ετικέτα PDF

{script}?action=print{courier}&voucher=#voucherno&cppass=#cppass

Μετά επιτυχή δημιουργία η EMDI καλεί αυτόν τον σύνδεσμο, κατεβάζει το PDF στο files\vouchers\{courier}_{voucher}.pdf και αν έχει οριστεί πρόγραμμα PDF το εκτυπώνει.
Αλλιώς ανοίγει απευθείας το URL εκτύπωσης.

Ενδεικτικό παράδειγμα σε PHP (ανά εταιρία δικό της include):

<?php
require_once('courier_common.php');
$couriername = $_GET['courier'];
$action = $_GET['action'];
// … read the other query fields the same way …
// On create, also read POST: pdf, company_data, products
if ($couriername == 'speedex'
|| $action == 'printspeedex'
|| $action == 'receiptspeedex'
|| $action == 'cancelspeedex') {
require_once('courier_speedex.php');
}
// Create success response (plain text):
// echo $voucher_code . '|' . $message;

<?php

require_once('courier_common.php');

$couriername = $_GET['courier'];

$action = $_GET['action'];

// … read the other query fields the same way …

// On create, also read POST: pdf, company_data, products

if ($couriername == 'speedex'

|| $action == 'printspeedex'

|| $action == 'receiptspeedex'

|| $action == 'cancelspeedex') {

require_once('courier_speedex.php');

}

// Create success response (plain text):

// echo $voucher_code . '|' . $message;

Η μορφή απάντησης πρέπει να είναι voucher|μήνυμα ώστε η EMDI να αποθηκεύει τον αριθμό στο παραστατικό.