Packetery API reference

Data structures reference

ClaimAttributes

Type Field name Constraints Required Description
unsignedLong id 10 digits no If you have assigned offline barcode range, fill the unique packetID here. Otherwise ignore this attribute. NOTE: Make sure to use 64-bit type.
string number 1-36 alphanumeric yes An unique ID of the order (from your e-shop).
string email valid e-mail if no phone Recipient's e-mail.
string phone valid phone number, examples are in phone number formats if no e-mail Recipient's phone.
decimal value see max values in TOS yes Packet's value (for insurance purposes).
string currency CZK, EUR, HUF, PLN, RON no Packet value currency.
string eshop when using more senders Sender label. If the entered sender does not exist yet, a new one is created.
bool sendLabelToEmail no If set to true, PDF label will be sent to the recipient via email.

ClaimWithPasswordAttributes

Type Field name Constraints Required Description
unsignedLong id 10 digits no If you have assigned offline barcode range, fill the unique packetID here. Otherwise ignore this attribute. NOTE: Make sure to use 64-bit type.
string number 1-36 alphanumeric yes An unique ID of the order (from your e-shop).
string email valid e-mail yes Recipient's e-mail.
string phone valid phone number, examples are in phone number formats yes Recipient's phone.
decimal value see max values in TOS yes Packet's value (for insurance purposes).
string currency CZK, EUR, HUF, PLN, RON no Packet value currency.
string eshop yes Sender label. If the entered sender does not exist yet, a new one is created.
string consignCountry 2 alphanumerical yes Country where packet will be consigned and in which language notification will be sent
bool sendEmailToCustomer no If set to true, email with password and instructions will be sent to customer

CurrentStatusRecord

An extension of StatusRecord, so it contains the same and some additional fields.

Type Field name Required Description
... ... ... ...
boolean isReturning yes Indicates whether the packet is on its way back to the sender.
date storedUntil yes The last possible day to pick up the packet. After this date, it will start returning to the sender.
unsignedInt carrierId no Numeric identifier of the chosen carrier method.
string carrierName no Name of the chosen carrier method, in english.

AttributeCollection

It represents additional information about packet or packet item. Is an array of type Attribute.

PacketCollection

Is an array of type PacketIdDetail.

ShipmentPacketsResult

Type Field name Constraints Required Description
PacketCollection packets type PacketCollection yes Packet collection

Security

Type Field name Required Description
boolean allowPublicTracking no Allow each user to view the tracking of the packet.
AllowTrackingForUsers allowTrackingForUsers no Allow specified users to view the tracking of the packet.

AllowTrackingForUsers

Type Field name Constraints Required Description
ApiKeys apiKeys type ApiKeys yes Packet collection

ApiKeys

An array of objects apiKey which contain a string value user's API key (16 characters).

Services

This attribute has not yet been implemented. This is reserved record for future use.

Type Field name Required Description
FirstMileCarrierService firstMileCarrier no Specify external carrier that will deliver the packet into our network. Tracking starts before accepting packet into our network
LastMileCarrierService lastMileCarrier no Specify external carrier that will deliver the packet to the client. Allows sender to pass carrier data such as barcode or tracking code.
ReturnDestinationService returnDestination no Service to override default return address for a single packet.

FirstMileCarrierService

This attribute has not yet been implemented. This is reserved record for future use.

A service that specifies that an external carrier will forward a packet to us for delivery. This allows us to track the packet before we physically receive it.

Type Field name Required Description
unsignedInt addressId yes ID of external carrier
string barcode no Packet barcode. If not supplied, we will consign the packet on your behalf. You can then obtain the carriers label. If supplied, trackingCode has to be supplied as well.
string trackingCode no Packet tracking code. If supplied, barcode has to be supplied as well.
string foreignId no The foreign ID. The identifier used for communication with carrier trough their API. Usually same as trackingCode which is also the default value for this attribute

LastMileCarrierService

This attribute has not yet been implemented. This is a reserved record for future use.

Allows to configure the carrier delivering the packet. The carrier is supplied trough root addressId attribute. The current usage is to support the clients who use assigned offline barcodes obtained from the carrier.

Type Field name Required Description
string barcode no Packet barcode.
string trackingCode no Packet tracking code.
string foreignId no The foreign ID. The identifier used for communication with carrier trough their API. Usually same as trackingCode which is also the default value for this attribute

ReturnDestinationService

This attribute has not yet been implemented. This is reserved record for future use.

Service to override default return address for a single packet.

Type Field name Required Description
unsignedInt addressId yes Id of branch or external carrier
string carrierPickupPoint no Id of carrier's pickup point or box
ReturnDestinationServiceAddress returnAddress no Address, required in the case of using an carrier HD or box

ReturnDestinationServiceAddress

This attribute has not yet been implemented. This is reserved record for future use.

Service to override default return address for a single packet. Note: Country is retrieved from addressId of the parent element (branch/carrier)

Type Field name Required Description
string name Yes
string surname Yes
string street Yes
string houseNumber Yes
string city Yes
string zip Yes
string email No* The requirement of this parameter differ per carrier
string phone No* The requirement of this parameter differ per carrier

ItemCollection

It represents things in the packet. Is an array of type Item.

Item

It represent one kind of thing in the packet. Is an array of type Attribute.

Attribute

It's represents additional information about packet or packet item (thing in packet). See to list of attributes.

Type Field name Required Description
string key yes Name of property.
string value yes Value of property.

Additional information about content of packet (for example for customs proceedings).

CustomsDeclaration

It is deprecated. Use attributes and items.

Type Constraints Field name Required Description
decimal deliveryCostEur yes A cost charged to the customer for shipping in EUR.
decimal deliveryCost yes A cost charged to the customer for shipping in the currency of the destination country.
CustomsDeclarationItems type CustomsDeclarationItems items yes An array describing customs declaration forms. One packet can consist of multiple goods, every one of each must have its own customs declaration form.

CustomsDeclarationItem

It is deprecated. Use attributes and items.

Type Field name Required Description
string customsCode yes Harmonized System code (see http://www.tariffnumber.com/).
decimal valueEur yes Value of the product in EUR.
decimal value yes Value of the product in the currency of the destination country.
string productEan yes Product EAN code.
string productNameEn yes Product name in English.
string productName yes Product name in the language of the destination country.
unsignedInt unitsCount yes Count of units. If you have multiple units of the same product, specify just one CustomsDeclarationItem for the product and set this value to count of units e.g. if you want to send 1000 screws then your product is a screw and the units count is 1000.
string countryOfOrigin yes Country of origin (COO) - country where the product was made.
string currency no Currency of product value. Required by the Swiss Post.
string invoiceNumber no Current product's invoice number. Required by the Swiss Post.
date invoiceIssueDate no Current product's invoice issue date in format Y-m-d, example: 2018-09-25. Required by the Swiss Post.
unsignedInt weight no Weight of the product(s) in grams. Required by the Swiss Post.
boolean isFoodBook no Does the current product classify as food or book? Required by the Swiss Post.
boolean isVoc no Does the current product classify as Volatile Organic Compound? Required by the Swiss Post.

CustomsDeclarationItems

It is deprecated. Use attributes and items.

Is an array of type CustomsDeclarationItem.

PacketAttributes

Type Field name Constraints Required Description
unsignedLong id 10 digits no If you have assigned offline barcode range, fill the unique packetID here. Otherwise ignore this attribute. NOTE: Make sure to use 64-bit type.
string affiliateId 16 alphanumeric no ID of the third-party sender or member of Packeta affiliate program.
string number 1-36 alphanumeric yes A unique ID of the order (from your e-shop).
string name 1-32 alphanumeric yes Recipient's name.
string surname 1-32 alphanumeric yes Recipient's surname.
string company 1-32 alphanumeric no Recipient's company.
string email valid e-mail if no phone Recipient's e-mail.
string phone valid phone number, examples are in phone number formats if no e-mail Recipient's phone.
unsignedInt addressId valid active branch ID yes Branch ID or an ID of the external carrier.
string currency CZK, EUR, HUF, PLN, RON no Currency of COD and packet value.
decimal cod integer for CZK, a multiple of 5 for HUF no COD amount.
decimal value see max. values in TOS yes Packet's value (for insurance purposes).
decimal weight yes Weight in kg
date deliverOn date within next 14 days no Date for scheduled delivery in future. Package can be delivered on this date or later. The format is YYYY-MM-DD.
string eshop when using more senders Sender label. If the entered sender does not exist yet, a new one is created.
boolean adultContent 0-1 no If set to 1, the packet will be handed over only to person older than 18 years. An identification will be required. Functionality is accessible just for Packeta internal pickup points in CZ/SK/HU/RO, it is not accessible for couriers and external pickup points.
string note 1-128 alphanumeric no Sender's note. It will be displayed on the label, if supported by courier. It will be shortened up to 32 characters, if limited by courier.
string street 1-32 alphanumeric on address delivery Street.
string houseNumber 1-16 alphanumeric on address delivery House number.
string city 1-32 alphanumeric on address delivery City.
string province 1-32 alphanumeric no Province.
string zip valid ZIP on address delivery ZIP code.
string carrierService alphanumeric, comma separated no Carrier services separated by comma. More information here.
string customerBarcode 1-32 alphanumeric no A custom barcode. Only applicable if you have an agreement about using custom barcodes.
string carrierPickupPoint 1-32 alphanumeric yes for some carriers Code of a carrier's pick up point. Required only if the chosen carrier offers them.
CustomsDeclaration customsDeclaration type CustomsDeclaration - deprecated (use attributes and items) on address delivery outside EU A collection of forms required for goods shipped outside of the European Union.
Size size type Size yes for some carriers Some carriers require the dimensions of the packet.
AttributeCollection attributes type AttributeCollection yes for some carriers Additional information which are specific for some carriers or other cases.
ItemCollection items type ItemCollection yes for some carriers Additional information about content of packet (for example for customs proceedings).
Security security type Security no Defines additional security options.
Services services type Services no Optional services. This attribute has not yet been implemented. This is reserved record for future use.

You can find more information about PacketAttributes associated with Direct label printing for carriers in it's own chapter.

Carrier service

Each carrier may offer additional optional services. This field is used to choose any of those services for individual packets. The services may be charged.

Individual services are typed in camel case, separated by comma, without whitespace.

Example: service1,service2,service3

Service Carriers Description
signature frcolissimohome, frcolisprivehome If present, the recipient is required to sign upon delivery.
additionalInsurance frcolissimohome, frcolisprivehome If present, additional insurance will be applied according to pricelist.
open bgspeedyhome Additional service Open. Recipient is allowed to open the package before payment.
test bgspeedyhome Additional service Test. Recipient is allowed to test the contents of the package before payment.

PacketIdDetail

Type Field name Constraints Required Description
unsignedLong id 10 digits yes If you have assigned offline barcode range, it will correspond to the id in the request. Otherwise it returns you random unique number from our system.
string barcode yes The id prefixed by letter 'Z'. This format is used for generating a readable barcode.
string barcodeText yes The barcode in following format Z 123 4567 890. Used for printing, for better readability.

PacketDetail

Type Field name Constraints Required Description
unsignedLong id 10 digits yes If you have assigned offline barcode range, it will correspond to the id in the request. Otherwise it returns you random unique number from our system.
string barcode yes The id prefixed by letter 'Z'. This format is used for generating a readable barcode.
string barcodeText yes The barcode in following format Z 123 4567 890. Used for printing, for better readability.
string password yes Password for submitting packet

PacketIds

An array of packet IDs, a packet ID is 64-bit unsignedLong.

PacketIdWithCourierNumber

Type Field name Constraints Required Description
unsignedLong packetId 10 digits yes A packet ID, e.g. an id returned by createPacket().
string courierNumber yes A courier number returned by packetCourierNumber().

PacketIdsWithCourierNumbers

An array of PacketIdWithCourierNumber structures, which contain packet IDs together with courier numbers.

Size

Dimensions of the packet in millimetres (mm). Is not required, except for certain carriers.

Type Field name Required Description
unsignedInt length yes Length of the packet.
unsignedInt width yes Width of the packet.
unsignedInt height yes Height of the packet.

PacketInfoResult

Object with a packet's additional information.

Type Field name Constraints Required Description
unsignedInt branchId yes Destination branch ID
unsignedInt invoicedWeightGrams no Verified weight of the packet which is used in the invoice (if available).
CourierInfo courierInfo type CourierInfo no Info about courier consignment, if the packet is heading to a courier and has been consigned.
Services services type Services no Optional services.

CourierInfo

An array of objects CourierInfoItem

CourierInfoItem

An object with additional information regarding packet's consignment to an external courier.

Type Field name Constraints Required Description
unsignedInt courierId yes Courier ID.
string courierName yes Name of the courier.
CourierNumbers courierNumbers type CourierNumbers no Array of courier numbers, if available.
CourierBarcodes courierBarcodes type CourierBarcodes no Array of courier barcodes, if available.
CourierTrackingNumbers courierTrackingNumbers type CourierTrackingNumbers no Array of courier tracking numbers, if available.
CourierTrackingUrls courierTrackingUrls type CourierTrackingUrls no Array of courier tracking urls, if available.

CourierNumbers

An array of objects courierNumber which contain a string identifier of the external courier's number of the packet.

CourierBarcodes

An array of objects courierBarcode which contain a string barcode from the courier's label.

CourierTrackingNumbers

An array of objects courierTrackingNumber which contain a string number that is used on courier's online tracking application.

CourierTrackingUrls

An array of courierTrackingUrl.

CourierTrackingUrl

A list of tracking URLs of external courier's tracking application.

Type Field name Constraints Required Description
string lang 2 letters yes Language of the tracking web page.
string url yes Tracking URL.

Packet status codes

statusCode codeText Extra valid fields Description
1 received data We have received the packet data. Freshly created packet.
2 arrived branchId Packet has been accepted at our branch.
3 prepared for departure branchId, destinationBranchId Packet is waiting to be dispatched from branch branchId to branch destinationBranchId.
4 departed branchId, destinationBranchId Packet is on the way from branch branchId to branch destinationBranchId.
5 ready for pickup branchId Packet has been delivered to its destination (branchId), the customer has been informed via SMS.
6 handed to carrier externalTrackingCode Packet has been handed over to an external carrier for delivery. It can be traced via carrier's tracking application under externalTrackingCode.
7 delivered branchId Packet was picked up by the customer at the branch branchId.
9 posted back Packet is on the way back to the sender.
10 returned Packet has been returned to the sender.
11 cancelled Packet has been cancelled.
12 collected branchId Packet has been collected and is on its way to the depot branchId.
14 customs Customs declaration process.
15 reverse packet arrived Reverse packet has been accepted at our branch.
16 delivery attempt Packeta Home made unsuccessful delivery attempt of packet.
17 rejected by recipient Packeta Home delivery attempt of packet end in rejected by recipient response.
999 unknown Unknown packet status.

ShipmentIdDetail

Type Field name Constraints Required Description
unsignedInt id yes A unique ID of the shipment.
string checksum yes Empty string. Deprecated.
string barcode yes A shipment barcode in format: D-***-XM-<id>. Id is numeric value that may be prefixed with 0, length is not restricted.
string barcodeText yes Same value as barcode. Deprecated.

StatusRecord

Type Field name Required Description
dateTime dateTime yes Date and time of the status change. The format is Y-m-d\TH:i:s, example: 2016-07-25T12:00:00.
unsignedInt statusCode yes Integer status code, see the status code table for more info.
string codeText yes Text representation of the code, see the status code table for more info.
string statusText yes Text description of the status.
unsignedInt branchId yes ID of the position of the packet in the moment of the last status change. Defaults to 0 if the branch data is not available.
unsignedInt destinationBranchId yes If status change regards moving to different branch, this field contains the ID of the destination branch. Defaults to 0 if the field is not relevant.
string externalTrackingCode ne If the packet is being delivered by an external carrier and this status change indicates handing over of the packet to the carrier, you can find the carrier's tracking code here.

ExternalStatusRecord

Type Field name Required Description
dateTime dateTime yes Date and time of the status change. The format is Y-m-d\TH:i:s, example: 2016-07-25T12:00:00.
string carrierClass yes External carrier identificator, example: czpacketahome
string statusCode yes Text representation of the status code from external carrier.
string externalStatusName yes Text description of the status.
string externalNote no Additional note for status.
string externalTrackingCode no External carrier's tracking code

PacketB2BAttributes

Type Field name Required Description
integer addressId yes Address ID of destination Pickup Point.
integer count no Count of packets to create, default 1.
boolean isReturn no Whether packet is return, default false

StatusRecords

Is an array of type StatusRecord.

ExternalStatusRecords

Is an array of type ExternalStatusRecord.

NullableDate

Is a date field with a possibility of null value.

PacketCourierNumberV2Result

Type Field name Constraints Required Description
string courierNumber yes The courier's number.
unsignedInt carrierId no Numeric identifier of the chosen carrier method.
string carrierName no Name of the chosen carrier method, in english.

Error messages

AttributeFault

Indicates an error that occured on a field specified by field's name and fault string.

Type Field name Required Description
string name yes Name of the invalid attribute (field).
string fault yes Description of the error.

ShipmentNotFoundFault

Shipment was not found by provided shipment identifier.

Does not contain any additional information.

CustomBarcodeNotAllowedFault

A custom barcode was used while its usage was not allowed.

Does not contain any additional information.

DateOutOfRangeFault

An entered date was out of supported range.

Does not contain any additional information.

DispatchOrderNotAllowedFault

An error has occured while validating packet attributes: trying to issue a DispatchOrder by setting PacketAttributes.dispatchOrder, while no fullfillment agreement is in place.

Does not contain any additional information.

IncorrectApiPasswordFault

An invalid API password was used.

Does not contain any additional information.

NoPacketIdsFault

An empty packetIds structure was passed to the method.

Does not contain any additional information.

NotSupportedFault

The action is not supported by the third party.

Does not contain any additional information.

PacketAttributesFault

An error has occurred while validating packet attributes.

Contains an array of type AttributeFault.

PacketIdFault

An error has occurred while validating packet attributes, an entered packetId is either not valid or does not belong inside your assigned packetId range.

Does not contain any additional information.

PacketIdsFault

Some of the packetIds passed to the method were not valid or were not from your assigned ID range.

Contains an array of invalid Ids.

SenderNotExists

A specified sender does not exist under your account.

Does not contain any additional information.

UnknownLabelFormatFault

An unknown label format was requested.

Does not contain any additional information.

ExternalGatewayFault

An error occured while communicating with third party service.

Does not contain any additional information.

InvalidCourierNumber

Supplied courier number was either not valid or couldn't be verified.

Does not contain any additional information.

Function reference

NOTE: All functions take API password as their first parameter. Due to its repetitiveness, it will be omitted from the function reference.

NOTE: The above also applies for an error message IncorrectApiPasswordFault.

For usage examples we will assume following prerequisities:

Usage:

<?php

$client = new SoapClient("http://www.zasilkovna.cz/api/soap-php-bugfix.wsdl"); // initialize the client
$pw = "1234567890abcdef1234567890abcdef"; // API password

packetAttributesValid()

Function prototype: void packetAttributesValid(PacketAttributes attributes)

Validates PacketAttributes.

On success (the attributes are valid) does not return anything.

Possible errors:

Usage:

<?php

$attributes = [
    "number" => "123abc",
    "name" => "John",
    "surname" => "Doe",
    "email" => "john.doe@test.te",
    "addressId" => 95,
    "value" => 100.00,
    "eshop" => "my-eshop",
];
try {
    $client->packetAttributesValid($pw, $attributes);
}
catch (SoapFault $e){
    ...
}
<packetAttributesValid>
    <apiPassword>...</apiPassword>
    <packetAttributes>
        <number>123abc</number>
        <name>John</name>
        <surname>Doe</surname>
        <email>john.doe@test.te</email>
        <addressId>95</addressId>
        <value>100.00</value>
        <eshop>my-eshop</eshop>
    </packetAttributes>
</packetAttributesValid>

packetClaimAttributesValid()

Function prototype: void packetClaimAttributesValid(ClaimAttributes attributes)

Validates ClaimAttributes.

On success (the attributes are valid) does not return anything.

Possible errors:

Usage:

<?php

$claimAttributes = [
    "number" => "RET123abc",
    "email" => "john.doe@test.te",
    "value" => 100.00,
    "eshop" => "my-eshop",
];
try {
    $client->packetClaimAttributesValid($pw, $claimAttributes);
}
catch (SoapFault $e){
    ...
}
<packetClaimAttributesValid>
    <apiPassword>...</apiPassword>
    <claimAttributes>
        <number>RET123abc</number>
        <email>john.doe@test.te</email>
        <value>100.00</value>
        <eshop>my-eshop</eshop>
    </claimAttributes>
</packetClaimAttributesValid>

createPacket()

Function prototype: PacketIdDetail createPacket(PacketAttributes attributes)

Creates packet from PacketAttributes.

On success returns PacketIdDetail with information about the newly created packet.

Possible errors:

Usage:

<?php

$attributes = [
    "number" => "123abc",
    "name" => "John",
    "surname" => "Doe",
    "email" => "john.doe@test.te",
    "addressId" => 95,
    "value" => 100.00,
    "eshop" => "my-eshop",
];
try {
    $client->createPacket($pw, $attributes);
}
catch (SoapFault $e){
    ...
}
<createPacket>
    <apiPassword>...</apiPassword>
    <packetAttributes>
        <number>123abc</number>
        <name>John</name>
        <surname>Doe</surname>
        <email>john.doe@test.te</email>
        <addressId>95</addressId>
        <value>100.00</value>
        <eshop>my-eshop</eshop>
    </packetAttributes>
</createPacket>

createPacketClaim()

Function prototype: PacketIdDetail createPacketClaim(ClaimAttributes attributes)

Creates a claim assistant packet from ClaimAttributes.

On success returns PacketIdDetail with information about the newly created packet.

Possible errors:

Usage:

<?php

$claimAttributes = [
    "number" => "RET123abc",
    "email" => "john.doe@test.te",
    "value" => 100.00,
    "eshop" => "my-eshop",
    "currency" => "CZK",
];
try {
    $client->createPacketClaim($pw, $claimAttributes);
}
catch (SoapFault $e){
    ...
}
<createPacketClaim>
    <apiPassword>...</apiPassword>
    <claimAttributes>
        <number>RET123abc</number>
        <email>john.doe@test.te</email>
        <value>100.00</value>
        <eshop>my-eshop</eshop>
        <currency>CZK</currency>
    </claimAttributes>
</createPacketClaim>

createPacketClaimWithPassword()

Function prototype: PacketDetail createPacketClaimWithPassword(ClaimWithPasswordAttributes attributes)

Creates a claim assistant packet from ClaimWithPasswordAttributes.

On success returns PacketDetail with information about the newly created packet.

Possible errors:

  • PacketAttributesFault
  • PacketEmailNotFilled: when sendEmailToCustomer is true, loaded packet by given id have to contain valid email; otherwise PacketEmailNotFilled is raised

Usage:

<?php

$claimAttributes = [
    "id" => 123456789,
    "number" => "RET123abc",
    "email" => "john.doe@test.te",
    "value" => 100.00,
    "eshop" => "my-eshop",
    "phone" => "+420723456789",
    "currency" => "CZK",
    "consignCountry" => "cz"
    "sendEmailToCustomer" => 1,
];

try {
    $client->createPacketClaimWithPassword($pw, $claimAttributes);
}
catch (SoapFault $e){
    ...
}
<createPacketClaimWithPassword>
    <apiPassword>...</apiPassword>
    <claimWithPasswordAttributes>
        <id>123456789</id>
        <number>objednavka2</number>
        <email>email@email.cz</email>
        <phone>+420723456789</phone>
        <value>100</value>
        <currency>CZK</currency>
        <eshop>test.ejha.cz</eshop>
        <consignCountry>sk</consignCountry>
        <sendEmailToCustomer>1</sendEmailToCustomer>
    </claimWithPasswordAttributes>
</createPacketClaimWithPassword>

createPacketsB2B()

Function prototype: CreatePacketsB2BResults createPacketsB2B(PacketB2BAttributes attributes)

Creates a B2B packet from PacketB2BAttributes.

On success returns CreatePacketsB2BResults, that is an array of type PacketIdDetail, with information about the newly created packets.

Possible errors:

Usage:

<?php

$packetB2BAttributes = [
    "addressId" => "95",
    "count" => "2",
];
try {
    $client->createPacketsB2B($pw, $packetB2BAttributes);
}
catch (SoapFault $e){
    ...
}
<createPacketsB2B>
    <apiPassword>...</apiPassword>
    <packetB2BAttributes>
        <addressId>95</addressId>
        <count>2</count>
    </packetB2BAttributes>
</createPacketsB2B>

createShipment()

Function prototype: ShipmentIdDetail createShipment(PacketIds packetIds, string customBarcode)

Creates a shipment from PacketIds. If customBarcode is specified and available for your account, the shipment will be created with the entered customBarcode.

On success returns ShipmentIdDetail with information about the newly created shipment.

Possible errors:

NOTE: The method does not accept IDs of claim assistant packets in PacketIds. If claim assistant packet ID is entered, function will return PacketIdsFault.

Usage:

<?php

$packetIds = [
    "1234567890",
    "1234567891",
    "1234567892",
    "1234567893",
];
try {
    $client->createShipment($pw, $packetIds);
}
catch (SoapFault $e){
    ...
}
<createShipment>
    <apiPassword>...</apiPassword>
    <packetIds>
        <id>1234567890</id>
        <id>1234567891</id>
        <id>1234567892</id>
        <id>1234567893</id>
    </packetIds>
</createShipment>

shipmentPackets()

Function prototype: ShipmentPacketsResult shipmentPackets(string $shipmentId)

Finds the packets inside shipment identified by D-code or B-code shipmentId.

On success returns ShipmentPacketsResult with information about shipment packets.

Possible errors:

Usage:

<?php

$shipmentId = 'D-***-XM-12345678';
try {
    $client->shipmentPackets($pw, $shipmentId);
}
catch (SoapFault $e){
    ...
}
<shipmentPackets>
    <apiPassword>...</apiPassword>
    <shipmentId>D-***-XM-12345678</shipmentId>
</shipmentPackets>

packetStatus()

Function prototype: CurrentStatusRecord packetStatus(unsignedLong packetId)

Fetches information about the current status of the packet specified by packetId.

On success returns CurrentStatusRecord.

Possible errors:

Usage:

<?php

$packetId = "1234567890";
try {
    $client->packetStatus($pw, $packetId);
}
catch (SoapFault $e){
    ...
}
<packetStatus>
    <apiPassword>...</apiPassword>
    <packetId>1234567890</packetId>
</packetStatus>

packetTracking()

Function prototype: StatusRecords packetTracking(unsignedLong packetId)

Fetches the whole tracking history of the packet specified by packetId.

On success returns StatusRecords.

Possible errors:

Usage:

<?php

$packetId = "1234567890";
try {
    $client->packetTracking($pw, $packetId);
}
catch (SoapFault $e){
    ...
}
<packetTracking>
    <apiPassword>...</apiPassword>
    <packetId>1234567890</packetId>
</packetTracking>

packetCourierTracking()

Function prototype: ExternalStatusRecords packetCourierTracking(unsignedLong packetId)

Fetches the whole tracking history of the packet from external carrier specified by packetId.

On success returns ExternalStatusRecords.

Possible errors:

Usage:

<?php

$packetId = "1234567890";
try {
    $client->packetCourierTracking($pw, $packetId);
}
catch (SoapFault $e){
    ...
}
<packetCourierTracking>
    <apiPassword>...</apiPassword>
    <packetId>1234567890</packetId>
</packetCourierTracking>

packetGetStoredUntil()

Function prototype: NullableDate packetGetStoredUntil(unsignedLong packetId)

Fetches the date until which the packet specified by packetId is stored and waiting for pickup. If the packet is not yet ready for pickup or is already returning to sender null is returned.

Possible errors:

Usage:

<?php

$packetId = "1234567890";
try {
    $client->packetGetStoredUntil($pw, $packetId);
}
catch (SoapFault $e){
    ...
}
<packetGetStoredUntil>
    <apiPassword>...</apiPassword>
    <packetId>1234567890</packetId>
</packetGetStoredUntil>

packetSetStoredUntil()

Function prototype: void packetSetStoredUntil(unsignedLong packetId, date date)

Sets the date until which the packet specified by packetId is stored and waiting for pickup.

On success (the date has been changed) does not return anything.

Possible errors:

Usage:

<?php

$packetId = "1234567890";
$date = "2016-08-30";
try {
    $client->packetSetStoredUntil($pw, $packetId, $date);
}
catch (SoapFault $e){
    ...
}
<packetSetStoredUntil>
    <apiPassword>...</apiPassword>
    <packetId>1234567890</packetId>
    <date>2016-08-30</date>
</packetSetStoredUntil>

barcodePng()

Function prototype: binary barcodePng(string barcode)

Returns a PNG image of the specified barcode. The barcode is created with Code 128 symbology.

NOTE: The method does not validate the barcode in any way. If you wish to create a barcode to use it on your labels, it is important that you use packetId prefixed by the letter Z e.g. Z1234567890.

Usage:

<?php

$packetId = "Z1234567890";
try {
    $client->barcodePng($pw, $barcode);
}
catch (SoapFault $e){
    ...
}
<barcodePng>
    <apiPassword>...</apiPassword>
    <barcode>Z1234567890</barcode>
</barcodePng>

packetLabelPdf()

Function prototype: binary packetLabelPdf(unsignedLong packetId, string format, unsignedInt offset)

Fetches a label for packet specified by packetId in format specified by format on a position specified by offset. The position is calculated left to right starting at top left corner of the document.

On success returns a PDF file (base64 encoded binary) with the label.

The format parameter accepts following values:

  • A6 on A6 - 105x148 mm (A6) label on a page of the same size
  • A7 on A7 - 105x74 mm (A7) label on a page of the same size
  • A6 on A4 - 105x148 mm (A6) label on a page of size 210x297 mm (A4)
  • A7 on A4 - 105x74 mm (A7) label on a page of size 210x297 mm (A4)
  • 105x35mm on A4 - 105x35 mm label on a page of size 210x297 mm (A4)
  • A8 on A8 - 50x74 mm (A8) label on a page of the same size

Possible errors:

Usage:

<?php

$packetId = "1234567890";
$format = "A7 on A4";
$offset = 0;
try {
    $client->packetLabelPdf($pw, $packetId, $format, $offset);
}
catch (SoapFault $e){
    ...
}
<packetLabelPdf>
    <apiPassword>...</apiPassword>
    <packetId>1234567890</packetId>
    <format>A7 on A4</format>
    <offset>0</offset>
</packetLabelPdf>

packetsLabelsPdf()

Function prototype: binary packetsLabelsPdf(PacketIds packetIds, string format, unsignedInt offset)

Fetches labels for packets specified by packetIds in format specified by format starting on a position specified by offset. The position is calculated left to right starting at top left corner of the document.

On success returns a PDF file (base64 encoded binary) with the labels.

The format parameter accepts the same values as in the packetLabelPdf() method.

Possible errors:

Usage:

<?php

$packetIds = [
    "1234567890",
    "1234567891",
    "1234567892",
];
$format = "A7 on A4";
$offset = 0;
try {
    $client->packetsLabelsPdf($pw, $packetIds, $format, $offset);
}
catch (SoapFault $e){
    ...
}
<packetsLabelsPdf>
    <apiPassword>...</apiPassword>
    <packetIds>
        <id>1234567890</id>
        <id>1234567891</id>
        <id>1234567892</id>
    </packetId>
    <format>A7 on A4</format>
    <offset>0</offset>
</packetsLabelsPdf>

packetCourierNumber()

Function prototype: string packetCourierNumber(unsignedLong packetId)

Returns a tracking code if the external carrier allows it, ie. its apiAllowed attribute is set to true.

Possible errors:

Usage:

<?php

$packetId = "1234567890";
try {
    $client->packetCourierNumber($pw, $packetId);
}
catch (SoapFault $e){
    ...
}
<packetCourierNumber>
    <apiPassword>...</apiPassword>
    <packetId>1234567890</packetId>
</packetCourierNumber>

packetCourierNumberV2()

Function prototype: string packetCourierNumberV2(unsignedLong packetId)

Version 2 of the method packetCourierNumber(), works the same way, except:

on success it returns packetCourierNumberV2Result.

Possible errors:

Usage:

<?php

$packetId = "1234567890";
try {
    $client->packetCourierNumberV2($pw, $packetId);
}
catch (SoapFault $e){
    ...
}
<packetCourierNumberV2>
    <apiPassword>...</apiPassword>
    <packetId>1234567890</packetId>
</packetCourierNumberV2>

packetCourierLabelPng()

Function prototype: base64binary packetCourierLabelPng(unsignedLong packetId, string courierNumber)

Returns label as string containing the PNG image (base64 encoded binary) if the external carrier allows it, ie. its apiAllowed attribute is set to true.

Possible errors:

Usage:

<?php

$packetId = "1234567890";
$courierNumber = "abcd1234567890";
try {
    $png = $client->packetCourierLabelPng($pw, $packetId, $courierNumber);
    header('Content-Type: image/png');
    echo $png;
}
catch (SoapFault $e){
    ...
}
<packetCourierLabelPng>
    <apiPassword>...</apiPassword>
    <packetId>1234567890</packetId>
    <courierNumber>abcd1234567890</courierNumber>
</packetCourierLabelPng>

packetCourierLabelPdf()

Function prototype: binary packetCourierLabelPdf(unsignedLong packetId, string courierNumber)

Returns label as string containing the PDF document (base64 encoded binary) if the external carrier allows it, ie. its apiAllowed attribute is set to true.

Possible errors:

Usage:

<?php

$packetId = "1234567890";
$courierNumber = "abcd1234567890";
try {
    $pdf = $client->packetCourierLabelPdf($pw, $packetId, $courierNumber);
    header('Content-Type: application/pdf');
    echo $pdf;
}
catch (SoapFault $e){
    ...
}
<packetCourierLabelPdf>
    <apiPassword>...</apiPassword>
    <packetId>1234567890</packetId>
    <courierNumber>abcd1234567890</courierNumber>
</packetCourierLabelPdf>

packetsCourierLabelsPdf()

Function prototype: binary packetCourierLabelPdf(PacketIdsWithCourierNumbers packetIdsWithCourierNumbers, unsignedInt offset, string format)

Returns labels as string containing the PDF document (base64 encoded binary) if the external carrier allows it, ie. its apiAllowed attribute is set to true.

The returned PDF page format is, by default, A4 with four 100x150 mm labels placed on each page. There is the optional argument format to specify the output PDF format. It accepts following values:

  • A6 on A4 - 105x148 mm (A6) label on a page of size 210x297 mm (A4)
  • A6 on A6 - 105x148 mm (A6) label on a page of the same size (offset argument is ignored for this format)

If there is more than one label per page, the second argument offset allows skipping some places on the first page.

NOTE: To avoid lost responses, set your request timeout to five seconds times the requested label count. E.g. 120 seconds for 24 labels. Typically, the labels will be generated much faster, but occasionally there may be delays.

Possible errors:

Usage:

<?php
$packetIdsWithCourierNumbers = [
    [
        'packetId' => "1234567890",
        'courierNumber' => "abcd1234567890",
    ],
    [
        'packetId' => "2345678901",
        'courierNumber' => "bcde2345678901",
    ],
];
try {
    $pdf = $client->packetsCourierLabelsPdf($pw, $packetIdsWithCourierNumbers, 0, 'A6 on A4');
    header('Content-Type: application/pdf');
    echo $pdf;
}
catch (SoapFault $e) {
    ...
}
<packetsCourierLabelsPdf>
    <apiPassword>...</apiPassword>
    <packetIdsWithCourierNumbers>
        <packetIdWithCourierNumber>
            <packetId>1234567890</packetId>
            <courierNumber>abcd1234567890</courierNumber>
        </packetIdWithCourierNumber>
        <packetIdWithCourierNumber>
            <packetId>2345678901</packetId>
            <courierNumber>bcde2345678901</courierNumber>
        </packetIdWithCourierNumber>
    </packetIdsWithCourierNumbers>
    <offset>0</offset>
    <format>A6 on A4</format>
</packetsCourierLabelsPdf>

packetLabelZpl()

Function prototype: binary packetLabelZpl(unsignedLong packetId, unsignedInt dpi)

Fetches a label for a packet specified by packetId with DPI specified by dpi.

On success returns an html escaped string representing the ZPL label.

WARNING: It is necessary to HTML unescape the string before printing. Otherwise the label may be rendered incorrectly.

The dpi parameter accepts the following values:

  • 203

  • 300

  • Some carriers support 203 dpi only.

Possible errors:

Usage:

<?php

$packetId = 1234567890;
$dpi = 203;

try {
    $client->packetLabelZpl($pw, $packetId, $dpi);
}
catch (SoapFault $e) {
    ...
}
<packetLabelZpl>
    <apiPassword>...</apiPassword>
    <packetId>1234567890</packetId>
    <dpi>300</dpi>
</packetLabelZpl>

packetCourierLabelZpl()

Function prototype: string packetCourierLabelZpl(unsignedLong packetId, string courierNumber, unsignedInt dpi = 300)

If the external carrier allows it, the method returns their label in ZPL format. Parameter dpi is not required, and defaults as 300 DPI.

This method is currently allowed for the following carriers:

  • CZ Packeta Home
  • SK Packeta Home
  • PL Home Delivery
  • CH Post
  • FR Colis PrivĂ© HD
  • PL InPost Paczkomaty Box
  • RO Sameday HD
  • RO Sameday Easybox

Allowed DPI values:

  • 203
  • 300

On success returns an HTML escaped string containing the ZPL file.

WARNING: It is necessary to HTML unescape the string before printing. Otherwise the label may be rendered incorrectly.

Possible errors:

Usage:

<?php

$packetId = "1234567890";
$courierNumber = "abcd1234567890";
$dpi = 300;
try {
    $zpl = $client->packetCourierLabelZpl($pw, $packetId, $courierNumber, $dpi);
    echo $zpl;
}
catch (SoapFault $e){
    ...
}
<packetCourierLabelZpl>
    <apiPassword>...</apiPassword>
    <packetId>1234567890</packetId>
    <courierNumber>abcd1234567890</courierNumber>
    <dpi>300</dpi>
</packetCourierLabelZpl>

senderGetReturnRouting()

Function prototype: string[] senderGetReturnRouting(string senderLabel)

Returns an array of 2 return routing strings for a sender specified by senderLabel.

Possible errors:

NOTE: These strings are generated from your account settings and need to be downloaded each time you want to use them. If you were to download the strings just once and use the stored value, your return address might change and the strings would be deprecated.

NOTE: It is preferred that the return routing strings are printed each on separate line. See our label specifications.

Usage:

<?php

$senderLabel = "my-eshop";
try {
    $client->senderGetReturnRouting($pw, $senderLabel);
}
catch (SoapFault $e){
    ...
}
<senderGetReturnRouting>
    <apiPassword>...</apiPassword>
    <senderLabel>my-eshop</senderLabel>
</senderGetReturnRouting>

packetInfo()

Function prototype: PacketInfoResult packetInfo(unsignedLong packetId)

Returns additional information about packet and its consignment to an external courier, if there is one.

On success it returns PacketInfoResult.

Possible errors:

Usage:

<?php

try {
    $client->packetInfo($pw, $packetId);
}
catch (SoapFault $e){
    ...
}
<packetInfo>
    <apiPassword>...</apiPassword>
    <packetId>Z1234567890</packetId>
</packetInfo>

Example output:

<?xml version="1.0"?>
<response>
    <status>ok</status>
    <result>
        <branchId>999</branchId>
        <invoicedWeightGrams>570</invoicedWeightGrams>
        <courierInfo>
            <courierInfoItem>
                <courierId>999</courierId>
                <courierName>Example courier</courierName>
                <courierNumbers>
                    <courierNumber>12345678</courierNumber>
                </courierNumbers>
                <courierBarcodes>
                    <courierBarcode>987654321</courierBarcode>
                </courierBarcodes>
                <courierTrackingNumbers>
                    <courierTrackingNumber>1234567890</courierTrackingNumber>
                </courierTrackingNumbers>
                <courierTrackingUrls>
                    <courierTrackingUrl>
                        <lang>en</lang>
                        <url>https://www.example-courier/tracking/en/1234567890</url>
                    </courierTrackingUrl>
                    <courierTrackingUrl>
                        <lang>cs</lang>
                        <url>https://www.example-courier/tracking/cs/1234567890</url>
                    </courierTrackingUrl>
                </courierTrackingUrls>
            </courierInfoItem>
        </courierInfo>
    </result>
</response>