Δημιουργία αποστολής

Η κλήση POST /shipments εκδίδει το voucher μιας παραγγελίας σας με μια courier, όπως η έκδοση voucher από το περιβάλλον πελάτη. Επιστρέφει την αποστολή (ίδιο αντικείμενο με το GET /shipments/{voucher}).

Δεν υπάρχει περιβάλλον δοκιμών (sandbox)

Οι courier δεν προσφέρουν sandbox. Κάθε επιτυχημένη κλήση POST /shipments εκδίδει πραγματικό voucher στην courier και χρεώνει το υπόλοιπο του λογαριασμού σας. Η ακύρωση υποστηρίζεται μόνο για ACS, BoxNow και ELTA και δεν επιστρέφει τη χρέωση. Για δοκιμές της ενσωμάτωσής σας χρησιμοποιήστε μια παραγγελία που πράγματι θα αποσταλεί, ή δοκιμάστε πρώτα τις κλήσεις ανάγνωσης.

WARNING

Θα πρέπει να συμπεριλάβετε το API Token σας σε κάθε αίτημα ως Bearer Token. Αντικαταστήστε το YOUR_TOKEN με το API Token του καταστήματος (chub_...). Δείτε το Overview.

Method	URI	Headers
POST	`/api/v2/shipments`	`Authorization`: `Bearer YOUR_TOKEN` `Content-Type`: `application/json`

Μεταβλητές αποστολής

Οι παράμετροι στέλνονται στο body ως JSON.

Variable Name	Type	Usage	Required
`order_id`	`Integer`	Το εσωτερικό ID της παραγγελίας στο CourierHub (το `order.id` των αποστολών), όχι το ID ή ο αριθμός της παραγγελίας στο e-shop. Η παραγγελία πρέπει να ανήκει στον λογαριασμό σας, αλλιώς η απάντηση είναι `404`.	*
`courier_id`	`Integer`	Το ID της courier, από το GET /couriers. Πρέπει να υπάρχει, αλλιώς `422 validation_failed`.	*
`services`	`Array` ή `null`	Επιπλέον υπηρεσίες της courier: λίστα με τιμές από τον πίνακα Υπηρεσίες, χωρίς διπλότυπα.
`compartment_size`	`Integer` ή `null`	Μέγεθος θυρίδας Box Now: `1` (Small), `2` (Medium) ή `3` (Large). Δείτε Μέγεθος θυρίδας.
`billing_code`	`String` ή `null`	Κωδικός χρέωσης ACS (έως 50 χαρακτήρες), για λογαριασμούς ACS με πολλούς κωδικούς χρέωσης. Δείτε Κωδικός χρέωσης ACS.

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

Υπηρεσίες (`services`)

Τιμή	Περιγραφή	Courier που τη χρησιμοποιούν
`saturday`	Παράδοση το Σάββατο.	ACS, Speedex, Γενική Ταχυδρομική, couriers της ομάδας Hermes (π.χ. Red Courier, Courier4U)
`epistrofi`	Παράδοση / Παραλαβή (υπηρεσία επιστροφής).	ACS, Γενική Ταχυδρομική, Kronos Express, couriers της ομάδας Hermes
`receive_from_reception`	Παραλαβή από κατάστημα της courier.	ACS, ELTA, Speedex, Γενική Ταχυδρομική, couriers της ομάδας Hermes

Οι τιμές είναι οι ίδιες με τις Υπηρεσίες της έκδοσης voucher στο περιβάλλον πελάτη. Μια υπηρεσία του πίνακα που δεν υποστηρίζει η courier αγνοείται. Κάθε άλλη τιμή (ή μια διπλή τιμή) απορρίπτεται με 422 validation_failed, με το σφάλμα στο errors.services.N. Οι υπηρεσίες που έχουν ήδη αντιστοιχιστεί αυτόματα στην παραγγελία (π.χ. από τον τρόπο αποστολής του e-shop) εφαρμόζονται πάντα, μαζί με όσες στέλνετε.

Μέγεθος θυρίδας Box Now (`compartment_size`)

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

Κωδικός χρέωσης ACS (`billing_code`)

Χρησιμοποιείται μόνο από την ACS. Χωρίς billing_code χρησιμοποιείται ο κωδικός της σύνδεσης ACS σας. Αν έχετε ενεργοποιήσει πολλούς κωδικούς χρέωσης, χωρίς billing_code χρησιμοποιείται ο κωδικός της χώρας του παραλήπτη όταν υπάρχει μόνο ένας. Αν υπάρχουν περισσότεροι για τη χώρα, ή στείλετε κωδικό που δεν αντιστοιχεί στη χώρα του παραλήπτη, η απάντηση είναι 422 courier_validation_failed με σφάλμα στο billing_code.

Επαναλήψεις και διπλές αποστολές

Για κάθε ζεύγος παραγγελία + courier εκδίδεται ένα voucher:

Αν η παραγγελία έχει ήδη voucher με την ίδια courier, η κλήση επιστρέφει αυτό το voucher με 200 OK, χωρίς νέα κλήση στην courier και χωρίς νέα χρέωση. Ο έλεγχος αυτός γίνεται πρώτος, πριν από τα όρια, το υπόλοιπο και τη σύνδεση της courier. Έτσι μια επανάληψη (π.χ. μετά από timeout του δικτύου σας) δεν χρεώνει ποτέ δεύτερη φορά και δεν αποτυγχάνει εκεί που πέτυχε η πρώτη κλήση.
Νέο voucher επιστρέφεται με 201 Created.
Αν την ίδια στιγμή εκδίδεται ήδη voucher για την ίδια παραγγελία και courier (π.χ. δύο ταυτόχρονες κλήσεις), η δεύτερη παίρνει 409 shipment_in_progress με κεφαλίδα Retry-After: 5. Ξαναδοκιμάστε μετά από τόσα δευτερόλεπτα: θα πάρετε το voucher με 200.
Μετά από ακύρωση του voucher μπορεί να εκδοθεί νέο voucher για την ίδια παραγγελία και courier (με νέα χρέωση).
Με άλλη courier η ίδια παραγγελία μπορεί να πάρει δεύτερο voucher (με δική του χρέωση).

Τι γίνεται μετά την έκδοση

Όπως και στην έκδοση από το περιβάλλον πελάτη:

χρεώνεται το υπόλοιπο με το κόστος του voucher (δείτε voucher_cost στο GET /account) και η κίνηση εμφανίζεται στις κινήσεις υπολοίπου με transaction_type voucher. Τα vouchers που χωράνε στο μηνιαίο πακέτο της συνδρομής σας κοστίζουν 0.00 (η συνδρομή χρεώνεται ξεχωριστά, μία φορά ανά περίοδο). Τα επιπλέον vouchers χρεώνονται με την τιμή του πακέτου σας. Τα ακυρωμένα vouchers μετράνε κανονικά στο πακέτο της περιόδου,
η παραγγελία γίνεται shipped και, αν είχε εισαχθεί από e-shop Shopify, WooCommerce ή OpenCart, ενημερώνεται ως ολοκληρωμένη στο e-shop. Οι παραγγελίες που δημιουργήσατε με POST /api/v2/orders δεν συγχρονίζονται ποτέ με το e-shop, οπότε δεν ενημερώνεται τίποτα εκεί,
στέλνεται SMS / Viber στον παραλήπτη, αν το έχετε ενεργοποιήσει,
στέλνεται webhook shipment.created.

Απάντηση αιτήματος

Η εφαρμογή σας επιστρέφει δεδομένα σε μορφή JSON, μέσα στο κλειδί data, με τα πεδία που περιγράφονται στο GET /shipments/{voucher}. Το HTTP status είναι 201 για νέο voucher και 200 για voucher που υπήρχε ήδη.

Variable Name	Type	Description
`data`	`Object`	Η αποστολή (shipment). Το `voucher_number` είναι ο αριθμός voucher της courier, που χρησιμοποιείτε στις υπόλοιπες κλήσεις (π.χ. ετικέτα).

Παράδειγμα επιτυχημένης δημιουργίας (201 Created).

json

{
    "data": {
        "voucher_number": "7012345679",
        "courier": {
            "id": 8,
            "name": "ACS"
        },
        "status": "created",
        "status_label": "Δημιουργήθηκε",
        "delivered_at": null,
        "returned_at": null,
        "cod_amount": "0.00",
        "cod_paid": false,
        "last_event": null,
        "tracking_url": "https://courierhub.gr/t/vhFgdvcS",
        "created_at": "2026-10-19T07:15:00Z",
        "order": {
            "id": 3,
            "order_id": "5012345678903",
            "order_number": "#12347",
            "store": {
                "id": 1,
                "name": "Το Κατάστημά μου"
            }
        }
    }
}

Η ίδια κλήση αργότερα επιστρέφει ακριβώς το ίδιο σώμα με 200 OK (το voucher που υπάρχει ήδη), χωρίς νέα χρέωση.

Σφάλματα

Όλα τα σφάλματα έχουν τη μορφή σφαλμάτων του v2. Στα σφάλματα 4xx δεν έχει εκδοθεί voucher και δεν έχει γίνει χρέωση.

`code`	HTTP	Πότε
`validation_failed`	422	Λείπει ή δεν είναι έγκυρο κάποιο πεδίο του body (π.χ. άγνωστο `courier_id`, `compartment_size` εκτός `1`-`3`).
`not_found`	404	Η παραγγελία δεν υπάρχει ή δεν ανήκει στον λογαριασμό σας.
`shipment_limit_reached`	422	Έχετε φτάσει το όριο αποστολών της τρέχουσας περιόδου. Τα ακυρωμένα vouchers μετράνε στο όριο.
`insufficient_balance`	422	Το διαθέσιμο υπόλοιπο δεν καλύπτει το κόστος του voucher. Ελέγχεται ακριβώς το ποσό που θα χρεωθεί, οπότε ένα voucher μέσα στο πακέτο της συνδρομής (κόστος `0.00`) δεν απορρίπτεται ποτέ για υπόλοιπο. Το `message` αναφέρει το απαιτούμενο και το διαθέσιμο ποσό. Το ίδιο `code` δίνεται όταν η δοκιμαστική περίοδος έχει λήξει και το διαθέσιμο υπόλοιπο δεν φτάνει για τη μηνιαία συνδρομή: το απαιτούμενο ποσό είναι τότε η μηνιαία συνδρομή.
`courier_not_connected`	422	Δεν έχετε συνδέσει λογαριασμό με αυτή την courier.
`courier_not_supported`	422	Η courier δεν υποστηρίζει έκδοση voucher μέσω CourierHub.
`courier_validation_failed`	422	Η courier (ή ο έλεγχος πριν από την κλήση της) απέρριψε τα στοιχεία της παραγγελίας. Το `errors` έχει τα προβλήματα ανά πεδίο και το `message` το πρώτο από αυτά. Διορθώστε την παραγγελία και ξαναδοκιμάστε.
`shipment_in_progress`	409	Άλλη κλήση εκδίδει αυτή τη στιγμή voucher για την ίδια παραγγελία και courier. Κεφαλίδα `Retry-After: 5`.
`courier_error`	502	Η courier απέτυχε (σφάλμα ή μη διαθεσιμότητα του API της, ή απάντηση χωρίς voucher). Το `message` είναι η περιγραφή του σφάλματος: άλλοτε το μήνυμα της ίδιας της courier, άλλοτε δική μας περιγραφή (π.χ. `No voucher number returned from ACS API`, όταν η ACS δεν επιστρέφει αριθμό voucher, για παράδειγμα λόγω μη έγκυρου ταχυδρομικού κώδικα). Είναι για ανθρώπους: για τον χειρισμό στηριχτείτε στο `code`. Δεν εκδόθηκε voucher.
`voucher_charge_failed`	500	Το voucher εκδόθηκε στην courier, αλλά απέτυχε η χρέωση ή η ενημέρωση της παραγγελίας. Η απάντηση έχει επιπλέον το πεδίο `voucher_number`. Μια επανάληψη της ίδιας κλήσης επιστρέφει το voucher με `200`, χωρίς νέο voucher. Τη χρέωση την τακτοποιεί η υποστήριξη.

Οι έλεγχοι γίνονται με αυτή τη σειρά: body, παραγγελία, voucher που υπάρχει ήδη (200), όριο αποστολών, υπόλοιπο, σύνδεση courier, ταυτόχρονη κλήση, υποστήριξη courier, κλήση στην courier.

Παράδειγμα σφάλματος επικύρωσης (422).

json

{
    "message": "The given data was invalid.",
    "code": "validation_failed",
    "errors": {
        "order_id": [
            "The order id field is required."
        ],
        "courier_id": [
            "The selected courier id is invalid."
        ],
        "services": [
            "The services field must be an array."
        ],
        "compartment_size": [
            "The selected compartment size is invalid."
        ]
    }
}

Μη επαρκές υπόλοιπο (422).

json

{
    "message": "Insufficient available balance to create a voucher. Required: €0.0700, available: €0.0500.",
    "code": "insufficient_balance"
}

Όριο αποστολών (422).

json

{
    "message": "The shipment limit of the current period has been reached.",
    "code": "shipment_limit_reached"
}

Courier που δεν έχετε συνδέσει (422).

json

{
    "message": "The courier Box Now is not connected to this account.",
    "code": "courier_not_connected"
}

Courier χωρίς υποστήριξη έκδοσης voucher (422).

json

{
    "message": "The courier Example Courier is not supported.",
    "code": "courier_not_supported"
}

Η courier απέρριψε τα στοιχεία (422).

json

{
    "message": "Το τηλέφωνο του παραλήπτη δεν είναι έγκυρο.",
    "code": "courier_validation_failed",
    "errors": {
        "phone": [
            "Το τηλέφωνο του παραλήπτη δεν είναι έγκυρο."
        ]
    }
}

Το message και τα μηνύματα του errors προέρχονται από την courier ή από τον έλεγχο της courier στο CourierHub και μπορεί να είναι στα Ελληνικά.

Ταυτόχρονη κλήση (409 Conflict, κεφαλίδα Retry-After: 5).

json

{
    "message": "A voucher for this order and courier is being created by another request. Try again shortly.",
    "code": "shipment_in_progress"
}

Σφάλμα της courier (502 Bad Gateway).

json

{
    "message": "ACS API error: Invalid postal code",
    "code": "courier_error"
}

Το voucher εκδόθηκε, αλλά απέτυχε η χρέωση (500).

json

{
    "message": "Voucher 7012345680 was created, but the charge or the order update failed.",
    "code": "voucher_charge_failed",
    "voucher_number": "7012345680"
}

Μην εκδώσετε voucher με άλλο τρόπο: ξαναστείλτε την ίδια κλήση για να πάρετε την αποστολή (200).

Παράδειγμα κλήσης

bash

curl -X POST https://courierhub.gr/api/v2/shipments \
  -H "Authorization: Bearer chub_YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "order_id": 3,
    "courier_id": 8,
    "services": ["saturday"]
  }'

Box Now με μέγεθος θυρίδας Medium:

bash

curl -X POST https://courierhub.gr/api/v2/shipments \
  -H "Authorization: Bearer chub_YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"order_id": 3, "courier_id": 12, "compartment_size": 2}'

Δημιουργία αποστολής ​

Μεταβλητές αποστολής ​

Υπηρεσίες (services) ​

Μέγεθος θυρίδας Box Now (compartment_size) ​

Κωδικός χρέωσης ACS (billing_code) ​

Επαναλήψεις και διπλές αποστολές ​

Τι γίνεται μετά την έκδοση ​

Απάντηση αιτήματος ​

Σφάλματα ​

Παράδειγμα κλήσης ​

Δημιουργία αποστολής

Μεταβλητές αποστολής

Υπηρεσίες (`services`)

Μέγεθος θυρίδας Box Now (`compartment_size`)

Κωδικός χρέωσης ACS (`billing_code`)

Επαναλήψεις και διπλές αποστολές

Τι γίνεται μετά την έκδοση

Απάντηση αιτήματος

Σφάλματα

Παράδειγμα κλήσης