User manual

tracking system using the WSDL/SOAP WebSerwis method

1. Introduction

Poczta Polska SA provides WSDL network service, which provides tracking of postal items.

The service is available at:

The tracking system service allows you to create one -off queries by one parcel number and many shipments.
You can use a default account for one -time system, the parameters of which are as follows:
  • Login: sliding
  • Password: PPSA
Customers who plan to formulate at once inquiries about larger quantities of parcels or obtain extended information about parcels, we encourage you to set up a dedicated account. To this end, please contact Poczta Polska SA via a dedicated form.

ATTENTION! Data provided by the Web Service Poczta Polska SA cannot be modified in the substantive scope. Any changes in the information scope, changes in the content of messages, e.g. type and shipping numbers, time of events, their order changes are unacceptable. Only modifications in the method of visualization of data are allowed: matching of the cut and font size, distribution of elements, etc. Data obtained with this tool must not be used for purposes other than reliable informing customers about events regarding their shipments provided by shipments provided by Polish Post Office SA SA

2. WSDL WebSerwis Methods

And information methods
Hello
Method for testing the correctness of transmitting parameters. Requires the parameter of the name (String) and returns the text Hello .
version
Returns the Web Service (String) version number
maximum licker
Returns the maximum number about shipments (INT), which you can ask for methods of checking , checking
II checking one or many shipments
Check
Requires a parcel number, returns information about a given parcel in the Shipment - detailed information about facilities in attributes type unit is not generated .
check -ups
It requires providing a parcel number or several shipping numbers, returns information about the provided shipments in the Message - detailed information about facilities in attributes such as the unit is not generated .
Check
Requires a parcel number, returns information about a given parcel in the Shipment - detailed information about facilities in attributes type unit is generated .
Check
requires providing a parcel number or several shipping numbers, returns information about the provided shipments in the structure Message - detailed information about facilities in attributes such as the unit is generated .
III Checking shipments with events in the given period ...
check -up
It requires providing one or several shipping numbers and a time range in the form of a start and end day (Yyyy-MM-DD). Returns the structure of the message , and detailed information about facilities in attributes type unit is not generated . In this method, the structure of the parcel in the shipment list is filled with data only for shipments with events in the given period. If the parcel did not have events in the given period, an empty shipping (only status and number fields filled) with a status equal to 2,
check -up
It requires providing one or several shipping numbers and a time range in the form of a start and end day (Yyyy-MM-DD). Returns the structure of the message , and detailed information about facilities in attributes type unit is generated . In this method, the structure of the parcel in the shipment list is filled with data only for shipments with events in the given period. If the parcel had no events in the given period, an empty structure is returned ( only status and number fields filled) with a status equal to 2,
IV authorization
Web Service uses a simple authentication mechanism based on the so -called Username token element . This standard has been defined in the Web Services Security (WSS): http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf . The so -called so -called Security element containing the username and password. Examples of the Witaj containing a full Security element is presented below.
V Request
For the proper operation of the WebSerwisu Soap/WSDL, it is necessary to send the correct Request. Below is an example using general authorization data:
sliding PPSA Yyyy-mm-ddt00: 00: 00,000z Jan
Diagnostic methods (apart from Hello ) should not have any content in the body. Other methods should have the following structure in the body:
For methods asking for a single shipment:
Method > 123456 Method >
For methods asking with more shipments:
Method > 123456 123456789 Method >

ATTENTION! It should be remembered that the header must be added to each Request:

"Soapaction": "Urn: "," Content-Type ":" TEXT/XML; CharSet = UTF-8 "
Errors will be returned without the right header. List of errors under the instructions.

3. Information provided by Web Service

Data structure:
WSDL data structure
Web Service provides the following information:
  • type of parcel (together with the type of parcel type), e.g. priority package (PRP),
  • Date of shipping,
  • Shipping format (S, M, L)
  • The name of the facility, in which the parcel was sent, e.g. UP Augustów 1,
  • name of the facility to which the shipment will be directed,
  • country of granting (together with the country code), e.g. Poland (PL),
  • the country of destination (together with the code of the country of destination),
  • Shipment weight (in kg),
  • information on the completion of the parcel service by Poczta Polska SA,
  • Information on a related shipment (procedural shipment)
    • procedure code
    • Name of the procedure
    • packaging type (or company envelope [t - yes, n - no])
    • List of related shipping numbers
  • List of events related to shipping (statuses). For each of the events, it is available:
    • Date and time of the event,
    • Name of the event (together with the event code), e.g. delivery (p_D),
    • the cause of the event (along with the causes code), e.g. not the addressee (p_a_aanz),
    • The name of the facility in which the event took place.
    • Information whether the event is the last event ending the service of the parcel by Poczta Polska SA extended methods (*PL) return additional information about the institution of posting and destination and the facilities where the events took place:
  • geographical coordinates of the facility,
  • address details of the facility:
    • the name of the place,
    • PNA,
    • street name,
    • House number,
    • premises number,
  • institution working hours:
    • on business days, e.g. 08: 00-20: 00 or pon.: 08: 00-20: 00, Tue.: 08: 00-20: 00, Wed.: 09: 00-16: 00, Thurs: 08: 00-20: 00, titled: 08: 00-20: 00,
    • on Saturdays,
    • on Sundays and holidays,
    • Comments on working hours.
Data model:
Announcement
status (int):
0
Found the data of the searched parcel
-1
inquiry about too many shipments
-2
No authorization to check many shipments
-3
The dates given in calling the method of check-ups or check-ups It is not checked whether the final date is greater or equal to the initial date. In this case, checked shipments, if they exist, will have status (in the structure of the parcel!) Equal to 2 - description below.
-99
Other error
Shipping (Listaprzesilek): Filled for a status equal to 0
List
Shipment (shipping [])
Delivery
status (int):
0
Found the data of the searched parcel
1
There are other shipments with this number
2
The shipment with the given number is in the system, but there are no events in the given period (applies to Methods)
-1
There is no shipment in the system with this number. Attention! Web Service only includes shipments with at least one event in the last 30 days.
-2
The parcel number provided is incorrect
-99
Other error
Number (String [20]): Shipping number (in accordance with the method provided in the parameter)
Data (data)
Step.
number (String [20]) - Shipping number again
Format (String [3]) - Shipping format
KodrodzPrzes (String [5]) - Shipping type code
Rozprze (String [64]) - type of parcel
DATANAdania (String [10])-date of posting in the form of yyyy-mm-dd
KodkRejunadania (String [5]) - Country of Shipping (e.g. PL)
Krajnadania (String [64]) - name of the country of broadcasting (e.g. Poland)
Kodkrajuprzenz (String [5]) - Country of the Shipping Country (e.g. PL)
Krajprzez (String [64]) - name of the country of destiny (e.g. Poland)
devices (unit) - information about the awarding facility
Office (unit) - information about the destination facility
Masa (float) - Shipment weight in kg
Endoned (Boolean) - whether the so -called Ending event (e.g. delivery, collecting a parcel at the Office, shipping return, etc.)
Procedural (procedure)
Events (list)
Procedure
CODE (String [3]) - CODE OF SERVICE PROCEDURE
Courtertafirm (String [1]) - packaging type (or company envelope) [t - yes, n - no]
Name (String [64]) - Name of the service procedure
Shipping (Listaprazesylekporated [])
List
Shipped (shipped [])
Parcel
nrprzesylkipped (String [20]) - parcel number
List
event (event [])
Event
Time (String [16])-time of the event in the form of Yyyy-MM-DD HH-NN
unit (unit) - unit (PP facility) in which the event took place
code (String [10]) - event code
ending (boolean) - whether this event is terminating the service of the parcel
Name (String [64]) - name of the event (e.g. sending with a load)
Cause (reason) - reason for the event - the attribute is filled only for certain Web Service users
Unit
Name (String [64])
Departmental (mitile units) - empty for methods of checks and checks, filled for check -ups and checkpl
Cause
Name (String [64]) - the cause of the event
CODE (String [10]) - Code of the causes of the event
Masty
Szergeogr (float from N (8.6)) - the latitude of the facility
DLGEOGR (Float with N (9.6)) - geographical length of the facility
town (String [64]) - a place where the facility is located
PNA (String [6]) - PNA (postal code) of the facility
Street (String [169]) - street
GRDOM (String [11]) - House number
NRLOKAL (String [7]) - premises number
Hours of time (hours of work) - facility's working hours
Hours of work
DoBocie (hours from
Saturdays (hours from it) - information about the work of the facility on Saturdays
Niedzisw (hours inaging) - information about the working hours of the facility on Sundays and holidays
Hours
Hours (String [4000])-working hours, e.g. 08: 00-24: 00
Notes (String [4000]) - comments to working hours

ATTENTION! Signs [] behind the type name mean a list (e.g. shipment [] ⬌ List of elements such as shipping), record [ ] at the string type means the maximum length of the text (e.g. String [64] ⬌ text with a maximum length of 64 characters)

4. Error codes

Descriptions of error codes returned by WSDL faultcode
400 Bad Request incorrect shipping number
Answers 400 are assigned to activities/verification related to incorrect data provided by users.
401 Unauthorized Login:<login>
Answers 401 are related to the lack of user authorization, which is related to the erroneous username or password. In the event that the login data is correct, but this message still appears, you should contact the PP SA support at: Slezenie@poczta-polska.pl Adding a returned message and request.
403 Forbidden Login:<login> Blocked account
Answers 403 are related to user locks or a lack of permissions for selected methods. If the error is not related to too many queries addressed to the services of the tracking system, please contact Poczta Polska to determine the causes of the blockade.
405 Method Not Allowed:<login>
This message means that for your login a password has changed or a password is required. To this end, contact PP SA support at: Slezenie@poczta-polska.pl by adding your login and returned message.
404 Resources for the Endpoint Uri Not Found.
This message occurs in "manual" integrations and means that the websewis method has been removed or changed its location in the structure, you should verify WSDL instructions and improve your code.
503 break
System inaccessible or technological break. The answers of the answers contain a feedback with detailed information.

5. FAQ

List
API Gateway Encounted An Error. Error Message: The Endpoint Reference (EPR) for the Operation Not Found is xx.xx.xx.xx/WS/Ppapitrackingwstt/1.0 and the WSA Action = null. If this epr was prevously reacable, please contact the server administrator .. Request details: service - ppapitrackingwstt, operation - null, invocation time: 11: 09: 39 am, date: jul 8, 2024, client IP - xx.xx.xx.xx.xx Application: Null
Announcement ... WSA Action = null ... means that when you make an inquiry to WSDL/SOAP, no header has been added
"Soapaction": "Urn:<metoda> "
.
Object Not found ( non-existing-endpointws/ppapitrackingwstt.leciehttpsoap11ndpoint/1.0 )
This message indicates that an erroneous endpoint is used - WSDL instructions should be verified and your code improves.
API Gateway Encounted An Error. Error Message: API Gateway Outbound Client Encounted Internal Server Error. Request Details: Service - PPAPiPitrackingwstt, Operation - Check -the -Silesian, Invocation Time: HH: II: SS PM, Date: M DD, RRRR, Client IP - xxx.xx.xx.xxx, user - Default and Application: NULL
It should be verified whether your Request has all the necessary parameters and scheme. -full element or a passwordtext is not properly defined . You should compare your requests with an example request .
API Gateway Encounted An Error. Error Message: API Gateway Outbound Client Encounted WsdallReceiver: Security Processing Failed. Request Details: Service - PPAPiPitrackingwstt, Operation - Check -the -Silesian, Invocation Time: HH: II: SS PM, Date: M DD, RRRR, Client IP - XX.XX.XXX.XX, User - Default and Application: NULL
The message ... Security Processing Failed ... means that in the definition of Usernametoken has not been properly indicated (or lacking at all) the scheme. You should compare your requests with an example request .
Fatal Error: Uncaught Soappfault Exception: [VersionMISMatch] Wrong Version
Probably your code uses SOAP 1.2. The implemented SOAP version in the tracking system is SOAP 1.1. Both differ even in the definition NameSpace:
SOAP 1.1 NameSpace: http://schemas.xmlsap.org/soap/envelope Soap 1.2 namespace: http://www.w3.org/2003/05/soap-envelope
Failed to Connect to TT.Poczta-polska.pl Port 80 After XX MS: Connection Refused
This message means that our firewall has detected a suspicious movement from your IP address and it has been blocked. To this end, you should contact the PP SA support at: slejenia@poczta-polska.pl by adding your login and returned message.
API Gateway Encounted An Error. Error Message: API Gateway Outbound Client Encounted Decoding Error; Illegal Input Parameter Value (S). Request Details: Service - PPAPiPitrackingwstt, Operation - Maximum Liceral, Invocation Time: HH: II: SS PM, Date: M DD, RRRR, Client IP - XX.XXX.XX.XXX, User - Default and Application: NULL
Message ... illegal input parameter Value (s). He informs that information methods (except hello ) in their body can not contain anything. If for the aforementioned method of maximum lenses we add in the body , we will receive such an error message. Clean the Body section.
Error While Applying Xpath. Error: Exception Occurred Evaluult Xpath:/Soapenv: Envelope/SOAPENV: Body/Ns: Check -the -Silesponse/Ns: Return/AX21: Shipments/Ax21: Shipping/Ax21: Daneprzesielki/Ax21: Events/Ax21: event. Exception: Xpath Expression Uses Unbound Namespace Prefix Ns
Error on the client application side. Depending on the language in which the code of its own application is written, some mechanisms require prefix in the form NS. Some libraries require to declare used name spaces. However, you can use the XPath design without name space. You can then use an exemplary expression:
/*[Local-Name () = 'Envelope']/*[Local-Name () = 'Body']/*[Local-Name () = 'check-upsponsponse']/*[Local-Name () = 'Return']/*[Local-Name [Local-Name () = 'Shipments']/*[Local-Name () = 'Shipment']/*[Local-Name () = 'Danep Silesia']/*[Local-Name () = 'Events']/*[Local-Name () = 'Event']

6. Postman files

For your convenience, we have prepared a ready -made configuration file, which after importing to the postman application will allow you to quickly test methods asking for shipping status.

This application has variables {username}, {password}, ​​which, when you have dedicated login data, enter accordingly in the VARIABLES .

Here is the configuration file: Download the file

7. Shared events

Below is a list of events returned and presented in the tracking system together with their Polish and English translation.

In integration, the event codes should be mapped (e.g. p_nad, p_d) and not the name of the event codes, because the names may change.

Download file (pdf): download file

Information

Please be advised that Poczta Polska introduces additional security as part of the Dora and NIS2 directives. One of the security is to disable access to the network traffic for SSL/TLS protocols in versions 1.0 and 1.1 for systems located at: USS.Poczta-polska.pl, tt.poczta-polska.pl, Ws.poczta-polska.pl eag.poczta-polska.pl for REST API and WSDL/SOAP environments.

Those of you who are still using the abovementioned protocol are asked to modify in their systems for the min TLS 1.2 versions by 10.04.2025.

After this day, communication using the TLS 1.0 and TLS 1.1 protocols will be impossible, which may cause no communication with our tracking systems.

Application for creating an WSDL/SOAP account

* compulsory fields

Technical data

Please Enter a Number from 1 is 500 .
0 of 100 max characters

Contact details

0 of 500 max characters
Email address for contact*
0 of 500 max characters
Contact details*
Consent required GDPR*

Rewrite the code from the picture (the size of the characters does not matter)

Captcha code
0 of 10 max characters
This Field is for Validation Purposes and Should Be Left Unchanged.
English