CPL API
Useful links
  • Developer
  • Sandbox
Useful links
  • Developer
  • Sandbox
Přepni do češtiny
  1. ShipmentBatch
  • Back to home
  • API Methods
  • AccessPoint
    • List of access points
  • AddressWhisper
    • Address Whisperer
  • Codelist
    • Codelist for the beneficiary's age verification service
    • Codelist product
    • Codelist externalNumbers
    • Codelist country + COD authorization
    • Codelist currency
    • Method for obtaining the services provided for shipments.
    • A method for obtaining minimum and maximum values ​​for services
    • Codelist shipment phase
    • Codelist status
    • Codelist of validation messages
    • Types of personal documents
  • Customer
    • Customer information - permitted currencies
    • Customer addresess
  • Info
    • /info
  • Order
    • Order tracking
  • OrderBatch
    • Create an order
    • Get order status
  • OrderEvent
    • Order cancel
  • Shipment
    • Shipment tracking
  • ShipmentBatch
    • Shipment creation
      POST
    • Used to modify the output format of the label.
      PUT
    • Getting import state
      GET
    • Pick up label
      GET
  • ShipmentEvent
    • Shipment cancel
    • Adding informations to shipment
  • VersionInformation
    • News
  1. ShipmentBatch

Shipment creation

POST
/shipment/batch
Maintainer:Not configured

Purpose and usage#

The shipment/batch method is used to create a request for retrieving a shipment or a group of shipments. When the method is called, the return value is batchId, which is then used to obtain the processing status of the shipment and subsequently to retrieve the label.
To successfully call the method, it is necessary to use the batchId, which is obtained from the Location header in the response to the POST shipment/batch request.

Request

Header Params
Accept-Language
string 
optional
Language specification, default language: cs-CZ
X-Correlation-ID
string 
optional
Correlation Id of request
X-LogLevel
enum<string> 
optional
The forced log level
Allowed values:
TraceDebugInformationWarningErrorCritical
Body Params application/json
returnChannel
optional
Section of return values for label printing. If you fill in returnChannel with the type email, a label for each requested shipment will be sent to the specified email. This does not work in the testing environment. This feature is mainly used for return shipments, where the requester receives the generated label directly via email. However, the email is empty, containing no text, only the PDF label as an attachment.
One of
type
optional
Label return path type. FTP is not
supported!
address
string  | null 
optional
Address:
Email format: xxxxxxx@yyyy.zzz
FTP format:
ftp://user:password@host:port/path
Délka: 100
<= 100 characters
labelSettings
optional
labbelSettings is used for label parameters settings.
One of
format
enum<string> 
Eps.Api.MyApi2.Web.Constants.ConstLabelFormat
optional
Label format
Allowed values:
ZplPdfJpegPngSvg
dpi
integer <int32> | null 
optional
chose DPI for ZPL
>= 203<= 1200
completeLabelSettings
optional
ZPL base64 encoding, mergin more
labels into one response
shipments
array [object {21}] 
required
Shipments
>= 1 items
referenceId
string 
required
referenceId
>= 1 characters<= 128 characters
shipmentNumber
string  | null 
optional
shipment Number. Use only if you have number serie assigned by PPL
productType
string 
required
productType
>= 1 characters
note
string  | null 
optional
Note length: 300
depot
string  | null 
optional
not used. length: 2
ageCheck
string  | null 
optional
Age check service (15,18+),
integratorId
integer <int32> | null 
optional
Integrator ID - only for type: integrator
>= 1
shipmentSet
optional
Shipment set
backAddress
optional
Address for the return of undelivered
shipments
sender
optional
Sender
senderMask
optional
Shipper - Alternate address (in case of a
different shipper on the label than the
one on record.
recipient
object 
required
Recipient
specificDelivery
optional
cashOnDelivery
optional
Payment information for cash on delivery products. Cash on delivery is tied to the product. In order for the request with cash on delivery to be accepted, it is necessary to enter the correct product type in the shipment (PRID, BUSD, SMAD, COND, DOPD, SMED).
insurance
optional
Parcel insurance. Adds insurance for a parcel or parcels in the shipment. Use this if you have a single parcel in the shipment or multiple parcels in a set with the same value. For parcels in a set with different values that you want to insure, specify the insurance in shipmentSetItems.
externalNumbers
array [object {2}]  | null 
optional
ExternalNumbers are external numbers used for customer identification, such as an order number or a specific product code. The most commonly used code is CUST, which serves as a customer-specific identifier. This number is also printed directly on the label and is recorded in the customer's invoicing system. For more details, refer to codelist/externalNumbers.
services
array [object {1}]  | null 
optional
Services
dormant
optional
shipmentRouting
optional
directInjection
optional
Used in case of Direct Injection packages to foreign depot. At first must be approved on PPL side and discussed with sales representative.
labelService
optional
shipmentsOrderBy
string  | null 
optional
Sort labels - ReferenceId, Shipment
Example
{
    "returnChannel": {
        "type": "<string>",
        "address": "<string>"
    },
    "labelSettings": {
        "format": "<string>",
        "dpi": "<integer>",
        "completeLabelSettings": {
            "isCompleteLabelRequested": "<boolean>",
            "pageSize": "<string>",
            "position": "<integer>"
        }
    },
    "shipments": [
        {
            "productType": "<string>",
            "recipient": {
                "country": "<string>",
                "zipCode": "<string>",
                "name": "<string>",
                "name2": "<string>",
                "street": "<string>",
                "city": "<string>",
                "contact": "<string>",
                "phone": "<string>",
                "email": "<string>"
            },
            "referenceId": "<string>",
            "shipmentNumber": "<string>",
            "note": "<string>",
            "depot": "<string>",
            "ageCheck": "<string>",
            "integratorId": "<integer>",
            "shipmentSet": {
                "numberOfShipments": "<integer>",
                "shipmentSetItems": [
                    {
                        "shipmentNumber": "<string>",
                        "weighedShipmentInfo": {
                            "weight": "<double>"
                        },
                        "externalNumbers": [
                            {
                                "code": "<string>",
                                "externalNumber": "<string>"
                            },
                            {
                                "code": "<string>",
                                "externalNumber": "<string>"
                            }
                        ],
                        "insurance": {
                            "insuranceCurrency": "<string>",
                            "insurancePrice": "<double>"
                        }
                    },
                    {
                        "shipmentNumber": "<string>",
                        "weighedShipmentInfo": {
                            "weight": "<double>"
                        },
                        "externalNumbers": [
                            {
                                "code": "<string>",
                                "externalNumber": "<string>"
                            },
                            {
                                "code": "<string>",
                                "externalNumber": "<string>"
                            }
                        ],
                        "insurance": {
                            "insuranceCurrency": "<string>",
                            "insurancePrice": "<double>"
                        }
                    }
                ]
            },
            "backAddress": {
                "country": "<string>",
                "zipCode": "<string>",
                "name": "<string>",
                "name2": "<string>",
                "street": "<string>",
                "city": "<string>",
                "contact": "<string>",
                "phone": "<string>",
                "email": "<string>"
            },
            "sender": {
                "country": "<string>",
                "zipCode": "<string>",
                "name": "<string>",
                "name2": "<string>",
                "street": "<string>",
                "city": "<string>",
                "contact": "<string>",
                "phone": "<string>",
                "email": "<string>"
            },
            "senderMask": {
                "country": "<string>",
                "zipCode": "<string>",
                "name": "<string>",
                "name2": "<string>",
                "street": "<string>",
                "city": "<string>",
                "contact": "<string>",
                "phone": "<string>",
                "email": "<string>"
            },
            "specificDelivery": {
                "specificDeliveryDate": "<dateTime>",
                "specificDeliveryTimeFrom": "<dateTime>",
                "specificDeliveryTimeTo": "<dateTime>",
                "specificTakeDate": "<dateTime>",
                "parcelShopCode": "<string>"
            },
            "cashOnDelivery": {
                "codCurrency": "<string>",
                "codPrice": "<double>",
                "codVarSym": "088919",
                "iban": "<string>",
                "swift": "<string>",
                "specSymbol": "<string>",
                "account": "<string>",
                "accountPre": "<string>",
                "bankCode": "<string>"
            },
            "insurance": {
                "insuranceCurrency": "<string>",
                "insurancePrice": "<double>"
            },
            "externalNumbers": [
                {
                    "code": "<string>",
                    "externalNumber": "<string>"
                },
                {
                    "code": "<string>",
                    "externalNumber": "<string>"
                }
            ],
            "services": [
                {
                    "code": "<string>"
                },
                {
                    "code": "<string>"
                }
            ],
            "dormant": {
                "shipmentNumber": "<string>",
                "note": "<string>",
                "recipient": {
                    "country": "<string>",
                    "zipCode": "<string>",
                    "name": "<string>",
                    "name2": "<string>",
                    "street": "<string>",
                    "city": "<string>",
                    "contact": "<string>",
                    "phone": "<string>",
                    "email": "<string>"
                },
                "externalNumbers": [
                    {
                        "code": "<string>",
                        "externalNumber": "<string>"
                    },
                    {
                        "code": "<string>",
                        "externalNumber": "<string>"
                    }
                ],
                "services": [
                    {
                        "code": "<string>"
                    },
                    {
                        "code": "<string>"
                    }
                ],
                "weighedShipmentInfo": {
                    "weight": "<double>"
                }
            },
            "shipmentRouting": {
                "inputRouteCode": "28696"
            },
            "directInjection": {
                "directAddressing": "<boolean>",
                "gatewayZipCode": "<string>",
                "gatewayCity": "<string>",
                "country": "<string>"
            },
            "labelService": {
                "labelless": "<boolean>"
            }
        }
    ],
    "shipmentsOrderBy": "<string>"
}

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST '/shipment/batch' \
--header 'Accept-Language;' \
--header 'X-Correlation-ID;' \
--header 'X-LogLevel;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "returnChannel": {
        "type": "<string>",
        "address": "<string>"
    },
    "labelSettings": {
        "format": "<string>",
        "dpi": "<integer>",
        "completeLabelSettings": {
            "isCompleteLabelRequested": "<boolean>",
            "pageSize": "<string>",
            "position": "<integer>"
        }
    },
    "shipments": [
        {
            "productType": "<string>",
            "recipient": {
                "country": "<string>",
                "zipCode": "<string>",
                "name": "<string>",
                "name2": "<string>",
                "street": "<string>",
                "city": "<string>",
                "contact": "<string>",
                "phone": "<string>",
                "email": "<string>"
            },
            "referenceId": "<string>",
            "shipmentNumber": "<string>",
            "note": "<string>",
            "depot": "<string>",
            "ageCheck": "<string>",
            "integratorId": "<integer>",
            "shipmentSet": {
                "numberOfShipments": "<integer>",
                "shipmentSetItems": [
                    {
                        "shipmentNumber": "<string>",
                        "weighedShipmentInfo": {
                            "weight": "<double>"
                        },
                        "externalNumbers": [
                            {
                                "code": "<string>",
                                "externalNumber": "<string>"
                            },
                            {
                                "code": "<string>",
                                "externalNumber": "<string>"
                            }
                        ],
                        "insurance": {
                            "insuranceCurrency": "<string>",
                            "insurancePrice": "<double>"
                        }
                    },
                    {
                        "shipmentNumber": "<string>",
                        "weighedShipmentInfo": {
                            "weight": "<double>"
                        },
                        "externalNumbers": [
                            {
                                "code": "<string>",
                                "externalNumber": "<string>"
                            },
                            {
                                "code": "<string>",
                                "externalNumber": "<string>"
                            }
                        ],
                        "insurance": {
                            "insuranceCurrency": "<string>",
                            "insurancePrice": "<double>"
                        }
                    }
                ]
            },
            "backAddress": {
                "country": "<string>",
                "zipCode": "<string>",
                "name": "<string>",
                "name2": "<string>",
                "street": "<string>",
                "city": "<string>",
                "contact": "<string>",
                "phone": "<string>",
                "email": "<string>"
            },
            "sender": {
                "country": "<string>",
                "zipCode": "<string>",
                "name": "<string>",
                "name2": "<string>",
                "street": "<string>",
                "city": "<string>",
                "contact": "<string>",
                "phone": "<string>",
                "email": "<string>"
            },
            "senderMask": {
                "country": "<string>",
                "zipCode": "<string>",
                "name": "<string>",
                "name2": "<string>",
                "street": "<string>",
                "city": "<string>",
                "contact": "<string>",
                "phone": "<string>",
                "email": "<string>"
            },
            "specificDelivery": {
                "specificDeliveryDate": "<dateTime>",
                "specificDeliveryTimeFrom": "<dateTime>",
                "specificDeliveryTimeTo": "<dateTime>",
                "specificTakeDate": "<dateTime>",
                "parcelShopCode": "<string>"
            },
            "cashOnDelivery": {
                "codCurrency": "<string>",
                "codPrice": "<double>",
                "codVarSym": "088919",
                "iban": "<string>",
                "swift": "<string>",
                "specSymbol": "<string>",
                "account": "<string>",
                "accountPre": "<string>",
                "bankCode": "<string>"
            },
            "insurance": {
                "insuranceCurrency": "<string>",
                "insurancePrice": "<double>"
            },
            "externalNumbers": [
                {
                    "code": "<string>",
                    "externalNumber": "<string>"
                },
                {
                    "code": "<string>",
                    "externalNumber": "<string>"
                }
            ],
            "services": [
                {
                    "code": "<string>"
                },
                {
                    "code": "<string>"
                }
            ],
            "dormant": {
                "shipmentNumber": "<string>",
                "note": "<string>",
                "recipient": {
                    "country": "<string>",
                    "zipCode": "<string>",
                    "name": "<string>",
                    "name2": "<string>",
                    "street": "<string>",
                    "city": "<string>",
                    "contact": "<string>",
                    "phone": "<string>",
                    "email": "<string>"
                },
                "externalNumbers": [
                    {
                        "code": "<string>",
                        "externalNumber": "<string>"
                    },
                    {
                        "code": "<string>",
                        "externalNumber": "<string>"
                    }
                ],
                "services": [
                    {
                        "code": "<string>"
                    },
                    {
                        "code": "<string>"
                    }
                ],
                "weighedShipmentInfo": {
                    "weight": "<double>"
                }
            },
            "shipmentRouting": {
                "inputRouteCode": "28696"
            },
            "directInjection": {
                "directAddressing": "<boolean>",
                "gatewayZipCode": "<string>",
                "gatewayCity": "<string>",
                "country": "<string>"
            },
            "labelService": {
                "labelless": "<boolean>"
            }
        }
    ],
    "shipmentsOrderBy": "<string>"
}'

Responses

🟢201Created
application/json
Created
Headers
X-Correlation-ID
string 
optional
Correlation Id of request otherwise id of response
Location
string 
optional
Newly created entity location
Body
object {0}
Example
{}
🟠400Bad Request
🔴500Server Error
🔴503Service Unavailable
Modified at 2025-05-21 11:59:08
Previous
ShipmentBatch
Next
Used to modify the output format of the label.
Built with