B2BZasilka nAPI České pošty

Technická dokumentace

Stažení yaml - technické dokumentace: B2B-ZSKService.

Jsou zde uvedeny příklady odpovědí, typy jednotlivých atributů a jejich omezení

Práce s API klíčem

Získání API klíče

Produkční prostředí API je přístupné pouze pro smluvní zákazníky.

Pro získání přístupů k API je potřeba kontaktovat Vašeho obchodního manažera. Obchodní manažer Vám pomůže s registrací, počátečním nastavením a přidělí práva. Který je právě Váš se dozvíte zde: Obchodní manažeři.

Ke svému účtu se po získání přístupových údajů přihlásíte na stránkách Pošta Online. V záložce Služby pro firmy je přistup ke Správě B2B profilu, kde si můžete vytvářet a měnit klíče, kterými je potřeba zašifrovat request, jenž bude posílán na API.

K dispozici jsou také 4 testovací účty, na kterých si můžete vyzkoušet volání API. Údaje k ním jsou v kapitole Testovací účty.

Průvodce generováním API klíče

Po příchodu emailu s přihlašovacím jménom a SMS zprávy s přihlašovacím heslem se přihlašte na Pošta Online. Poté v záložce Služby pro firmy klikněte na Správa B2B profilu

 

Po kliku na Spravovat budete vyzváni ke vložení SMS kódu

 

Zobrazí se souhrn informací o Vašem účtu a můžete si generovat API klíče. Klíče se generují s datumem platnosti OD a mají platnost neomezenou, nebo do začátku platnosti nového klíče.


Api-Token

Autorizace a autentizace API klíčem, který je generován ve Správě profilu B2B. API klíč má zákazník prostřednictvím administračního rozhraní možnost zneplatnit a vystavit nový.

Příklad:
Api-Token: b79b16c2-2f77-450f-91a5-868c3c698a82
Security Scheme Type API Key
Header parameter name Api-Token

Authorization-Timestamp

Authorization-Timestamp je použito pro výpočet HMAC_SHA256_Auth. Systém externího partnera vygeneruje časové razítko ve formátu 'UTC UNIX Timestamp'.
Tato položka musí být připojena k hlavičce jako 'Authorization-Timestamp'.
Toto časové razítko nesmí být delší než čas 60 sekund, nemůže být v budoucnosti. Požadavek s neplatným časovým razítkem bude odmítnut s kódem odpovědi 403.

Příklad:
Authorization-Timestamp: 1593561601
Security Scheme Type API Key
Header parameter name Authorization-Timestamp

Authorization-content-SHA256

SHA256 těla požadavku. Systém externího partnera počítá hash SHA256 'requestBody' těla požadavku JSON.
Tento hash musí být připojen k hlavičce jako 'Authorization-Content-SHA256'.
V případě, že tento hash nesouhlasí s hashem těla v požadavku, bude požadavek odmítnut s kódem odpovědi 403.

Příklad:
Authorization-Content-SHA256: f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8
Security Scheme Type API Key
Header parameter name Authorization-Content-SHA256

HMAC_SHA256_Auth

HMAC_SHA256_Auth je tvořen pomocí nonce (náhodný řežezec) a signature. Pro požadavky je nutná autorizace tajného klíče. Tento tajný klíč je generován v uživatelské aplikaci, tajný klíč není součástí požadavku. Systém externího partnera generuje 'nonce' - ve formátu UUIDv4.

Signature se vytvoří jako hash HMAC256 těchto položek:
Authorization-Content-SHA256;Authorization-Timestamp;nonce
jako první parametr HMAC funkce a
secretKey
jako druhý.

Pokud požadavek nebude mít tělo (např. operace GET), je signature tvořen takto:
;Authorization-Timestamp;nonce
jako první parametr HMAC funkce a
secretKey
jako druhý.

Signature musí být v base64.

Příklad:
Authorization: CP-HMAC-SHA256 nonce="74b03ffb-34e1-419e-8c6f-f8275bad9a41" signature="QGBaYeY8loQZXbJRmj91JV2yTwsuBTME6wQhUrEm7mI="
Security Scheme Type API Key
Header parameter name Authorization

Content-Type

Je potřeba celý request kodovat v application/json;charset=UTF-8

Příklad tvorby hlaviček JavaScript

const secret = 'dOJWwjp+BWqUcof3K+3OW6XGTnEpmWerx64TCNk0+0pZnonHdN99NFRIGaJSX0/HTtiu6AGYpKp0mjguzqp+wg==';

//set unix timestamp
var moment = require('moment');
pm.environment.set("utc_unix_timestamp", moment().unix());
//console.log('utc_unix_timestamp: ' + pm.variables.get('utc_unix_timestamp'));

var nonce = "0d8873f8-6cf8-4075-88df-f3518c7df527"
//console.log('nonce: ' + nonce);
//0d8873f8-6cf8-4075-88df-f3518c7df527

var payload = pm.request.body.toString();
//console.log('payload : ' + payload);
pm.environment.set("sha256payload", CryptoJS.SHA256(payload).toString());
//console.log('sha256payload : ' + pm.variables.get('sha256payload').toString());

var hash = CryptoJS.HmacSHA256(pm.variables.get('sha256payload') + ';' + pm.variables.get('utc_unix_timestamp') + ';' + nonce, secret);
//console.log('nonceDolni : ' + nonce);
var hashBase64 = CryptoJS.enc.Base64.stringify(hash);

pm.environment.set("signature", hashBase64);
console.log('signature : ' + pm.variables.get('signature').toString());

API operace

Základní informace

Předání dat o zásilkách může být provedeno pomocí operace POST sendParcel (Asynchronní) a nebo pomocí POST parcelService (synchronní).

POST sendParcel je používáno pro větší dávky, je totiž přes tuto operaci možno zaslat informace až o 1000 zásilkách. Po zaslání dat přes operaci POST sendParcel dostane zákazník info zda byla dávka přijata ke zpracování a získá id transakce. Toto id je potřeba zaslat v requestu operace GET sendParcels, po které se dozvíte, zda byla dávka přijatá úspěšně nebo s chybou.

POST parcelService je používáno pro zaslání dat o jedné zásilce (pěti při využití služby 70 - vícekus). Při této operaci je možno zadat i id formuláře a rovnou si vytisknout také štítek.

Podací pošta

Klient musí mít nasmlouvané pošty (postCode) a pouze ty se mohou vkládat do reqeustů.

Vícekusá zásilka - služba 70

  • první zásilka je hlavní zásilka
  • zásilky ve vícekusu musí následovat v jednom requestu po sobě
  • u každé zásilky musí být uvedena služba 70
  • u každé zásilky se uvede element quantityParcel, který značí celkový počet zásilek vícekusu
  • u každé zásilky se uvede element sequenceParcel, který značí pořadí zásilky, to je například u první zásilky 1 ze tří, u druhé zásilky 2 ze tří, u třetí 3 ze tří. Vypisuje se pouze hodnota, čili 1 – 5.
  • u každé zásilky uvést její hmotnost a velikost
  • udanou cenu a dobírku vypsat pouze u hlavní zásilky
  • maximální počet zásilek ve vícekusu je 5

Zjištění nevyužitých čárových kódů

Aplikace pomáhá zjistit počet nevyužitých čárových kódu pro dané technologické číslo.

Balíkovny a pošty

Pokud zasíláte data na balíkovnu/poštu, je potřeba uvést příslušny prefix zásilky (NB/NP) a do adresy příjemce vložit PSČ dané Balíkovny/pošty a do parametru street vložit údaj Balíkovna/Na poštu. Každá Balíkovna/pošta má své jedinečné PSČ, dle kterého poznáme, kam má být zásilka doručena.

http://napostu.ceskaposta.cz/vystupy/balikovny.xml

http://napostu.ceskaposta.cz/vystupy/napostu.xml

Seznam chybových hlášek

Přehled chybových hlášek
responseCode responseString responseText CHYBA / INFO
1 OK Vše v pořádku INFO
2 INTERNAL_APPLICATION_ERROR Interní chyba aplikace CHYBA
3 UNAUTHORIZED_ACCESS Login není evidován k uvedenému číslu podavatele CHYBA
10 INVALID_CUSTOMER_ID Neplatné technologické čislo CHYBA
11 INVALID_LOCATION Neplatné podací místo CHYBA
12 INVALID_POST_CODE Neplatné PSČ podací pošty CHYBA
13 INVALID_TRANSMISSION_DATE Chybné datum podání (menší než aktuální datum) CHYBA
14 TRANSMISSION_OPENED Podání otevřeno CHYBA
15 TRANSMISSION_CLOSED Podání již bylo uzavřeno CHYBA
16 TRANSMISSION_UNFINISHED Zpracování ješte není ukončeno CHYBA
17 BATCH_CLOSED Dávka uzavřena CHYBA
18 BATCH_UNFINISHED Zpracování ješte není ukončeno CHYBA
19 BATCH_INVALID V dávce se vyskytují chybné záznamy CHYBA
20 TRANSMISSION_NOT_EXISTS Podání neexistuje CHYBA
21 PARTIALLY_ACCEPTED Částečně přijato INFO
100 INVALID_PARCEL_CODE Neplatné ID zásilky CHYBA
101 DUPLICATE_PARCEL_CODE Duplicitní ID zásilky v rámci 13-ti měsíců CHYBA
102 FULL_SEQUENCE Vyčerpaná řada podacích čísel CHYBA
103 INVALID_PREFIX Neznámý typ zásilky CHYBA
104 INVALID_WEIGHT Hmotnost mimo povolený rozsah CHYBA
105 INVALID_PRICE Udaná cena mimo povolený rozsah CHYBA
106 INVALID_AMOUNT Dobírka mimo povolený rozsah CHYBA
107 INVALID_CURRENCY Neplatná měna dobírkové částky CHYBA
108 MISSING_VS Neuveden variabilní symbol poukázky CHYBA
109 INVALID_WIDTH Šířka mimo povolený rozsah CHYBA
110 INVALID_HEIGHT Výška mimo povolený rozsah CHYBA
111 INVALID_LENGTH Délka mimo povolený rozsah CHYBA
112 ILLEGAL_COMBINATION_SERVICE Nepovolená kombinace doplňkových služeb CHYBA
113 MISSING_REQUIRED_SERVICE Neuvedena alespoň jedna povinná doplňková služba CHYBA
114 MISSING_SURNAME Neuvedeno příjmení fyzické osoby CHYBA
115 MISSING_COMPANY_NAME Neuveden název právnické osoby CHYBA
116 UNKNOWN_CITY Neznámá obec adresáta CHYBA
117 UNKNOWN_ZIP_CODE Neznámé PSČ adresáta CHYBA
118 MISSING_PHONE_NUMBER Neuvedeno telefonní číslo CHYBA
119 INVALID_ADRESS Adresa odesílatele není vhodná pro produkt Nadrozměrná zásilka (adresa obsahuje údaj P.O.Box nebo Poste restante) CHYBA
120 INVALID_DENSITY Objemová hmotnost mimo povolený rozsah CHYBA
121 BAD_WEIGHT Hmotnost není číslo CHYBA
122 BAD_PRICE Udaná cena není číslo CHYBA
123 BAD_AMOUNT Dobírka není číslo CHYBA
124 MISSING_AMOUNT Neuvedena částka dobírky CHYBA
125 MISSING_REQUIRED_SERVICE 20/22/1U Neuvedena povinná služba 20 ani 22 ani 1U CHYBA
126 MISSING_REQUIRED_SERVICE 37/38 Neuvedena povinná služba 37 ani 38 CHYBA
127 MISSING_REQUIRED_SERVICE 42/43/44 Neuvedena povinná služba 42 ani 43 ani 44 CHYBA
128 MISSING_PREFIX Neuveden typ zásilky CHYBA
129 INVALID_WEIGHT_FOR_SERVICE_11 Hmotnost mimo povolený rozsah služby 11 CHYBA
130 MISSING_PRICE Neuvedena částka udané ceny CHYBA
131 MISSING_AMOUNT_TYPE Neuveden typ dobírky CHYBA
132 BAD_VS Variabilní symbol poukázky není číslo CHYBA
133 BAD_WIDTH Šířka není celé číslo CHYBA
134 BAD_HEIGHT Výška není celé číslo CHYBA
135 BAD_LENGTH Délka není celé číslo CHYBA
136 MISSING_REQUIRED_PHONE_NUMBER Není uveden povinný údaj - telefonní číslo adresáta CHYBA
137 BAD_PREFIX Zásilku tohoto typu nelze na uvedenou adresu odeslat CHYBA
138 MISSING_REQUIRED_PHONE_NUMBER_OR_EMAIL Není uveden povinný údaj - telefonní číslo nebo e-mail adresáta CHYBA
139 INVALID_ADRESS_FOR_AMOUNT_OVER_20000 Zásilku tohoto typu s dobírkou vetší než 20 000 Kč nelze na uvedenou adresu odeslat CHYBA
140 BAD_PREFIX Zásilku tohoto typu nelze na uvedenou adresu odeslat CHYBA
141 INVALID_ADRESS Adresa je vhodná pouze pro produkt Na poštu CHYBA
142 INVALID_ADRESS "Adresu nelze zvolit (adresa obsahuje údaj P.O.Box, Poste restante nebo Na poštu)" CHYBA
143 FULL_SEQUENCE Vyčerpaná řada podacích čísel CHYBA
144 DUPLICATE_PARCEL_CODE Duplicitní zásilka CHYBA
145 INVALID_PARCEL_CODE_CONTROL Nesouhlasí kontrolní číslo v ID zásilky CHYBA
146 MISSING_REQUIRED_MRN_CODE Neuveden MRN kód CHYBA
147 INVALID_MRN_CODE_CONTROL Neplatný kód MRN CHYBA
150 INVALID_ADRESS Adresa je vhodná pouze pro produkt Na poštu CHYBA
155 INVALID_ADRESS Adresát není vhodný pro produkt Nadrozměrná zásilka (nevyplněn mobil nebo telefon) CHYBA
156 MISSING_REQUIRED_SERVICE 14/19 Neuvedena povinná služba 14 CHYBA
159 MISSING_REQUIRED_PHONE_NUMBER Nevyplněn variabilní symbol zásilky CHYBA
160 INVALID_PARCEL_CODE Neuvedeno ID odpovědní zásilky CHYBA
161 INVALID_PARCEL_CODE Neuvedeno ID zásilky CHYBA
164 INVALID_PARCEL_CODE Nesouhlasí technologické číslo s ID zásilky CHYBA
165 BAD_ADDRESSEE Chybný adresát CHYBA
166 BAD_QUANTITY_PARCEL_NUMBER Nepovolený počet VK CHYBA
168 MISSING_HEIGHT Neuvedena výška CHYBA
169 MISSING_WIDTH Neuvedena šířka CHYBA
170 MISSING_LENGTH Neuvedena délka CHYBA
171 MISSING_PALETTS_NUMBER Počet palet mimo povolený rozsah CHYBA
173 INVALID_WEIGHT Součet fyzických hmotností celé vícekusové zásilky mimo povolený rozsah CHYBA
174 INVALID_DENSITY Součet objemových hmotností celé vícekusové zásilky mimo povolený rozsah CHYBA
176 INVALID_AMOUNT Napočtená dobírka u hlavní zásilky je nad povolený rozsah CHYBA
177 INVALID_AMOUNT "Limit pro uložení zásilky na Výdejním místě je pro Dobírku max. 50.000,- Kč. Zásilka bude uložena na poště, která je Výdejnímu místu nadřízená. " CHYBA
178 INVALID_PRICE "Limit pro uložení zásilky na Výdejním místě je pro Udanou cenu a Dobírku max. 50.000,- Kč. Zásilka bude uložena na poště, která je Výdejnímu místu nadřízená. " CHYBA
179 INVALID_PRICE_AND_AMOUNT "Limit pro uložení zásilky na Výdejním místě je pro Udanou cenu a Dobírku max. 50.000,- Kč. Zásilka bude uložena na poště, která je Výdejnímu místu nadřízená. " CHYBA
182 INVALID_PHONE_NUMBER Neplatný formát telefonního čísla CHYBA
183 INVALID_EMAIL Neplatný formát e-mailu CHYBA
184 INVALID_PHONE_NUMBER Neplatný formát telefonního čísla CHYBA
185 INVALID_EMAIL Neplatný formát e-mailu CHYBA
186 MISSING_REQUIRED_SERVICE 4 "Musí být vybraná služba ""Dobírka Pk A"" " CHYBA
187 INVALID_PREFIX Nepovolená kombinace doplňkových služeb CHYBA
188 MISSING_SENDER_EMAIL Neuveden povinný údaj e-mail odesílatele CHYBA
189 MISSING_REQUIRED_MOBIL_NUMBER Není uveden povinný údaj - telefonní číslo nebo mobil adresáta CHYBA
190 INVALID_SIGN_NUMBER Neuveden počet dokumentů určených k podpisu CHYBA
191 INVALID_SERVICE_36 Nepovolená kombinace adresy do Balíkomatu a služby 36 (Potvrzení dokumentace při dod.) CHYBA
192 INVALID_SERVICE_37 Nepovolená kombinace adresy do Balíkomatu a služby 37 (Ověření údajů při dod.) CHYBA
193 INVALID_SERVICE_38 Nepovolená kombinace adresy do Balíkomatu a služby 38 (Předání inf. z dod.) CHYBA
194 INVALID_ADDRESS_ADDRESSEE_DOCUMENT Zásilku tohoto typu nelze na uvedenou adresu adresáta dokumentů odeslat (obsahuje údaj Na poštu) CHYBA
195 MISSING_REQUIRED_ADDRESSEE_DOCUMENT Adresát dokumentů neuveden CHYBA
196 MISSING_REQUIRED_MOBIL_OR_EMAIL Není uveden povinný údaj - mobilní telefonní číslo nebo e-mail adresáta CHYBA
197 INVALID_ZPRO_ORDER_NUMBER Nesprávný formát čísla objednávky ZPRO CHYBA
198 INVALID_PARTNER_CODE Váš kód partnera neodpovídá zadanému kódu objednávky CHYBA
199 INVALID_ORDER_NUMBER Neexistující číslo objednávky CHYBA
200 INVALID_ORDER_NUMBER Objednávka s tímto číslem byla stornována CHYBA
201 INVALID_ORDER_NUMBER "K číslu objednávky již existuje přiřazená zásilka, číslo objednávky nelze použít " CHYBA
202 INVALID_AMOUNT Dobírková částka je vyšší než celková cena objednávky CHYBA
203 MISSING_REQUIRED_ZPRO_ORDER_NUMBER Neuvedeno číslo objednávky ZPRO CHYBA
204 INVALID_VS_PARCEL Variabilní symbol není číslo CHYBA
205 INVALID_PARCEL_CODE Zadané ID zásilky není v rozmezí vaší přidělené číselné řady CHYBA
206 MISSING_PARCEL_CUSTOM_GOODS Neuvedena data celní prohlášky CHYBA
207 MISSING_CATEGORY_CUSTOM_DECALARATION Neuvedena kategorie zásilky CHYBA
208 MISSING_CURRENCY_CUSTOM_DECALARATION Neuvedena měna celní hodnoty CHYBA
209 INVALID_QUANTITY_CUSTOM_GOOD Množství celního obsahu mimo povolený rozsah CHYBA
210 MISSING_QUANTITY_CUSTOM_GOOD Neuvedeno množství celního obsahu CHYBA
211 INVALID_WEIGHT_CUSTOM_GOOD Hmotnost celního obsahu mimo povolený rozsah CHYBA
212 MISSING_WEIGHT_CUSTOM_GOOD Neuvedena hmotnost celního obsahu CHYBA
213 MISSING_PRICE_CUSTOM_GOOD Neuvedena celní hodnota položky CHYBA
214 MISSING_ISO_CUSTOM_GOOD Neuvedena země původu zboží CHYBA
215 MISSING_HS_CODE_CUSTOM_GOOD Neuveden tarifní kód CHYBA
216 MISSING_CONTENT_CUSTOM_GOOD Neuveden popis obsahu zboží CHYBA
217 INVALID_PRICE_CURRENCY Nesouhlasí měna udané ceny CHYBA
218 INVALID_AMOUNT_CURRENCY Nesouhlasí měna dobírky CHYBA
219 MISSING_ADDRESSEE_ZIP_CODE PSČ adresáta musí být vyplněno CHYBA
220 MISSING_ADDRESSEE_CITY Obec adresáta musí být vyplněna CHYBA
221 INVALID_WEIGHT_CUSTOM_GOOD_SUMMARY Celková hmotnost zboží je vyšší než hmotnost uvedená u zásilky CHYBA
222 MISSING_PARCEL_CUSTOM_GOOD Neuvedena zásilka k položkám obsahu zboží CHYBA
223 INVALID_WEIGHT Váhové rozmezí je mimo povolený rozsah CHYBA
224 INVALID_ORDER_NUMBER "Číslo objednávky nelze použít, ještě nedošlo k jejímu odeslání " CHYBA
225 INVALID_PREFIX Nesouhlasí typ zásilky s typem produktu dané dávky CHYBA
226 INVALID_CONTENT_CUSTOM_GOOD Celní hodnota položky je mimo povolený rozsah CHYBA
227 INVALID_CUSTOM_GOOD_NUMBER Počet položek celního obsahu mimo povolený rozsah CHYBA
228 MISSING_REQUIRED_VOUCHER_PRICE Neuvedena částka CHYBA
230 MISSING_REQUIRED_PAYDAY Termín výplaty není uveden CHYBA
231 INVALID_PAYDAY Termín výplaty je mimo povolené rozmezí 365 dní CHYBA
232 INVALID_PAYDAY Termín výplaty není platné datum CHYBA
240 MISSING_REQUIRED_SERVICE 3/32/33 Neuvedena povinná služba 3 ani 32 ani 33 CHYBA
241 MISSING_REQUIRED_SERVICE_10 Neuvedena služba 10 CHYBA
242 MISSING_REQUIRED_SERVICE 1A/1B Neuvedena povinná služba 1A ani 1B CHYBA
243 MISSING_REQUIRED_SERVICE Neuvedeny dispozice pro nakládání se zásilkou CHYBA
243 MISSING_REQUIRED_SERVICE Neuveden způsob vrácení zásilky (ekonom./let.) CHYBA
245 MISSING_RETURN_NUMBER_DAYS Neuveden počet dní pro vrácení zásilky CHYBA
246 INVALID_RETURN_NUMBER_DAYS Počet dní pro vrácení zásilky mimo povolený rozsah CHYBA
247 INVALID_ADRESS Nepovolená provozovna pro adresu typu Balíkovna CHYBA
248 INVALID_ADRESS Adresa je vhodná pouze pro produkt balík do Balíkovny CHYBA
250 MISSING_REQUIRED_EMAIL Není uveden povinný údaj e-mail adresáta CHYBA
252 MISSING_REQUIRED_FIRST_NAME_ADDRESSEE_DOCUMENT Neuvedeno jméno adresáta dokumentů CHYBA
253 INFO_INEXACT_ADDRESS Nepřesná (nejednoznačná) adresa INFO
254 INVALID_PARCEL_CODE Chybné ID čárového kódu CHYBA
255 INVALID_PARCEL_CODE Chybné ID čárového kódu CHYBA
256 DUPLICATE_PARCEL_CODE Duplicitní ID čárového kódu CHYBA
257 INVALID_ADRESS Adresa je vhodná pouze pro vnitrostátní zásilky CHYBA
258 MISSING_VS Nevyplněn variabilní symbol CHYBA
259 MISSING_ADDRESSEE_CITY Není uveden povinný údaj - město adresáta CHYBA
260 MISSING_ADDRESSEE_STREET Není uveden povinný údaj – ulice adresáta CHYBA
261 MISSING_SIZE_CATEGORY Neuvedena rozměrová kategorie zásilky CHYBA
262 INVALID_PRICE Udaná cena mimo povolený rozsah CHYBA
263 INFO_SPECIAL_PACKAGING_REQUEST Pozor – požadavek na speciální balení zásilky INFO
264 INVALID_PRICE Službu Cenný obsah je možné zvolit až od 10 tis. Kč CHYBA
265 INVALID_WEIGHT_CUSTOM_GOOD_SUMMARY Celková hmotnost zboží je vyšší než hmotnost uvedená u zásilky CHYBA
266 INVALID_HS_CODE_CUSTOM_GOOD Nesprávný formát tarifního kódu CHYBA
267 MISSING_REQUIRED_SERVICE_4/5/41 K dobírkové částce neuvedena dopl. sl. Dobírka CHYBA
268 MISSING_AMOUNT K dopl. sl. Dobírka neuvedena dobírková částka CHYBA
269 MRN_CODE_ALREADY_USED MRN již bylo použito CHYBA
275 INVALID_MASTER_PARCEL_CODE_CONTROL Nesouhlasí kontrolní číslo v ID řídící zásilky CHYBA
276 INVALID_MASTER_PARCEL_CODE Nesouhlasí technologické číslo s ID řídící zásilky CHYBA
277 MISSING_MASTER_PARCEL_CODE Neuvedeno ID řídící zásilky CHYBA
278 MISSING_PARCEL_CODE Neuvedeno ID zásilky CHYBA
279 MISSING_SEQUENCE Neuvedeno pořadí zásilky v rámci VK III CHYBA
280 MISSING_QUANTITY Neuveden celkový počet zásilek v rámci VK III CHYBA
281 INVALID_PARCEL/MASTER_CODE Nesouhlasí ID zásilky s ID řídící zásilky CHYBA
282 INVALID_BANK_CODE Neplatný kód banky CHYBA
283 INVALID_BANK_ACCOUNT Chybný účet nebo předčíslí CHYBA
284 MISSING_REQUIRED_SERVICE 3/32/33/44 Neuvedena povinná služba 3 ani 32 ani 33 ani 44 CHYBA
285 MISSING_REQUIRED_SERVICE 20/22 Neuvedena povinná služba 20 ani 22 CHYBA
300 MISSING_ADDRESSEE Adresát neuveden CHYBA
301 INFO_CITY_CHANGED "V adrese byl upraven údaj ""obec"" dle zadaného psč " INFO
302 MISSING_ADDRESS Nepovolená kombinace adresy a subjektu CHYBA
303 INFO_INVALID_BIRTH_DAY Neplatný formát data narození INFO
304 INFO_INVALID_MOBIL_NUMBER Mobil - neplatné telefonní číslo INFO
305 INFO_INVALID_TELEPHONE_NUMBER Telefon - neplatné telefonní číslo INFO
306 INFO_INVALID_PREFIX_ACCOUNT Předčíslí není číslo INFO
307 INFO_INVALID_ACCOUNT Účet není číslo INFO
308 INFO_INVALID_BANK_CODE Banka není číslo INFO
309 INVALID_ADDRESS Chybná adresa - neexistující PSČ nebo obec CHYBA
310 INVALID_PREFIX Neplatný typ zásilky CHYBA
311 INVALID_PREFIX Nesouhlasí typ zásilky s ID zásilky CHYBA
312 INFO_CANCEL_SERVICE_29 Zrušena služba 29 - nepovolená služba pro typ adresy Poste restante /P.O:Box INFO
313 INFO_INVALID_WEIGHT Hmotnost není číslo INFO
314 INFO_INVALID_PRICE Udaná cena není číslo INFO
315 INFO_INVALID_AMOUNT Dobírka není číslo INFO
316 INVALID_AMOUNT_CURRENCY Nesouhlasí měna dobírkove částky CHYBA
317 INFO_INVALID_SPEC_SYMBOL Specifický symbol není číslo INFO
318 INFO_CANCEL_SERVICE_27 Zrušena služba 27 - nepovolená služba pro adresáta s PSČ Výdejního místa INFO
319 INVALID_SERVICE_18 Nepovolená kombinace adresy a služby Doruč v So CHYBA
320 INVALID_SERVICE_19 Nepovolená kombinace adresy a služby Doruč v Ne/sv CHYBA
321 INFO_CANCEL_SERVICE_30 "Zrušena služba 30 - nepovolená služba u produktu Balík Do ruky nad 31,5 kg " INFO
322 INFO_CANCEL_SERVICE_31 "Zrušena služba 31 - nepovolená služba u produktu Balík Do ruky nad 31,5 kg " INFO
323 INFO_CANCEL_SERVICE_47 "Zrušena služba 47 - nepovolená služba u produktu Balík Do ruky do 31,5 kg " INFO
324 INFO_SERVICE_29+47 "Zásilku s výškou nad 150cm nelze podat jako Balík Do ruky se sl.47, ale musí být využit Balík Nadrozměr v kategorii NZ 2 " INFO
325 INFO_CANCEL_SERVICE_34 Zrušena služba 34 - nesprávný formát telefonního čísla INFO
326 INFO_CANCEL_SERVICE_45 Zrušena služba 45 - nesprávný formát telefonního čísla nebo emailu INFO
327 MISSING_REQUIRED_EMAIL Není uveden povinný údaj e-mail adresáta CHYBA
328 INFO_CANCEL_SERVICE_25 Zrušena služba 25 - neuvedena povinná služba 24 k této službě INFO
329 MISSING_REQUIRED_PARCEL_CODE Neuvedeno ID zásilky CHYBA
330 INVALID_PARCEL_CODE Nepovolené ID zásilky CHYBA
331 MISSING_PALETTS_NUMBER Neuveden počet palet CHYBA
332 INFO_CANCEL_PALETTS_NUMBER Počet palet není celé číslo INFO
333 INFO_CANCEL_WIDTH Šířka není celé číslo INFO
334 INFO_CANCEL_HEIGHT Výška není celé číslo INFO
335 INFO_CANCEL_LENGTH Délka není celé číslo INFO
336 MISSING_REQUIRED_PRICE Neuvedena částka udané ceny CHYBA
337 INVALID_AMOUNT_TYPE Neuveden typ dobírky CHYBA
338 INFO_CANCEL_VS_VOUCHER Variabilní symbol poukázky není číslo INFO
339 INVALID_SERVICE_COMBINATION Nepovolená kombinace doplňkových služeb CHYBA
340 INVALID_MRN_CODE Neplatný kód MRN CHYBA
341 INFO_CANCEL_SERVICE_34 Zrušena služba 34 - nesprávný formát telefonního čísla INFO
342 INFO_CANCEL_SERVICE_46 Zrušena služba 46 - nesprávný formát e-mailu INFO
343 INFO_CANCEL_SERVICE_45 Zrušena služba 45 - nesprávný formát telefonního čísla nebo e-mailu INFO
344 MISSING_REQUIRED_ADDRESSEE_DOCUMENT Adresát dokumentů neuveden CHYBA
345 INVALID_ADDRESS_ADDRESSEE_DOCUMENT Chybná adresa adresáta dokumentů - neexistující PSČ nebo obec CHYBA
346 INVALID_ADDRESS_ADDRESSEE_DOCUMENT Nepřesná adresa adresáta dokumentů - nenalezen objekt CHYBA
347 INF0_CANCEL_MOBIL_OR_EMAIL_ADDRESSEE_DOCUMENT Mobil - neplatné telefonní číslo nebo e-mail adresáta dokumentů INFO
348 INFO_CANCEL_CUST_CARD_NUMBER Nesprávný formát zákaznické karty INFO
349 INFO_CANCEL_CUST_CARD_NUMBER_ADDRESSEE_DOCUMENT Nesprávný formát zákaznické karty adresáta dokumentů INFO
350 INVALID_ZPRO_ORDER_NUMBER Nesprávný formát čísla objednávky ZPRO CHYBA
351 INFO_ADD_REQUIRED_SERVICE_75 Doplněna povinná služba 75 k číslu objednávky ZPRO INFO
352 INVALID_PRICE_CURRENCY Nesouhlasí měna udané ceny CHYBA
353 INVALID_CATEGORY_CUSTOM_DECALARATION Nesprávný formát kategorie zásilky CHYBA
354 INVALID_CURRENCY_CUSTOM_DECALARATION Nesprávný formát měny celní hodnoty CHYBA
355 INVALID_QUANTITY_CUSTOM_GOOD Nesprávný formát množství celního obsahu CHYBA
356 INVALID_WEIGHT_CUSTOM_GOOD Nesprávný formát hmotnosti celního obsahu CHYBA
357 INVALID_PRICE_CUSTOM_GOOD Nesprávný formát hodnoty celní položky CHYBA
358 INVALID_ISO_CUSTOM_GOOD Neexistující země původu zboží CHYBA
359 INVALID_ISO_CUSTOM_GOOD Nesprávný formát země původu zboží CHYBA
360 INVALID_HS_CODE_CUSTOM_GOOD Nesprávný formát tarifního kódu CHYBA
361 MISSING_REQUIRED_SERVICE_43/44 Neuvedena povinná služba č. 43 nebo č. 44 k datům celní prohlášky CHYBA
362 INFO_CANCEL_PRICE Částka není číslo INFO
363 INFO_CANCEL_PRICE Příliš velká částka INFO
364 INFO_CANCEL_PERSONAL_IDENTIFICATION_NUMBER Neplatný formát rodného čísla INFO
365 INVALID_ADDRESSEE Chybný adresát CHYBA
366 INVALID_RESPONSIBLE_CONSIGNMENT_NUMBER "Hodnota ""počet odpovědních zásilek"" je mimo povolený rozsah " CHYBA
367 INVALID_RESPONSIBLE_CONSIGNMENT_NUMBER Nesprávný formát počtu odpovědních zásilek CHYBA
368 INVALID_RESPONSIBLE_CONSIGNMENT_NUMBER Počet odpovědních zásilek při vyplnění ID zásilky nelze importovat CHYBA
369 INFO_CANCEL_SERVICE_1A/1B Zrušena služba 1A/1B - nepovolená ke službě 40 INFO
370 INFO_CANCEL_SERVICE_1A Zrušena služba 1A – nepovolená ke službě 40 INFO
371 INFO_CANCEL_SERVICE_1B Zrušena služba 1B – nepovolena k PSČ adresáta INFO
372 INVALID_TARE_WEIGHT Hmotnost obalu je mimo povolený rozsah CHYBA
373 INVALID_NUMBER_CLOSURE Duplicitní číslo uzávěru CHYBA
374 INVALID_PARCEL_CODE Duplicitní ID zásilky v rámci souboru CHYBA
375 INVALID_TIMING Nesprávný předstih podání CHYBA
376 INFO_CANCEL_SERVICE_1A+1B Zrušena služba 1A a 1B - nepovolená kombinace doplňkových služeb INFO
377 INFO_CANCEL_SERVICE_1B Zrušena služba 1B INFO
378 INVALID_PREFIX_COMBINATION Zásilka je chybně přiřazena k ID tiskové šablony CHYBA
379 PARCEL_DOES_NOT_MEET_THE_REQUIREMENTS_FORM Parametry zásilky nesplňují podmínky požadovaného formuláře CHYBA
380 NO_CONTRACT_SERVICE_RETURN_RECEIPT K formuláři není sjednána smlouva ke službě Dodejka CHYBA
381 INFO_CANCEL_SERVICE_1B_ADD_SERVICE_1A "Služba 1B není povolena k PSČ adresáta, nahrazena službou 1A" INFO
382 INFO_CANCEL_SERVICE_1A Zrušena služba 1A – nepovolena k PSČ adresáta INFO
383 INVALID_CUSTOMER_CARD_NUMBER Chybné číslo zákaznické karty CHYBA
384 BAD_FORMAT_RETURN_NUMBER_DAYS Neplatný formát počtu dní pro vrácení zásilky CHYBA
385 INFO_ADD_SERVICE_1B Přiřazena služba 1B Doruč. 13-19 hod INFO
386 INFO_ADD_SERVICE_1A Přiřazena služba 1A Doruč. 8-14 hod INFO
387 INFO_CANCEL_SERVICE_1A Zrušena služba 1A Doruč. 8-14 hod - nepovolena se službou 1B INFO
388 INFO_CANCEL_SERVICE_1B Zrušena služba 1B Doruč. 13-19 hod - nepovolena se službou 1A INFO
389 INFO_CANCEL_SERVICE_1V Zrušena nepovolená služba 1V - Vrácení zboží INFO
390 INFO_ADDRESSEE_TO_LONG Adresát mimo rozsah 40 znaků pro přenos ke zpracování Pk B INFO
391 INFO_MISSING_PART_CITY_SERVICE_DELIVERY_ON_SUNDAY/HOLIDAY_MAY_NOT_BE_REALIZED Neuvedena část obce - sl. Gar. čas dodání v Ne/Sv nemusí být realizována INFO
392 NFO_CANCEL_SERVICE_9 Zrušena nepovolená služba 9 prioritně INFO
393 INFO_ADD_SERVICE_9 Přiřazena služba 9 prioritně INFO
394 INFO_CANCEL_SERVICE_1E Zrušena služba 1E - neuveden kontaktní údaj adresáta INFO
395 INFO_CANCEL_SERVICE_5B Zrušena služba 5B - neuveden kontaktní údaj adresáta INFO
396 INFO_CANCEL_SERVICE_5C Zrušena služba 5C - neuveden kontaktní údaj adresáta INFO
397 INFO_CANCEL_SERVICE_5D Zrušena služba 5D - neuveden kontaktní údaj adresáta INFO
398 INFO_CANCEL_SERVICE_5B_AND_5C Zrušena služba 5B a 5C - nepovolená kombinace doplňkových služeb INFO
399 INFO_CANCEL_SERVICE_5B_AND_5D Zrušena služba 5B a 5D - nepovolená kombinace doplňkových služeb INFO
400 INFO_CANCEL_SERVICE_5C_AND_5D Zrušena služba 5C a 5D - nepovolená kombinace doplňkových služeb INFO
401 INFO_INVALID_CATEGORY_CUSTOM_DECALARATION Uvedena nepovolená kategorie zásilky - nahrazena kategorií Dokumenty' INFO
402 INVALID_SUBISO_COUNTRY Neexistující nebo nesprávný členský stát CHYBA
403 NO_CONTRACT_SERVICE_41 Pro tech. číslo a produkt nesjednána služba bezdokladová dobírka CHYBA
404 INVALID_SERVICE_COMBINATION Nepovolená kombinace doplňkových služeb – rozměr zásilky CHYBA
405 INVALID_SERVICE_COMBINATION Nepovolená kombinace doplňkových služeb – rozměr zásilky a sl.11 (Křehce) CHYBA
406 INFO_ADD_SERVICE_1D Přiřazena služba 1D – cenný obsah INFO
407 INFO_CANCEL_SERVICE_1D Zrušena služba 1D INFO
408 INFO_ADDRESS_WAS_MODIFIED "Adresa není přesná, byla upravena" INFO
409 INVALID_ADDRESSE_ZIP_CODE Chybný formát PSČ adresáta CHYBA
410 INVALID_ADDRESSEE Nesouhlasí země určení s VDD CHYBA
411 INCORECT_NUMBER_OF_RECEIVED_PARCELS Nepořízeny všechny zásilky k VDD CHYBA
412 INFO_HS_CODE_WAS_MODIFIED Upraven tarifní kód na max. počet 6-ti znaků INFO
413 INVALID_CATEGORY_CUSTOM_DECALARATION Nepovolená kategorie zásilky – dárek – jde pouze o zboží/komodity zasílané mezi dvěma fyzickými osobami CHYBA
414 MISSING_DOCUMENT_TYPE Neuveden typ dokumentu CHYBA
415 DUPLICIT_DOCUMENT_TYPE Duplicitní typ dokumentu CHYBA
416 MISSING_LOCATION_NAME Název podacího místa musí být vyplněn CHYBA
417 INFO_INVALID_IC_FORMAT Nesprávný formát IČ INFO
418 INFO_INVALID_IC_FORMAT_ADDRESSEE_DOCUMENT Nesprávný formát IČ adresáta dokumentů INFO
419 INVALID_HS_CODE Neplatný tarifní kód CHYBA
420 INVALID_CONTENT_CUSTOM_GOOD Neplatný popis celního obsahu CHYBA
421 INFO_HS_CODE_WAS_MODIFIED Tarifní kód upraven dle popisu celního obsahu INFO
422 INFO_CONTENT_CUSTOM_GOOD_WAS_MODIFIED Popis celního obsahu upraven dle tarifního kódu INFO
423 INFO_NON_EXISTENT_ZIP_CODE_REPLACED Neexistující PSČ nahrazeno konstantou INFO
424 INFO_CANCEL_SERVICE_40 Zrušena služba 40 - neuveden kontaktní údaj adresáta INFO
425 INFO_CANCEL_SERVICE_29 Zrušena dopl. sl. 29 – neuveden kontaktní údaj INFO
426 INFO_CANCEL_SERVICE_40 Zrušena služba 40 – nepovolena se sl. 29 INFO
427 INFO_CANCEL_SERVICE_40 Zrušena služba 40 – zásilka Poste restante/P.O.Box INFO
428 INFO_CANCEL_SERVICE_7K Zrušena služba 7K - nesjednaná služba pro zákaznické řešení INFO
429 INFO_NOTIFICIATON_WAS_MODIFIED Služba avizování přiřazena dle kontaktních údajů INFO
430 INFO_ADDRESS_CHANGED adresní údaj Poštovní přihrádka nahrazen údajem P.O.Box INFO

 

POST: /sendParcels

Operace slouží k předání dat k zásilkám do dalšího zpracování. V případě, že zpracování proběhlo úspěšně, jsou data automaticky předána na podací poštu. Takto přijatá data k zásilkám je možno zobrazit i prostřednictvím web aplikace POL. Výstupem této operace je objekt AsyncResponse, který obsahuje jednoznačné ID (idTransaction) potřebné pro zjištění výsledku zpracování operace, toto ID se musí předat do operace GET sendParcels

Parametry requestu operace

Položka   Popis parametru Komentář
idContract   IDCČK klienta podavatele Posílá se jako parametr v URI. V případě, že není vyplněno, použije se IDCČK, jenž je přiřazeno k API tokenu. Není povinné, důležíté je pro agregátora
parcelHeader      
  transmissionDate Předpokládané datum podání Uvádí se pouze datum, např. 2022-03-05
  customerID Technologické číslo podavatele např.: M12345
  postCode PSČ podací pošty PSČ pošty, kde se bude provádět návoz zásilek. Pošty jsou předem nasmlouvané a zákazník nemůže podat zásilky na jinou poštu
  contractNumber Číslo zakázky Zákazník může mít s poštou sjednanou určitou zakázku, zde se uvadí její číslo
  senderAddress Adresa odesílatele Je doporučeno využít elementu locationNumber, aby nevznikly nesrovnalosti v adresách
  codAddress Adresa adresáta dobírkové částky Je doporučeno využít elementu locationNumber, aby nevznikly nesrovnalosti v adresách
  codBank Bankovní spojení adresáta dobírkové částky Také součástí locationNumber
  senderContacts Kontakní údaje odesílatele Také součástí locationNumber
  senderCustCardNum Číslo zákaznické karty odesílatele  
  locationNumber Číslo podacího místa Jedná se o číslo podacího místa, pod kterým chce provádět import – v případě využití této položky není třeba uvádět v requestu údaje senderAddress, codAddress, codBank, senderContacts. Lokace lze spravovat pomocí operací GET location, DELETE location, POST location. Číslování začíná od hodnoty 1.
  goodToAccept Indikace, zda mají být v případě výskytu chyby v datech korektní data přijata do zpracování. 1 - správná data k zásilkám přijata, špatná ignorována, zákazník musí opravit a zaslat pouze špatná data. 0 - pokud je v dávce minimálně jedna chyba, celá dávka se musí opravit a zaslat znovu
parcelDataList   Data zásilek  
parcelDataList.parcelParams   Parametry zásilky  
  recordID Unikátní ID záznamu Doporučujeme využít pro identifikaci případných chybových stavů u jednotlivých záznamů v případě generování ID zásilek aplikací
  parcelCode ID zásilky Pokud není uveden, tak ČP přiradí id zásilky a hlídá posloupnost řady
  prefixParcelCode Typ zásilky (prefix) Např. DR, NB, RR
  weight Hmotnost Udává se na setiny. Nad 31.5 je zásilka již Nadrozměr
  insuredValue Udaná cena Cena, na kterou se zásilka pojistí
  amount Dobírka Nutné zadat při službě 41 - Bezdokladová dobírka
  currency ISO kód měny dobírky Výchozí hodnota CZK
  vsVoucher Variabilní symbol - poukázka Nutné zadat při službě 41 - Bezdokladová dobírka
  vsParcel Variabilní symbol - zásilka  
  sequenceParcel Pořadí v rámci vícekusové zásilky Při vícekusu je nutné zadat u každé obsažené zásilky
  quantityParcel Celkový počet zásilek vícekusové zásilky Při vícekusu je nutné zadat u každé obsažené zásilky
  note Poznámka Interní poznámka
  notePrint Poznámka pro tisk Zobrazí se na štítku
  length Délka  
  width Šířka  
  height Výška  
  mrn Kód MRN Movement reference number
  referenceNumber Číslo jednací číslo jednací se používá v souvislosti se sl. Dodejka u RR zásilek
  returnNumDays Počet dní pro vrácení zásilky  
parcelDataList.parcelServices   Požadované doplňkové služby  
  Service Požadovaná doplňková služba  
parcelDataList.parcelAddress Adresát zásilky    
  recordID Interní označení adresáta  
  firstName Jméno  
  surname Příjmení  
  company Název společnosti  
  aditionAddress Doplňující informace k názvu adresáta Informace budou vytištěny na štítku
  subject Typ adresáta F - Fyzická osoba / P - Právnícká osoba
  address    
  address.street Ulice  
  address.houseNumber Číslo popisné  
  address.sequenceNumber Číslo orientační  
  address.cityPart Část obce  
  address.city Obec  
  address.zipCode PSČ  
  address.isoCountry ISO kód země  
  address.subIsoCountry ISO kód území  
  address.addressCode Kód adresního místa RUIAN  
  mobilNumber Mobil  
  phoneNumber Telefon  
  emailAddress Email  

Parametry response operace

Položka   Popis parametru Komentář
idTransaction   ID transakce (pro asynchronní volání)  

GET: /sendParcels/idTransaction/{idTransaction}

Operace slouží ke zjištění výsledku zpracování dat předaných prostřednictvím sendParcels.

Parametry requestu operace

Položka   Popis parametru Komentář
idTransaction   ID transakce přidělené B2B modulem (asynchronní volání)  

Parametry response operace

Položka   Popis parametru Komentář
ResultSendParcelsList   Seznam zpracovaných zásilek  
  recordNumber Unikátní ID záznamu  
  parcelCode ID (čárový kód) zásilky  
parcelStateResponse      
  responseCode Kód odpovědi  
  responseText Popis odpovědi  

GET: /sendParcels/stats

Operace slouží ke zjištěni statistických informací o datech předaných prostřednictvím operace sendParcels

Parametry requestu operace

Položka   Popis parametru Komentář
dateFrom   Datum od  
dateTo   Datum do  

Parametry response operace

Položka   Popis parametru Komentář
importAll   Celkový počet importů  
importErr   Počet chybných importů  
importOK   Počet přijatých importů  
parcels   Počet přijatých zásilek  

POST: /parcelPrinting

Operace slouží k získání adresních štítků.

Parametry requestu operace

Položka   Popis parametru Komentář
printingHeader      
  customerID Technologické číslo podavatele  
  contractNumber IDCČK zákazníka  
  idForm ID formuláře pro tisk štítku  
  shiftHorizontal Hodnota posunu doprava v mm  
  shiftVertical Hodnota posunu dolu v mm  
  position Hodnota pozice na A4  
printingData   Položkové údaje  

Parametry response operace

Položka   Popis parametru Komentář
printingHeaderResult      
printingHeader      
  customerID Technologické číslo podavatele  
  contractNumber IDCČK zákazníka  
  idForm ID formuláře pro tisk štítku  
  shiftHorizontal Hodnota posunu doprava v mm  
  shiftVertical Hodnota posunu dolu v mm  
  position Hodnota pozice  
printingStatusResponse      
  responseCode Kód odpovědi  
  responseText Popis odpovědi  
printingDataResult   Data štítku v base64 kódování  

POST: /parcelService

Provede validaci a zápis dat, připadně generovani adresního štítku k zásilce.

Parametry requestu operace

Položka   Popis parametru Komentář
idContract   IDCČK klienta podavatele Posílá se jako parametr v URI. V případě, že není vyplněno, použije se IDCČK, jenž je přiřazeno k API tokenu. Není povinné, důležíté je pro agregátora
parcelServiceHeader      
parcelServiceHeader.parcelServiceHeaderCom      
  transmissionDate Předpokládané datum podání Uvádí se pouze datum, např. 2022-03-05
  customerID Technologické číslo podavatele např.: M12345
  postCode PSČ podací pošty PSČ pošty, kde se bude provádět návoz zásilek. Pošty jsou předem nasmlouvané a zákazník nemůže podat zásilky na jinou poštu
  contractNumber Číslo zakázky Zákazník může mít s poštou sjednanou určitou zakázku, zde se uvadí její číslo
  senderCustCardNum Číslo zákaznické karty odesílatele  
  locationNumber Číslo podacího místa Jedná se o číslo podacího místa, pod kterým chce provádět import
parcelServiceHeader.printParams   parametry pro tisk štítku  
  idForm ID formuláře pro tisk štítku  
  shiftHorizontal Hodnota posunu doprava v mm  
  shiftVertical Hodnota posunu dolu v mm  
parcelServiceHeader.position   Hodnota pozice na A4  
parcelServiceData   Data zásilek  
parcelServiceData.parcelParams   Parametry zásilky  
  recordID Unikátní ID záznamu Doporučujeme využít pro identifikaci případných chybových stavů u jednotlivých záznamů v případě generování ID zásilek aplikací
  parcelCode ID zásilky Pokud není uveden, tak ČP přiradí id zásilky a hlídá posloupnost řady
  prefixParcelCode Typ zásilky (prefix) Např. DR, NB, RR
  weight Hmotnost Udává se na setiny. Nad 31.5 je zásilka již Nadrozměr
  insuredValue Udaná cena Cena, na kterou se zásilka pojistí
  amount Dobírka Nutné zadat při službě 41 - Bedokladová dobírka
  currency ISO kód měny dobírky Výchozí hodnota CZK
  vsVoucher Variabilní symbol - poukázka Nutné zadat při službě 41 - Bedokladová dobírka
  vsParcel Variabilní symbol - zásilka  
  sequenceParcel Pořadí v rámci vícekusové zásilky Při vícekusu je nutné zadat u každé obsažené zásilky
  quantityParcel Celkový počet zásilek vícekusové zásilky Při vícekusu je nutné zadat u každé obsažené zásilky
  note Poznámka Interní poznámka
  notePrint Poznámka pro tisk Zobrazí se na štítku
  length Délka  
  width Šířka  
  height Výška  
  mrn Kód MRN movement reference number
  referenceNumber Číslo jednací číslo jednací se používá v souvislosti se sl. Dodejka u RR zásilek
  returnNumDays Počet dní pro vrácení zásilky  
parcelServiceData.parcelServices   Požadované doplňkové služby  
  Služby se vypisují do pole Požadovaná doplňková služba  
parcelServiceData.parcelAddress Adresát zásilky    
  recordID Interní označení adresáta  
  firstName Jméno  
  surname Příjmení  
  company Název společnosti  
  aditionAddress Doplňující informace k názvu adresáta Informace budou vytištěny na štítku
  subject Typ adresáta F - Fyzická osoba / P - Právnícká osoba
  address    
  address.street Ulice  
  address.houseNumber Číslo popisné  
  address.sequenceNumber Číslo orientační  
  address.cityPart Část obce  
  address.city Obec  
  address.zipCode PSČ  
  address.isoCountry ISO kód země  
  address.subIsoCountry ISO kód území  
  address.addressCode Kód adresního místa RUIAN  
  mobilNumber Mobil  
  phoneNumber Telefon  
  emailAddress Email  
multipartParcelData Přidružené zásilky    
multipartParcelData.addParcelData Data přidružených zásilek    
  recordID Email  
  prefixParcelCode Email  
  weight Email  
  sequenceParcel Email  
  quantityParcel Email  
multipartParcelData.addParcelDataServices Služby přidružených zásilek    

Parametry response operace

Položka   Popis parametru Komentář
responseHeader      
responseHeader.resultHeader      
  responseCode Kód odpovědi  
  responseText Popis odpovědi  
responseHeader.resultParcelData      
  recordNumber Unikátní ID záznamu  
  parcelCode ID zásilky  
  parcelStateResponse    
  parcelStateResponse.responseCode Kód odpovědi  
  parcelStateResponse.responseText Popis odpovědi  

POST: /parcelStatus

Operace slouží k získání seznamu stavu zásilek.

Je možno se v jednom requestu zeptat až na deset zásilek.

Parametry requestu operace

Položka   Popis parametru Komentář
parcelIds   ID (čárový kód) zásilky Je možno zadat až deset zásilek
language   Jazyk zobrazovaných událostí  

Parametry response operace

Položka   Popis parametru Komentář
idParcel   ID (čárový kód) zásilky  
parcelType   Typ zásilky(prefix)  
weight   Hmotnost  
amount   Dobirka  
currency   ISO kód měny dobírky  
parcelsQuantity   Množství  
depositTo   Datum uložení do  
timeDeposit   Úložní doba  
countryOfOrigin   Země původu  
countryOfDestination   Země určení  
parcelStatuses      
  id ID stavu  
  date Datum načtení stavu  
  text Text stavu  
  postCode PSČ kde stav nastal  
  name Název provozovny kde stav nastal  

GET: /parcelDataHistory/idContract/{idContract}/parcelID/{parcelID}:

Získání historie zásilky

Parametry requestu operace

Položka   Popis parametru Komentář
idContract   ID_CCK podavatele (idContract)  
parcelID   Čárový kód zásilky  

Parametry response operace

Položka   Popis parametru Komentář
parcelCode   ID (čárový kód) zásilky  
customerID   Technologické číslo podavatele  
name   Jméno  
surname   Příjmení  
company   Název společnosti  
aditionAddress   Doplňující informace k názvu adresáta  
address      
  street Ulice  
  houseNumber Číslo popisné  
  sequenceNumber Číslo orientační  
  cityPart Část obce  
  city Obec  
  zipCode PSČ  
  isoCountry ISO kód země  
  subIsoCountry ISO kód území  
  addressCode Kód adresního místa RUIAN  
cashOnDelivery   Dobírka  
insuredValue   Udaná cena  
weight   Váha  
services   Doplňkové služby  
vsVoucher   Variabilní symbol - poukázka  
vsParcel   Variabilní symbol - zásilka  
currency   ISO kód měny dobírky  
height   Výška  
width   Šířka  
lenght   Délka  
volumeWeight   Objemová hmotnost  
payoutAmount   Výplatní částka  
payoutAmountSum   Součet výplatného vícekusové zásilky  
sumWeight   Součet hmotnosti vícekusu  
masterCode   ID řídící zásilky pro zákaznícké služby  
sequenceParcel   Pořadí v rámci vícekusové zásilky  
quantityParcel   Celkový počet zásilek vícekusové zásilky  
creditedData   Email  
  deliveryPostCode PSČ dodací pošty, která vyplatila dobírku  
  deliveryPostOfficeName Název dodací pošty  
  paymentDate Den vyplacení dobírky na dodací poště  
  serialSubnumber Podčíslo podacího čísla  
  transactionDate Datum převodu  
senderCustCardNum   Číslo zákaznické karty  

POST: /letterWithCN22

Ukládá data podaných zásilek pro OLZ. Asynchronní.

Parametry requestu operace

Položka   Popis parametru Komentář
idContract   IDCČK klienta podavatele Posílá se jako parametr v URI. V případě, že není vyplněno, použije se IDCČK, jenž je přiřazeno k API tokenu. Není povinné, důležíté je pro agregátora
letterHeader      
  transmissionDate Předpokládané datum podání Uvádí se pouze datum, např. 2022-03-05
  customerID Technologické číslo podavatele  
  postCode PSČ podací pošty  
  contractNumber Číslo zakázky Zákazník může mít s poštou sjednanou určitou zakázku, zde se uvadí její číslo
  frankingNumber Číslo výplatního stroje  
  senderCustCardNum Číslo zákaznické karty  
  locationNumber Číslo podacího místa Jedná se o číslo podacího místa, pod kterým chce provádět import
letterData   Data k zasilkam  
letterData.letterParams   Parametry zásilky  
  recordID Unikátní ID záznamu Doporučujeme využít pro identifikaci případných chybových stavů u jednotlivých záznamů v případě generování ID zásilek aplikací
  parcelCode ID zásilky  
  weight Hmotnost  
  note Poznámka  
  note2 Poznámka  
  letterParams.letterServices Požadované doplňkové služby  
  Služby se vypisují do pole Požadovaná doplňková službá  
letterAddress   Adresa příjemce  
letterAddress.title   Informace o příjemci  
  recordID Interní označení adresáta  
  firstName Jméno  
  surname Příjmení  
  company Název společnosti  
  aditionAddress Doplňující informace k názvu adresáta  
  subject Typ adresáta F - Fyzická osoba / P - Právnícká osoba
  ic IČO - identifikační číslo ekonomických subjektů  
  dic DIČ - daňové identifikační číslo  
  specification Specifikace, např. datum narození  
letterAddress.address   Adresa příjemce  
  street Ulice  
  houseNumber Číslo popisné  
  sequenceNumber Číslo orientační  
  cityPart Část obce  
  city Obec  
  zipCode PSČ  
  isoCountry ISO kód země  
  subIsoCountry ISO kód území  
  addressCode Kód adresního místa RUIAN  
letterAddress.bank   Bankovní spojení adresáta  
  prefixAccount Předčíslí účtu  
  account Account number  
  bank Kód banky  
letterAddress.contact   Kontaktní údaje  
  mobilNumber Mobilní číslo  
  phoneNumber Telefonní číslo  
  emailAddress Email  
letterAddress.custCardNum   Číslo zákaznické karty  
letterAddress.adviceInfo      
  adviceInformationsList Informace číslo x k dodejce  
  adviceNote Poznámka k dodejce  
letterCustomsDeclaration      
  category Kategorie zásilky  
  note Poznámka  
  customValCur ISO kód měny celní hodnoty  
  importerRefNum Číslo dovozce  
  customGoods    
  customGoods.sequence Pořadí  
  customGoods.customCont Popis zboží  
  customGoods.quantity Množství  
  customGoods.weight Hmotnost  
  customGoods.customVal Celní hodnota  
  customGoods.hsCode HS kód  
  customGoods.iso Země původu zboží  

Parametry response operace

Položka   Popis parametru Komentář
idTransaction   ID transakce přidělené B2B modulem (asynchronní volání)  

GET: /letterWithCN22/idTransaction/{idTransaction}

Operace slouží ke zjištění výsledku zpracování dat předaných prostřednictvím operace letterWithCN22

Parametry requestu operace

Položka   Popis parametru Komentář
idTransaction   ID transakce přidělené B2B modulem (asynchronní volání)  

Parametry response operace

Položka   Popis parametru Komentář
parcelParamsResult      
  recordNumber ID transakce přidělené B2B modulem (asynchronní volání)  
  parcelCode ID transakce přidělené B2B modulem (asynchronní volání)  
parcelStateResponse   ID transakce přidělené B2B modulem (asynchronní volání)  
  responseCode Kód odpovědi  
  responseText Popis odpovědi  

GET: /location/idContract/{idContract}

Vypíše seznam podacích míst, adres, bankovních spojení a kontaktů. Tato podací místa jsou využívána v operacích sendParcel a parcelService v parametru locationNumber.

Parametry requestu operace

Položka   Popis parametru Komentář
idContract   ID CČK složky podavatele  

Parametry response operace

Položka   Popis parametru Komentář
locationNumber   Číslo podacího místa Jedná se o číslo podacího místa, pod kterým chce provádět import – v případě využití této položky v requestech není třeba uvádět v requestu údaje senderAddress, codAddress, codBank, senderContacts
location   Údaje o lokaci  
  locationName Název lokace Jedná se o pojmenování podacího místa odesilatele
  locationNameAddOn Doplněk názvu lokace  
  senderAddress Adresa odesílatele  
  companyName Název společnosti  
  aditionAddress Doplňující informace k názvu adresáta  
  street Ulice  
  houseNumber Číslo popisné  
  sequenceNumber Číslo orientační  
  cityPart Část obce  
  city Obec  
  zipCode PSČ  
  isoCountry ISO kód země  
  subIsoCountry ISO kód území  
  addressCode Kód adresního místa RUIAN  
codAddress   Adresa adresáta dobírkové částky  
  companyName Název společnosti  
  aditionAddress Doplňující informace k názvu adresáta  
  street Ulice  
  houseNumber Číslo popisné  
  sequenceNumber Číslo orientační  
  cityPart Část obce  
  city Obec  
  zipCode PSČ  
  isoCountry ISO kód země  
  subIsoCountry ISO kód území  
  addressCode Kód adresního místa RUIAN  
codBank   Bankovní spojení adresáta dobírkové částky  
  prefixAccount Předčíslí účtu  
  account Číslo účtu  
  bank Kód banky  
senderContacts   Kontakní údaje odesílatele  
  mobilNumber Mobilní číslo  
  phoneNumber Telefonní číslo  
  emailAddress Email  

DELETE: /location/idContract/{idContract}

Zruší dané podací místo včetně adres, bankovních spojení a kontaktů

Parametry requestu operace

Položka   Popis parametru Komentář
idContract   ID CČK složky podavatele  

Parametry response operace

Položka   Popis parametru Komentář
LocationDeleteResponse   0 Výsledek metody delete pro výmaz podacího místa

POST: /location/idContract/{idContract}

Uloží podací místo včetně adres, bankovních spojení a kontaktů. Tato podací místa jsou využívána v operacích sendParcel a parcelService v parametru locationNumber.

Parametry requestu operace

Položka   Popis parametru Komentář
locationName   Název lokace Jedná se o pojmenování podacího místa odesilatele
locationNameAddOn   Doplněk názvu lokace  
senderAddress   Adresa odesílatele  
  companyName Název společnosti  
  aditionAddress Doplňující informace k názvu adresáta  
  street Ulice  
  houseNumber Číslo popisné  
  sequenceNumber Číslo orientační  
  cityPart Část obce  
  city Obec  
  zipCode PSČ  
  isoCountry ISO kód země  
  subIsoCountry ISO kód území  
  addressCode Kód adresního místa RUIAN  
codAddress   Adresa adresáta dobírkové částky  
  companyName Název společnosti  
  aditionAddress Doplňující informace k názvu adresáta  
  street Ulice  
  houseNumber Číslo popisné  
  sequenceNumber Číslo orientační  
  cityPart Část obce  
  city Obec  
  zipCode PSČ  
  isoCountry ISO kód země  
  subIsoCountry ISO kód území  
  addressCode Kód adresního místa RUIAN  
codBank   Bankovní spojení adresáta dobírkové částky  
  prefixAccount Předčíslí účtu  
  account Account number  
  bank Kód banky  
senderContacts   Kontakní údaje odesílatele  
  mobilNumber Mobilní číslo  
  phoneNumber Telefonní číslo  
  emailAddress Email  

Parametry response operace

Položka   Popis parametru Komentář
locationStateSenderResponse      
  responseCode Kód odpovědi  
  responseText Popis odpovědi  
locationStateCodResponse      
  responseCode Kód odpovědi  
  responseText Popis odpovědi  
locationData      
  locationNumber Číslo podacího místa Jedná se o číslo podacího místa, pod kterým chce provádět import – v případě využití této položky není třeba uvádět v requestech údaje senderAddress, codAddress, codBank, senderContacts
locationDataResponseList      
  locationDataResponseList.responseCode Kód odpovědi  
  locationDataResponseList.responseText Popis odpovědi  

Testovací účty

Adresa pro volání testovacího prostředí: https://b2b-test.postaonline.cz:444/restservices/ZSKService/v1/*

U testovacích účtů je nutné uvádět mezi služby velikost zásilky S, M, L nebo XL. Účty nemají nastavenou jednotnou cenu. V ostrém prostředí za předpokladu, že klient má nasmlouvanou jednotnou cenu, tato nutnost odpadne.

API Token Secret key Technologické číslo Podací pošta ID CČK
b79b16c2-2f77-450f-91a5-868c3c698a82 dOJWwjp+BWqUcof3K+3OW6XGTnEpmWerx64TCNk0+0pZnonHdN99NFRIGaJSX0/HTtiu6AGYpKp0mjguzqp+wg== M00077, M00078, U066, U124, U126 10003, 60011 256712001
113b6ef0-723d-4de4-9f0a-0b426203957a ZWXwGSe4D2bFy3qGKMV5z80fN1z6pt8TKtlUQ0g3v9Gn78xGFi5wieYyszrVSTAC3gOp+TfOP8zkAH43gWPWIw== M00076, U062, U118, U121 37271 194402001
ae9007cf-57b9-471b-b443-cda0bb2ba31e /qzdUBd3JnRFOcpLJNVdKGNi4sq2XpMGIMpl51bQ4XhXSc4FEZKzIxoPhbxLO4wk9hknaJjo4NEcyc2XK5JUYA== M00074, U061, U114, U116 77072 167463001
d7e3ab6c-85c8-4502-ae49-351529cce9d0 hkV0h5YH7f4cTSiwsLK4x9E+s9W6s1dznYC8gq7sC+f33dpWOSDMnkXG4ie4eWDCItPrpiJbuHpqgakzvNTEvA== M00069, U060, U070, U067 70071 153526001

Upozorňujeme, že se jedná o testovací prostředí, ve kterém jsou data sdílená mezi všemi uživateli. Z bezpečnostních důvodů je zakázáno v testovacím prostředí zapisovat produkční, resp. ostrá data a chráněné informace (osobní údaje, obchodní tajemství apod.). Žádáme uživatele o dodržování tohoto zákazu. Každý uživatel je odpovědný při nakládání s daty dodržovat základní principy ochrany a bezpečnosti dat a Česká pošta, s.p. nenese odpovědnost za případné porušení tohoto zákazu ze strany uživatele.

Vzory

DR sendParcels + Bezdokladová dobírka

{"parcelHeader":{"transmissionDate":"2022-02-01","customerID":"M00077","postCode":"10003","locationNumber":1,"goodToAccept":true},"parcelDataList":[{"parcelParams":{"recordID":"1","prefixParcelCode":"DR","weight":"1.20","insuredValue":1500,"amount":1500,"currency":"CZK","vsVoucher":"28988358"},"parcelAddress":{"recordID":"1","firstName":"Jan","surname":"Novák","aditionAddress":"areál MÚ","subject":"F","address":{"street":"Těšínská","houseNumber":"42","sequenceNumber":"2672","cityPart":"Předměstí","city":"Opava","zipCode":"74601","isoCountry":"CZ"},"mobilNumber":"+420603123456","emailAddress":"jan.novak@email.cz"},"parcelServices":["7","41","45","M"]}]}

DR parcelService + Bezdokladová dobírka

{"parcelServiceHeader":{"parcelServiceHeaderCom":{"transmissionDate":"2022-03-05","customerID":"M00077","postCode":"10003","locationNumber":1},"printParams":{"idForm":101,"shiftHorizontal":0,"shiftVertical":0},"position":1},"parcelServiceData":{"parcelParams":{"recordID":"1","prefixParcelCode":"DR","weight":"1.20","insuredValue":100,"amount":105,"currency":"CZK","vsVoucher":"123456"},"parcelAddress":{"recordID":"1","firstName":"Jan","surname":"Kuffner","address":{"street":"Těšínská","houseNumber":"42","sequenceNumber":"2672","cityPart":"Předměstí","city":"Opava","zipCode":"74601","isoCountry":"CZ"},"mobilNumber":"+420603488433","emailAddress":"jan.kuffner@cpost.cz"},"parcelServices":["7","41","45","M"]}}

NB sendParcels + Bezdokladová dobírka

{"parcelHeader":{"transmissionDate":"2022-02-01","customerID":"M00077","postCode":"10003","locationNumber":1,"goodToAccept":true},"parcelDataList":[{"parcelParams":{"recordID":"1","prefixParcelCode":"NB","weight":"14.99","insuredValue":1500,"amount":1500,"currency":"CZK","vsVoucher":"28988358"},"parcelAddress":{"recordID":"1","firstName":"Jan","surname":"Kuffner","address":{"street":"Balíkovna","zipCode":"10000"},"mobilNumber":"+420603123456","emailAddress":"jan.kuffner@cpost.cz"},"parcelServices":["7","41","45","M"]}]}

NP sendParcels + Bezdokladová dobírka

{"parcelHeader":{"transmissionDate":"2022-02-01","customerID":"M00077","postCode":"10003","locationNumber":1,"goodToAccept":true},"parcelDataList":[{"parcelParams":{"recordID":"1","prefixParcelCode":"NP","weight":"10.20","insuredValue":1500,"amount":1500,"currency":"CZK","vsVoucher":"28988358"},"parcelAddress":{"recordID":"1","firstName":"Jan","surname":"Kuffner","address":{"street":"Na poštu","zipCode":"10000"},"mobilNumber":"+420603123456","emailAddress":"jan.kuffner@cpost.cz"},"parcelServices":["7","41","45","M"]}]}

 
DR sendParcels + Vícekus + Bezdokladová dobírka

{"parcelHeader":{"transmissionDate":"2022-03-17","customerID":"M00077","postCode":"10003","locationNumber":1,"goodToAccept":true},"parcelDataList":[{"parcelParams":{"recordID":"1","prefixParcelCode":"DR","weight":"2.20","insuredValue":1500,"amount":1500,"currency":"CZK","vsVoucher":"28988358","sequenceParcel":1,"quantityParcel":4},"parcelAddress":{"recordID":"1","firstName":"Jan","surname":"Kuffner","aditionAddress":"areál MÚ","subject":"F","address":{"street":"Těšínská","houseNumber":"42","sequenceNumber":"2672","cityPart":"Předměstí","city":"Opava","zipCode":"74601","isoCountry":"CZ"},"mobilNumber":"+420603123456","emailAddress":"jan.kuffner@cpost.cz"},"parcelServices":["7","41","45","M","70"]},{"parcelParams":{"recordID":"2","prefixParcelCode":"DR","weight":"1.20","insuredValue":1500,"currency":"CZK","sequenceParcel":2,"quantityParcel":4},"parcelAddress":{"recordID":"1","firstName":"Jan","surname":"Kuffner","aditionAddress":"areál MÚ","subject":"F","address":{"street":"Těšínská","houseNumber":"42","sequenceNumber":"2672","cityPart":"Předměstí","city":"Opava","zipCode":"74601","isoCountry":"CZ"},"mobilNumber":"+420603123456","emailAddress":"jan.kuffner@cpost.cz"},"parcelServices":["7","45","M","70"]},{"parcelParams":{"recordID":"3","prefixParcelCode":"DR","weight":"1.20","insuredValue":1500,"amount":1200,"currency":"CZK","vsVoucher":"28988358","sequenceParcel":3,"quantityParcel":4},"parcelAddress":{"recordID":"1","firstName":"Jan","surname":"Kuffner","aditionAddress":"areál MÚ","subject":"F","address":{"street":"Těšínská","houseNumber":"42","sequenceNumber":"2672","cityPart":"Předměstí","city":"Opava","zipCode":"74601","isoCountry":"CZ"},"mobilNumber":"+420603123456","emailAddress":"jan.kuffner@cpost.cz"},"parcelServices":["7","45","M","70"]},{"parcelParams":{"recordID":"4","prefixParcelCode":"DR","weight":"1.20","insuredValue":1500,"amount":1200,"currency":"CZK","vsVoucher":"28988358","sequenceParcel":4,"quantityParcel":4},"parcelAddress":{"recordID":"1","firstName":"Jan","surname":"Kuffner","aditionAddress":"areál MÚ","subject":"F","address":{"street":"Těšínská","houseNumber":"42","sequenceNumber":"2672","cityPart":"Předměstí","city":"Opava","zipCode":"74601","isoCountry":"CZ"},"mobilNumber":"+420603123456","emailAddress":"jan.kuffner@cpost.cz"},"parcelServices":["7","41","45","M","70"]}]}

DR parcelService + Vícekus + Bezdokladová dobírka

{"parcelServiceHeader":{"parcelServiceHeaderCom":{"transmissionDate":"2022-03-05","customerID":"M00077","postCode":"10003","locationNumber":1},"printParams":{"idForm":100,"shiftHorizontal":0,"shiftVertical":0},"position":1},"parcelServiceData":{"parcelParams":{"recordID":"1","prefixParcelCode":"DR","weight":"1.20","insuredValue":100,"amount":105,"currency":"CZK","vsVoucher":"123456","sequenceParcel":1,"quantityParcel":4},"parcelAddress":{"recordID":"1","firstName":"Jan","surname":"Novák","address":{"street":"Těšínská","houseNumber":"42","sequenceNumber":"2672","cityPart":"Předměstí","city":"Opava","zipCode":"74601","isoCountry":"CZ"},"mobilNumber":"+420603488433","emailAddress":"name.surname123@somemaildomain.cz"},"parcelServices":["7","41","45","M","70"]},"multipartParcelData":[{"addParcelData":{"recordID":"2","prefixParcelCode":"DR","weight":"1.20","sequenceParcel":2,"quantityParcel":4},"addParcelDataServices":["70","M"]},{"addParcelData":{"recordID":"3","prefixParcelCode":"DR","weight":"2.20","sequenceParcel":3,"quantityParcel":4},"addParcelDataServices":["70","M"]},{"addParcelData":{"recordID":"4","prefixParcelCode":"DR","weight":"3.20","sequenceParcel":4,"quantityParcel":4},"addParcelDataServices":["70","M"]}]}