5. Shipment methods
5.1.CreateShipmentOrders
Definition
This method is used for creating shipment orders.
Method |
URL example - TEST |
POST |
https://dxwebapit.posta.hr:9020/api/shipment/create_shipment_orders |
Request parameters
Class ShipmentOrdersData
Parameter |
Type |
Description |
REQUIRED |
parcels |
List<ShipmentOrderData> |
A list of shipment orders to create |
YES |
return_address_label |
Bool |
Flag for shipping labels in a response for created shipment orders in PDF format
Possible values:
False – NO
True – YES |
|
Class ShipmentOrderData
Parameter |
Type |
Description |
REQUIRED |
client_reference_number |
String |
Unique client ID of shipment order
Max. length: 100 |
YES |
service |
Integer |
Type of service
Possible values:
24 – Pallet shipment
26 – Package 24 D+1
29 – Package 24 D+2
32 – Package 24 D+3
38 – Package 24 D+4 |
YES |
payed_by |
Integer |
Shipment payer
Possible values:
1 – Sender
2 – Recipient
If NULL Sender is default. |
|
delivery_type |
Integer |
Shipment delivery type
Possible values:
1 – Address
2 – Post office
3 – Parcel locker |
YES |
value |
Decimal |
Insured shipment value
Number of decimal places: 2 |
|
payment_value |
Decimal |
Cash-on-delivery amount
Number of decimal places: 2 |
YES if additional service 9 is chosen (Cash-on-delivery shipment) |
pickup_type |
Integer |
Shipment pickup type
Possible values:
1 – Address
2 – Post office
3 – Parcel locker |
|
parcel_size |
String |
Parcel size
Possible values:
X – Parcel dimension XS
S – Parcel dimension S
M – Parcel dimension M
L – Parcel dimension L
Parcel dimensions:
https://www.posta.hr/dimenzije-pretinaca/9279 |
YES if delivery_type 3
is chosen
(Shipment is delivered to a Parcel locker) |
reference_field_B |
String |
Order reference field B
NOT UNIQUE. Max. length: 100 |
|
reference_field_C |
String |
Order reference field C
NOT UNIQUE. Max. length: 100 |
|
reference_field_D |
String |
Order reference field D
NOT UNIQUE. Max. length: 100 |
|
sender |
SenderData |
Sender's data |
YES |
recipient |
RecipientData |
Recipient's data |
YES |
additional_services |
List<AdditionalServiceData> |
Additional services |
|
packages |
List<PackageData> |
Package list |
YES |
|
|
|
|
|
SenderData
Parameter |
Type |
|
REQUIRED |
sender_name |
String |
Max. length: 50 |
YES |
sender_phone |
String |
Max. length: 25 |
YES |
sender_email |
String |
Max. length: 25 |
|
sender_street |
String |
Max. length: 50 |
YES |
sender_hnum |
String |
Max. length: 10 |
YES |
sender_hnum_suffix |
String |
Max. length: 10 |
YES |
sender_zip |
String |
Max. length: 5 |
YES |
sender_city |
String |
Max. length: 25 |
YES |
sender_pickup_center |
String |
Max. length: 5 |
YES if pickup_type 2 or 3
is chosen |
RecipientData
Parameter |
Type |
Description |
REQUIRED |
recipient_name |
String |
Recipient's name (person or oganization)
Max. length: 50 |
YES |
recipient_phone |
String |
Recipient's phone number
Max. length: 25 |
YES |
recipient_email |
String |
Recipient's email address
Max. length: 25 |
|
recipient_street |
String |
Recipient's name of the street
Max. length: 50 |
YES |
recipient_hnum |
String |
Recipient's number of the house
Max. length: 10 |
YES |
recipient_hnum_suffix |
String |
Recipient's suffix number of the house
Max. length: 10 |
YES |
recipient_zip |
String |
Recipient's area zip code
Max. length: 5 |
YES |
recipient_city |
String |
Recipient's name of the town or village
Max. length: 25 |
YES |
recipient_delivery_center |
String |
Recipient's code of post office or parcel locker for delivery
Max. length: 5 |
YES if delivery_type 2 or 3
is chosen |
Class AdditionalServiceData
Parameter |
Type |
Description |
REQUIRED |
additional_service_id |
Integer |
ID of additional service
Possible values:
1 – Personal delivery
3 – Delivery on Saturdays
4 – With the advice of receipt (AR)
9 – Cash-on-delivery shipment
30 – Send a notification to the recipient
32 – Send an e-mail to the recipient
47 – Consolidated shipment |
|
Class PackageData
Parameter |
Type |
Description |
REQUIRED |
barcode |
String |
Barcode given by Hrvatska pošta d.d. (before creating shipment order)
Max. length: 20 |
YES if barcode_type 0
is chosen |
barcode_type |
Integer |
Barcode type
Possible values:
0 – Barcode given by Hrvatska pošta d.d. (before creating shipment order)
1 – Barcode given from response after creating shipment order |
YES |
barcode_client |
String |
Client's own barcode
Max. length: 500 |
YES if barcode_type 1
is chosen |
weight |
Decimal |
Package weight in kilograms
Number of decimal places: 3 |
YES |
Request example
{
"parcels": [
{
"client_reference_number": "test",
"service": "26",
"payed_by": 1,
"delivery_type": 1,
"value": null,
"payment_value": 20,
"pickup_type": 1,
"parcel_size": "X",
"reference_field_B": "string",
"reference_field_C": "string",
"reference_field_D": "string",
"sender": {
"sender_name": "string",
"sender_phone": "string",
"sender_email": "string",
"sender_street": "string",
"sender_hnum": "string",
"sender_hnum_suffix": "string",
"sender_zip": "string",
"sender_city": "string",
"sender_pick_up_center": "string"
},
"recipient": {
"recipient_name": "string",
"recipient_phone": "string",
"recipient_email": "string",
"recipient_street": "string",
"recipient_hnum": "string",
"recipient_hnum_suffix": "",
"recipient_zip": "string",
"recipient_city": "string",
"recipient_delivery_center": "string"
},
"additional_services": [
{
"additional_service_id": 9
}
],
"packages": [
{
"barcode": "",
"barcode_type": 1,
"barcode_client": "string",
"weight": 3
},
{
"barcode": "",
"barcode_type": 1,
"barcode_client": "string",
"weight": 3
}
]
},
{
"client_reference_number": "test1",
"service": "26",
"payed_by": 1,
"delivery_type": 1,
"value": null,
"payment_value": 0,
"pickup_type": 1,
"parcel_size": "S",
"reference_field_B": "string",
"reference_field_C": "string",
"reference_field_D": "string",
"sender": {
"sender_name": "string",
"sender_phone": "string",
"sender_email": "string",
"sender_street": "string",
"sender_hnum": "string",
"sender_hnum_suffix": "string",
"sender_zip": "string",
"sender_city": "string",
"sender_pick_up_center": "string"
},
"recipient": {
"recipient_name": "string",
"recipient_phone": "string",
"recipient_email": "string",
"recipient_street": "string",
"recipient_hnum": "string",
"recipient_hnum_suffix": "string",
"recipient_zip": "string",
"recipient_city": "string",
"recipient_delivery_center": "string"
},
"additional_services": [
{
"additional_service_id": 30
}
],
"packages": [
{
"barcode": "",
"barcode_type": 1,
"barcode_client": "string",
"weight": 3
},
{
"barcode": "",
"barcode_type": 1,
"barcode_client": "string",
"weight": 3
}
]
}
],
"return_address_label": true
}
Response example
{
"ShipmentOrdersList": [
{
"ClientReferenceNumber": "test",
"ResponseStatus": 0,
"Packages": [
{
"barcode": "LE900002111HR",
"barcode_type": 1,
"barcode_client": "test12",
"weight": 3.0
},
{
"barcode": "LE900002125HR",
"barcode_type": 1,
"barcode_client": "test22",
"weight": 3.0
}
],
"ErrorCode": null,
"ErrorMessage": null,
"MessageID": ""
},
{
"ClientReferenceNumber": "test1",
"ResponseStatus": 0,
"Packages": [
{
"barcode": "LE900002139HR",
"barcode_type": 1,
"barcode_client": "test12",
"weight": 3.0
},
{
"barcode": "LE900002142HR",
"barcode_type": 1,
"barcode_client": "test22",
"weight": 3.0
}
],
"ErrorCode": null,
"ErrorMessage": null,
"MessageID": ""
}
],
"ShipmentsLabel": "base64string"
}
Response parameters
Class CreateShipmentOrdersMainResponse
Parameter |
Type |
Description |
ShipmentOrdersList |
List<CreateShipmentOrdersResponse> |
List of created or rejected shipment orders depending of potentional errors |
ShipmentsLabel |
String |
Shipping labels for created shipment orders in PDF format |
Class CreateShipmentOrdersResponse
Parameter |
Type |
Description |
ClientReferenceNumber |
String |
Unique client ID of shipment order |
ResponseStatus |
EnumResponseStatus |
0 – OK
1 – ERROR |
Packages |
List<PackageData> |
List of created packages |
ErrorCode |
Integer |
Error code |
ErrorMessage |
String |
Error message |
MessageID |
String |
Error ID |
5.2. CancelShipmentOrders
Definition
This method is used to cancel shipping orders.
Method |
URL example - TEST |
POST |
https://dxwebapit.posta.hr:9020/api/shipment/cancel_shipment_orders |
Request parameters
Class CancelOrdersData
Parameter |
Type |
Description |
REQUIRED |
parcels |
List<CancelOrderData> |
List of shipment orders to cancel |
YES |
Class CancelOrderData
Parameter |
Type |
Description |
REQUIRED |
client_reference_number |
String |
Unique client ID of shipment order
Max. length: 100 |
YES |
Request example
{
"parcels": [
{
"client_reference_number": "test"
},
{
"client_reference_number": "test1"
}
]
}
Response example
[
{
"ClientReferenceNumber": "test",
"ResponseStatus": 0,
"ErrorCode": null,
"ErrorMessage": null
},
{
"ClientReferenceNumber": "test1",
"ResponseStatus": 0,
"ErrorCode": null,
"ErrorMessage": null
}
]
Response parameters
Class CancelShipmentOrdersResponse
Parameter |
Type |
Description |
ClientReferenceNumber |
String |
Unique client ID of shipment order |
ResponseStatus |
EnumResponseStatus |
0 – OK
1 – ERROR |
ErrorCode |
Integer |
Error code |
ErrorMessage |
String |
Error message |
5.3. GetShipmentStatus
Definition
This method is used to retrieve shipping orders status.
Method |
URL example - TEST |
GET |
https://dxwebapit.posta.hr:9020/api/shipment/get_shipment_status |
Request parameters
Class BarcodesData
Parameter |
Type |
Description |
REQUIRED |
barcodes |
List<BarcodeData> |
List of barcodes to retrieve status |
YES |
Class BarcodeData
Parameter |
Type |
Description |
REQUIRED |
barcode |
String |
Package barcode to retrieve status
Max. length: 20 |
YES |
Request example
{ "barcodes": [
{
"barcode": "LE347087966HR"
},
{
"barcode": "LE347087952HR"
}
]
}
Response example
[
{
"Barcode": "LE347087966HR",
"PackageScansList": [
{
"Scan": "NOV",
"ScanDescription": "Definirani podaci o pošiljci",
"ScanTime": "2022-11-16T11:15:33.257",
"Center": "ROOT",
"Comment": null,
"CommentNPA": "5000002"
}
],
"ResponseStatus": 0,
"ErrorCode": null,
"ErrorMessage": null
},
{
"Barcode": "LE347087952HR",
"PackageScansList": [
{
"Scan": "NOV",
"ScanDescription": "Definirani podaci o pošiljci",
"ScanTime": "2022-11-16T11:30:22.763",
"Center": "ROOT",
"Comment": null,
"CommentNPA": "5000002"
}
],
"ResponseStatus": 0,
"ErrorCode": null,
"ErrorMessage": null
}
]
Response parameters
Class GetShipmentStatusResponse
Parameter |
Type |
Description |
Barcode |
String |
Package barcode |
PackageScansList |
List<PackageScanData> |
List of package scans |
ResponseStatus |
EnumResponseStatus |
0 – OK
1 – ERROR |
ErrorCode |
Integer |
Error code |
ErrorMessage |
String |
Error message |
Class PackageScanData
Parameter |
Type |
Description |
Scan |
String |
Scan code
List of scans: Appendix A |
ScanDescription |
String |
Scan description |
ScanTime |
DateTime |
Scan date and time |
Center |
String |
Center in which the scan was made |
Comment |
String |
Comment on scan |
CommentNPA |
String |
Comment on scan NPA
List of comments: Appendix B |
1.4.GetShippingLabels
Definition
This method is used for retrieval of package address labels.
It is possible to retrieve the address label by parcel barcodes and/or by client order number.
Method |
URL example - TEST |
GET |
https://dxwebapit.posta.hr:9020/api/shipment/get_shipping_labels |
Request parameters
Class LabelsData
Parameter |
Type |
Description |
REQUIRED |
client_reference_number |
String |
Unique client ID of shipment order
Max. length: 100 |
YES if barcodes is NULL or EMPTY |
barcodes |
List<BarcodeData> |
List of barcodes to retrieve labels |
YES if CRN
is NULL or EMPTY |
A4 |
Bool |
Flag for A4 paper size (4 labels on 1 page)
Possible values:
0 – NO
1 – YES
If NULL 0 is default. |
|
Class BarcodeData
Parameter |
Type |
Description |
REQUIRED |
barcode |
String |
Package barcode
Max. length: 20 |
|
Request example
{
"client_reference_number": "test",
"barcodes": [
{
"barcode": "LE900001297HR"
},
{
"barcode": "LE900001310HR"
}
],
"A4":false
}
Response example
{
"PackageLabel": "base64string",
"ResponseStatus": 0,
"ErrorCode": null,
"ErrorMessage": null
}
Response parameters
Class GetShippingLabelsResponse
Parameter |
Type |
Description |
PackageLabel |
String |
Package labels of created shipment orders in „base64“ string format |
ResponseStatus |
EnumResponseStatus |
0 – OK
1 – ERROR |
ErrorCode |
Integer |
Error code |
ErrorMessage |
String |
Error message |
|