API methods
All functions take API password as their first parameter. Due to its repetitiveness, it will be omitted from the function reference.
This also applies for an error message IncorrectApiPasswordFault.
For usage examples we will assume following prerequisities:
Usage:
<?php
$client = new SoapClient("https://soap.api.packeta.com/api/soap-php-bugfix.wsdl"); // initialize the client
$pw = "1234567890abcdef1234567890abcdef"; // API password
barcodePng()
Function prototype: binary barcodePng(string barcode)
Returns a PNG image of the specified barcode. The barcode is created with Code 128 symbology.
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>{{API_PASSWORD}}</apiPassword>
<barcode>Z1234567890</barcode>
</barcodePng>
cancelPacket()
Function prototype: void cancelPacket(unsignedLong packetId)
Cancels not physically submitted packet specified by packetId.
On success (packet was canceled) does not return anything.
Possible errors:
Usage:
<?php
$packetId = '1234567890';
try {
$client->cancelPacket($pw, $packetId);
} catch (SoapFault $e) {
...
}
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',
'company' => 'Company',
'email' => 'example@packetatest.com',
'addressId' => 95,
'cod' => 100.00,
'value' => 100.00,
'currency' => 'CZK',
'weight' => 2,
'eshop' => 'MyEshop',
];
try {
$client->createPacket($pw, $attributes);
} catch (SoapFault $e) {
...
}
<createPacket>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<packetAttributes>
<number>123abc</number>
<name>John</name>
<surname>Doe</surname>
<email>example@packetatest.com</email>
<addressId>95</addressId>
<value>100.00</value>
<weight>2</weight>
<eshop>{{SENDER_INDICATION}}</eshop>
</packetAttributes>
</createPacket>
createPacketClaim()
This method is deprecated. Use createPacketClaimWithPassword() to obtain all functionalities available (return to Z-BOX).
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' => 'example@packetatest.com',
'phone' => '+420777777777',
'value' => 100.00,
'currency' => CZK,
'eshop' => 'MyEshop',
'sendLabelToEmail' => true,
];
try {
$client->createPacketClaim($pw, $claimAttributes);
} catch (SoapFault $e) {
...
}
<createPacketClaim>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<claimAttributes>
<number>RET123abc</number>
<email>example@packetatest.com</email>
<value>100.00</value>
<eshop>{{SENDER_INDICATION}}</eshop>
</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:
PacketAttributesFaultPacketEmailNotFilled: whensendEmailToCustomeris set totrue, the packet must contain a valid email address; otherwisePacketEmailNotFilledis raised
Usage:
<?php
$claimAttributes = [
'number' => 'RET123abc',
'email' => 'example@packetatest.com',
'phone' => '+4207777777777',
'value' => 100.00,
'currency' => 'CZK',
'eshop' => 'MyEshop',
'consignCountry' => 'CZ',
'sendEmailToCustomer' => false,
];
try {
$client->createPacketClaimWithPassword($pw, $claimAttributes);
} catch (SoapFault $e) {
...
}
<createPacketClaimWithPassword>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<claimWithPasswordAttributes>
<id>123456789</id>
<number>claimNumber</number>
<email>example@packetatest.com</email>
<phone>+420723456789</phone>
<value>100</value>
<currency>CZK</currency>
<eshop>{{SENDER_INDICATION}}</eshop>
<consignCountry>CZ</consignCountry>
<sendEmailToCustomer>false</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>{{API_PASSWORD}}</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:
The Method does not accept IDs of packets, that were already consigned physically. If consigned packet ID is entered, function will return PacketIdsFault.
The method also 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>{{API_PASSWORD}}</apiPassword>
<packetIds>
<id>1234567890</id>
<id>1234567891</id>
<id>1234567892</id>
<id>1234567893</id>
</packetIds>
</createShipment>
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' => 'example@packetatest.com',
'addressId' => 95,
'value' => 100.00,
'eshop' => 'MyEshop',
];
try {
$client->packetAttributesValid($pw, $attributes);
} catch (SoapFault $e) {
...
}
<packetAttributesValid>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<packetAttributes>
<number>123abc</number>
<name>John</name>
<surname>Doe</surname>
<email>example@packetatest.com</email>
<addressId>95</addressId>
<value>100.00</value>
<currency>CZK</currency>
<eshop>Myshop</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' => 'example@packetatest.com',
'phone' => '+420777777777',
'value' => 100.00,
'currency' => CZK,
'eshop' => 'Myshop',
'sendLabelToEmail' => 'true',
];
try {
$client->packetClaimAttributesValid($pw, $claimAttributes);
} catch (SoapFault $e) {
...
}
<packetClaimAttributesValid>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<claimAttributes>
<number>RET123abc</number>
<email>example@packetatest.com</email>
<phone>+420777777777</phone>
<value>100.00</value>
<currency>100.00</currency>
<eshop>Myshop</eshop>
<sendLabelToEmail>true</sendLabelToEmail>
</claimAttributes>
</packetClaimAttributesValid>
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>{{API_PASSWORD}}</apiPassword>
<packetId>1234567890</packetId>
<courierNumber>abcd1234567890</courierNumber>
</packetCourierLabelPdf>
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>{{API_PASSWORD}}</apiPassword>
<packetId>1234567890</packetId>
<courierNumber>abcd1234567890</courierNumber>
</packetCourierLabelPng>
packetCourierLabelZpl()
Function prototype: string packetCourierLabelZpl(unsignedLong packetId, string courierNumber, unsignedInt dpi = 300)
If the external carrier allows it, the method returns carrier label in ZPL format. List of supported carriers can be found at Label printing - Carrier labels
Parameter dpi is not required, default value is 300 DPI.
Allowed DPI values:
203300
On success returns an HTML/XML escaped string containing the ZPL file.
It is necessary to 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>{{API_PASSWORD}}</apiPassword>
<packetId>1234567890</packetId>
<courierNumber>abcd1234567890</courierNumber>
<dpi>300</dpi>
</packetCourierLabelZpl>
packetCourierNumber()
Deprecated - this method does not return full information for BDS.
Function prototype: string packetCourierNumber(unsignedLong packetId)
Returns a courier number 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>{{API_PASSWORD}}</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>{{API_PASSWORD}}</apiPassword>
<packetId>1234567890</packetId>
</packetCourierNumberV2>
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>{{API_PASSWORD}}</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 pick-up. If the packet is not yet ready for pick-up 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>{{API_PASSWORD}}</apiPassword>
<packetId>1234567890</packetId>
</packetGetStoredUntil>
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 returns PacketInfoResult, CourierInfo.
Find how to consign packets to Z-BOXes in this guide.
Possible errors:
Usage:
<?php
try {
$client->packetInfo($pw, $packetId);
} catch (SoapFault $e) {
...
}
<packetInfo>
<apiPassword>{{API_PASSWORD}}</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> <!-- Carrier packet ID -->
</courierNumbers>
<courierBarcodes>
<courierBarcode>987654321</courierBarcode> <!-- Barcode value printed on the label -->
</courierBarcodes>
<courierTrackingNumbers>
<courierTrackingNumber>ABC1234</courierTrackingNumber> <!-- Carrier tracking number -->
</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>
<services/>
<number>OrderNumber</number>
<consignPassword>123456789</consignPassword> <!-- Optional, only if applicable -->
<pickupPassword>123456789</pickupPassword> <!-- Optional, only if applicable -->
</result>
</response>
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 with the label.
Possible errors:
Usage:
<?php
$packetId = '1234567890';
$format = 'A6 on A6';
$offset = 0;
try {
$client->packetLabelPdf($pw, $packetId, $format, $offset);
} catch (SoapFault $e) {
...
}
<packetLabelPdf>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<packetId>1234567890</packetId>
<format>A6 on A6</format>
<offset>0</offset>
</packetLabelPdf>
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 XML/HTML escaped string representing the ZPL label.
It is necessary to unescape the string before printing. Otherwise the label may be rendered incorrectly.
Possible errors:
Usage:
<?php
$packetId = 1234567890;
$dpi = 203;
$format ='A6';
try {
$client->packetLabelZpl($pw, $packetId, $dpi);
} catch (SoapFault $e) {
...
}
<packetLabelZpl>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<packetId>1234567890</packetId>
<format>A6</format>
<dpi>300</dpi>
</packetLabelZpl>
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 105x148 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 (offsetargument 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.
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:
PacketIdFaultNotSupportedFaultExternalGatewayFaultInvalidCourierNumberNoPacketIdsFaultUnknownLabelFormatFault
Usage:
<?php
$packetIdsWithCourierNumbers = [
[
'packetId' => '1234567890',
'courierNumber' => 'abcd1234567890',
],
[
'packetId' => '2345678901',
'courierNumber' => 'bcde2345678901',
],
];
try {
$pdf = $client->packetsCourierLabelsPdf($pw, $packetIdsWithCourierNumbers, 0, 'A6 on A6');
header('Content-Type: application/pdf');
echo $pdf;
} catch (SoapFault $e) {
...
}
<packetsCourierLabelsPdf>
<apiPassword>{{API_PASSWORD}}</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 A6</format>
</packetsCourierLabelsPdf>
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 = '2023-12-30';
try {
$client->packetSetStoredUntil($pw, $packetId, $date);
} catch (SoapFault $e) {
...
}
<packetSetStoredUntil>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<packetId>1234567890</packetId>
<date>2023-12-30</date>
</packetSetStoredUntil>
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 with the labels.
The format parameter accepts the same values as in the packetLabelPdf() method.
Possible errors:
Usage:
<?php
$packetIds = [
'1234567890',
'1234567891',
'1234567892',
];
$format = 'A6 on A6';
$offset = 0;
try {
$client->packetsLabelsPdf($pw, $packetIds, $format, $offset);
} catch (SoapFault $e) {
...
}
<packetsLabelsPdf>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<packetIds>
<id>1234567890</id>
<id>1234567891</id>
<id>1234567892</id>
</packetIds>
<format>A6 on A6</format>
<offset>0</offset>
</packetsLabelsPdf>
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>{{API_PASSWORD}}</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>{{API_PASSWORD}}</apiPassword>
<packetId>1234567890</packetId>
</packetTracking>
senderGetReturnRouting()
Function prototype: string[] senderGetReturnRouting(string senderLabel)
Returns an array of 2 return routing strings for a sender specified by senderLabel.
Possible errors:
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.
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>{{API_PASSWORD}}</apiPassword>
<senderLabel>my-eshop</senderLabel>
</senderGetReturnRouting>
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>{{API_PASSWORD}}</apiPassword>
<shipmentId>D-***-XM-12345678</shipmentId>
</shipmentPackets>