Přeskočit na hlavní obsah
For any questions, feel free to contact our integrations team at integrations@packeta.com

API methods

info

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.

info

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()​

warning

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:

  • PacketAttributesFault
  • PacketEmailNotFilled: when sendEmailToCustomer is set to true, the packet must contain a valid email address; otherwise PacketEmailNotFilled is 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:

info

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:

  • 203
  • 300

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

[Warning]

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.

tip

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.

WARNING

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 (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.

info

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 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:

info

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.

info

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>