HP Shipping Service API - 5. Shipment methods

Previous Next
(docx) HP Shipping Service API - Technical documentation (pdf)
 

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