Dokumentace API Balíkobot v

Transkript

1 Dokumentace API Balíkobot v Pro jednoduché nasazení API je veškerá komunikace realizována přes URL adresy orientované na zdroje a HTTP autentizaci. Veškerá volání API jsou zabezpečena klíčem, který od nás dostanete při registraci. Zároveň musí být všechny požadavky na API realizovány přes HTTPS protokol, přes HTTP se Vám nedostane žádné odpovědi. Existuje 18 druhů požadavků, které můžete volat: ADD (přidání balíku/balíků), DROP (odstranění balíku), TRACK (stav balíku), OVERVIEW (soupis dosud neodeslaných balíků), PACKAGE (zaslané údaje o konkrétním balíku a odkaz na štítek pro tisk), ORDER (předání dat přepravci svozová dávka), ORDERVIEW (informace k poslednímu/konkrétnímu svozu), SERVICES (seznam podporovaných služeb u konkrétního přepravce), BRANCHES (seznam poboček, na které se dá zasílat zásilky u konkrétních dopravních služeb přepravce), ZIPCODES (seznam PSČ, na které se dají zasílat zásilky u konkrétních dopravních služeb přepravce), LABELS (vrací hromadné PDF se štítky pro vybrané balíky u konkrétního dopravce), MANIPULATIONUNITS (vrací seznam zkratek manipulačních jednotek pro paletovou přepravu), COUNTRIES4SERVICE (seznam států, do kterých se dá zasílat skrze jednotlivé služby přepravce), ORDERPICKUP (objednání svozového kurýra na určitý den a časové okno), CHECK (obdoba metody ADD jen se data neuloží do systému, ale zkontrolují se a API vrátí zda jsou v pořádku, případně seznam chyb), ADRUNITS (seznam kódu jednotek pro režim přepravy ADR), BRANCHLOCATOR (metoda pro nalezení poboček pro zadanou zemi a město) a B2A (objednání svozu na zvolenou adresu zákazníka/partnera pro přepravu připravených balíků/zboží zpět na adresu objednavatele svozu tedy adresu expedičního místa spadající pod API klíče). Při nasazování dostanete pro účely testování Test API key a API uživatelské jméno. Veškeré requesty během testování reagují obdobně jako při živém nasazení. Balíky a objednání svozu (předání dat přepravci) se ale nepředá příslušnému dopravci, zůstane jen v rámci API a předá nazpět mock data. Nastavení jednotlivých dopravců (jejich číselné řady, zákaznická čísla atd.) je u všech testovacích účtů nastaveno stejně. Vyplněním údajů u jednotlivých dopravců v klientské zóně ( se projeví jak u živých, tak u testovacích API klíčů. Až budete mít vše otestováno a nastaveno (konfigurační formuláře pro jednotlivé dopravce a správu svých obchodů naleznete v klientské zóně vyměňte Test API key za Live API key. Tisk štítků z API je možný jak na laserových, tak na inkoustových tiskárnách na formát A4. Termotiskárny typu Zebra umí tisknout jednotlivé (single) štítky, které API vrací. Ty jsou standardně 1

2 v pozici na výšku A4 a mají rozměry dle specifikací dopravců (nejčastěji jedna čtvrtina A4, u dopravců jako je Zásilkovna a InTime je to 1/8 A4). Pokud váš obchod spravuje některé z e-shopových řešení, které je naším partnerem, stačí nás kontaktovat pro získání přístupových údajů do klientské zóny. Z ní pak získáte ostrý API klíč a API uživatele, které vložíte do příslušných políček v administraci vašeho obchodu. Pokud e-shopové řešení ještě není naším partnerem, zažádejte si u něj o přidání naší služby. Pro snadné nasazení API Balikobot žádáme všechny e-shopové řešení o přidání políček pro ostrý API klíč a API uživatele do administrace obchodů. V případě, že implementujete v programovacím jazyce Ruby je možné využít gem (není spravován námi). V případě, že implementujete v programovacím jazyce PHP je možné využít knihovnu (není spravována námi), nebo (není spravována námi). Knihovna BalikoBotSharp -.NET Standard 2.0 v jazyce C# (není spravována námi, MIT llicence). 2

3 Vytvoření požadavku přes PHP knihovnu curl: $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, " curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); curl_setopt($ch, CURLOPT_HEADER, FALSE); curl_setopt($ch, CURLOPT_POST, TRUE); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($adata)); // pole $adata vstupů curl_setopt($ch,curlopt_httpheader, array("authorization: Basic ". base64_encode('user:api_key), "Content-Type: application/json")); $response = curl_exec($ch); curl_close($ch); $aresponse = json_decode($response); // převod návratových hodnot do pole DOPRAVCE nahraďte za zkratku dopravce, přes kterého se bude balík posílat (cp Česká pošta, dpd DPD, ppl PPL, atd. viz. Seznam názvů dopravců v URL requestech ). POŽADAVEK název požadavku, který chcete volat (add, drop, track, view, order). USER:API_KEY nahraďte za přidělené API uživatelské jméno (USER) a API klíč (API_KEY) oddělené dvojtečkou. API uživatele a klíč od nás dostanete na vyžádání. Zároveň je naleznete po přihlášení do klientské zóny ( Vložit jen API klíč nestačí! Odpovědi z API jsou ve formátu JSON. Pro převod na datový typ pole použijte funkci json_decode. Příklad implementace naleznete v kapitole Příklad implementace v administraci obchodu (135). 3

4 OBSAH Přehled změn... 7 ADD Česká pošta DPD PPL Parcel balíková přeprava PPL Sprint paletová přeprava Zásilkovna Geis Parcel balíková přeprava Geis Cargo paletová přeprava Uloženka Intime GLS Toptrans paletová přeprava Pošta bez hranic (PbH) DHL Express Slovenská pošta UPS TNT DHL Parcel SK SPS Slovak Parcel Service Gebrüder Weiss ZPL štítky DROP TRACK TRACK V TRACKSTATUS

5 OVERVIEW LABELS PACKAGE ORDER ORDERVIEW ORDERPICKUP SERVICES MANIPULATIONUNITS BRANCHES FULLBRANCHES BRANCHLOCATOR COD4SERVICES COUNTRIES4SERVICE ZIPCODES CHECK ADRUNITS ACTIVATEDSERVICES B2A B2A PPL Parcel B2A Geis Parcel B2A Geis Cargo B2A DPD Seznam zkratek států/provincií/okresů pro rec_region Seznam názvů dopravců v URL requestech Seznam významu návratových kódů parametru status Tabulka chybových statusů z metody ADD Tipy pro implementátory Příklad implementace v administraci obchodu

6 Přehled objednávek Detail objednávky nezaslaná do API Detail objednávky zaslaná do API, před objednáním svozu Detail objednávky zaslaná do API, po předání dat přepravci Tisk štítku Sledování zásilky (Track & Trace) Předání dat přepravci - objednání svozu

7 Přehled změn Číslo verze Datum vydání Název metody Popis změn ZPL tisk ADD Zásilkovna BRANCHES FULLBRANCHES ADD GLS ADD GW B2A_DPD ADD UPS ADD Zásilkovna - formát ZPL pro tisk štítků - Zásilkovna RU celní deklarace (content_data) - přidání filtru na zemi u přepravce Zásilkovna - přidání filtru na zemi u přepravce Zásilkovna - přidání atributu swap pro výměnnou zásilku - nový přepravce Gebrüder Weiss - přidání DPD sběrného balíku (B2A) - přidání atribut require_full_age (podpis při převzetí zásilky) - přidání atributu swap (výměnná zásilka) - přidání atributů del_exworks / del_exworks_account_number / del_exworks_zip pro platbu přepravy/cla a daní příjemcem - přidání atributů pro neutralizaci zásilky (neutralize_*) - přidání atributu rec_region pro RO zásilky ADD PbH - úprava předávaných dat při zasílání na DHL DE výdejní místa (nutnost zaslat rec_zip, rec_city a rec_zip stejné jako je na výstupu z BRANCHLOCATOR) ADD Intime ADD Zásilkovna - rozšíření o služby Parcel EU (service_type = 8) a Parcel EU+ (service_type = 9) - přidání atribut ins_currency (měna udané ceny) - doručení do Švýcarska přidání potřebných atributů do content_data pro celní prohlášku B2A - nová metoda pro objednání přepravy z místa B (typicky dodavatel/předchozí příjmce) do místa A (expediční místo) ADD PbH - přidání atributů weight (váha) a rec_id (ID příjemce v rámci vybrané poštovní služby) BRANCHLOCATOR - PbH (německá výdejní místa) ADD UPS - odstranění content atributu content_customs_code a změna atributu content_ean na nepovinný + přidání 7

8 atributu note (poznámka) ADD Geis ADD Geis Cargo - úprava názvů služeb (service_type) rozšíření B2C zemí pro mezinárodní doručení - úprava názvů služeb (service_type) rozšíření B2C zemí pro mezinárodní doručení ACTIVATEDSERVICES - nová metoda pro ostré API klíče (seznam aktivních služeb na úrovni přepravce) ADD CP ADD SP - přidání pomocného atributu branch_id - přidání pomocného atributu branch_id ADD SPS - podpora mezinárodních zásilek (service_type = 4) ADD GLS - přidání atributu del_insurance (připojištění) a ins_currency (měna udané ceny) ADD Zásilkovna - přidání celní deklarace (content_data), ceny přepravy v EUR (delivery_costs_eur) a ceny přepravy v měně cílové země (delivery_costs) pro doručování na Ukrajinu ADD Uloženka ADD PPL Parcel ADD SPS - rozšíření o nové služby (19 Expres kurýr SK, 20 Expres na poštu SK, 21 BalíkoBOX SK, 22 Depo SK) - vážené zásilky (jiný formát štítků) - přidání přepravce Slovak Parcel Service ADD DHL PARCEL SK - přidání přepravce DHL Parcel SK ADD PPL Sprint COD4SERVICES - přidání atributu adr_service pro režim ADR přepravy - nová informační metoda pro získání seznamu služeb (na úrovni přepravce) a k nim zemí, do kterých lze zasílat doběrečné zásilky BRANCHLOCATOR - přidání nové metody pro vyhledání poboček na základě vstupních parametrů (dostupné pro přepravce UPS) ADD TNT ADD CP - přidání přepravce TNT - možnoti předávání konfekční velikosti zásilkek přidání seznamu zkratek států/provincií/okresů pro USA, Kanadu a Irsko důležité pro doručení přes UPS do těchto zemí (atribut rec_region) ADD UPS - úprava popisu ke službě UPS Access Point branch_id ADD PbH - rozšíření o výdejní místa Rakouské pošty (service_type = 8

9 8) dostupná přes metodu BRANCHES ADD Zásilkovna - přidání rozměrových atributů width, length a height pro doručování na Paczkomaty do PL ADD PbH - rozšířšení o přepravce Nova Poshta (UA), doplněná textace u atributů rec_name, přidání atributu rec_name_patronymum a rec_locale_id ADD Geis ADD Geis Cargo ADD PbH ADD UPS TRACK V ADD Toptrans ADRUNITS - přidání atributu bank_account_number - přidání atributu bank_account_number - přidání nových atributů pro upřesněné dodání u přepravce Meest (BG) - přidání přepravce UPS - přidání návratového atributu status_id - přidání atributu pro adr_content pro režim přepravy ADR - nová metoda pro získání ADR kódů jednotek TRACK V2 - přidání upravené metody TRACK verze 2, která vrací data strukturovaně ADD PbH ADD PPL ADD PPL Sprint ADD GLS ADD Uloženka ADD_SP - rozšíření o výdejní místa a automaty BG Speedy - přídání atributů open_before_payment a test_before_payment - úprava textace u rec_zip doplnění o ID lokalit - přidání atributu del_insurance - přidání atributu del_insurance - přidání atributu note - rozšíření o službu 17 Doručení na adresu D+1 - nový přepravce Slovenská pošta FULLBRANCHES - přidání informací k pobočkám Pošty bez hranic ADD Zásilkovna - přidání atributu swap pro výměnné zásilky (režim Reklamační asistent) ADD PbH - rozšíření atributu content_data o počet kusů produktu content_pieces ADD PbH - přidání atributů pro celní prohlášky (content_data a invoice_number) - přidání atributu branch_id pro výdejní místa 9

10 přidání popisu datových typů a omezení atributů metody ADD ADD PbH - přidání přepravce Meest ADD DHL - rozšíření o služby 6 Vnitrostátní Domestic Express 12:00 a 7 - Vnitrostátní Domestic Express ADD CP ADD DPD ADD Geis ADD Geis Cargo - rozšíření o služby RR Doporučená zásilka do zahraničí Prioritní, VL Cenné psaní do zahraničí Prioritní, EMS Expresní přeprava do zahrančií, CS Standardní balík do zahraničí Prioritní, CS Standardní balík do zahraničí Ekonomický, CV Cenný balík do zahraničí Prioritní, CV Cenný balík do zahraničí Ekonomický a CE Obchodní balík do zahraničí - přidání atributů pers_delivery_floor, pers_delivery_building, pers_delivery_department pro doručení na oddělení, atritubutu require_full_age pro ověřené předání a atributu pin pro zabezpečené předání - úprava popisu atributu del_insurance - přidání atributu del_insurance a contents pro připojištění ADD CP - rozšíření o službu BE - Balík Expres ADD Toptrans - přidání atributu comfort_exclusive_service (doplňková služba Top Comfort Exclusive) ADD CP ADD DHL - přidání doplňkových služeb ddodejka SMS 76, edodejka 77 a edodejka SMS mezi povolené hodnoty atributu services - přidání atributu swap a swap_option pro vrácení zpátečního štítku a zpátečního čísla zásilky ADD CP - přidání doplňkové služby Odvoz zboží 1V mezi povolené hodnoty atributu services ZIPCODES CHECK - DHL příklady + přidání nové hodnoty atributu type - nová metoda pro kontrolu zaslaných dat k zásilce bez jejího vložení do systému TRACKSTATUS - přidání nového statusu (4 Zásilka byla doručena zpět odesilateli) 10

11 DROP FULLBRANCHES ADD PPL Sprint ADD GLS ADD Geis ADD CP ADD Toptrans ADD Geis ADD Geis Cargo ADD Uloženka ADD CP - přidání nového chybového statusu úprava příkladů - přidání informací k NP pobočkám České pošty - přidání atributu volume objem - rozšíření o službu Express Parcel (sercice_type 3) - přidání atributu _notification - rozšíření o služby DE - Balík do ruky s garantovaným časem dodání, DE Balík Do ruky s garantovaným časem dodání Ne/Sv. a EMS Expresní přeprava po ČR - přidání atributů content_one, content_two, content_three pro difinici obsahu zásilky - přidání atibutů phone_delivery_notification a phone_order_notification - rozšíření o službu Mezinárodní zásilka (B2C) do SK / PL, Garantované doručení a Doručení do 12. hodin - rozšíření o služby Vnitrostátní paletová zásilka (B2C) a Mezinárodní paletová zásilka (B2C) do SK - rozšíření služby DPD Classic do dalších zemí (FR, DE, PL, AT, RO, GB) - přidání atributu wrap_back_count pro službu NB počet palet zpět Přehled možných chyb - přidání nových návratových statusů ADD PPL ADD CP ADD Geis Cargo ADD Toptrans ADD PPL Sprint ADD ADD PbH - poznámka k zásilce (atribut note) - poznámka k zásilce (atribut note) - přidání atributu get_piece_numbers (čísla kusů) - přidání atributu get_piece_numbers (čísla kusů) - přidání atributu get_piece_numbers (čísla kusů) - přidání atributu return_full_errors pro navrácení chyb v textové podobě namísto standardních číselných - formát návratové struktury při použití atributu get_piece_numbers - přidání přepravců Hermes, Speedy a Colissimo ADD PPL - přidání atributu sat_delivery pro sobotní doručení ADD CP - přidání doplňkové služby Dodání do vlastních rukou 11

12 výhradně jen adresáta pro ověření věku adresáta skrze atributy require_full_age a full_age_data ADD PbH - přidání atributu del_insurance ADD CP ADD Uloženka ADD DHL ORDERPICKUP ADD Intime ADD Zásilkovna ADD PbH - přidání služby Balík do balíkovny (NB) - přidání nových služeb Inpost výdejní automaty (8) a Intime Balíkomat (10) - nový přepravce DHL - nová metoda pro objednání svozového kurýra - přidání atributu require_full_age - přidání atributu require_full_age - přidání nových přepravních služeb (service_type 13, 14,15) ADD PbH - přidání atributu rec_region pro RO zásilky ADD Geis - branch_id přidání možnosti SK G-Pointů ADD Toptrans - přidání atributu bank_account_number ADD PPL Sprint - přidání atributu wrap_back_count ADD CP - přidání služby BN (Balík Nadrozměr) ADD - přidání atributu return_track pro získání trackovacího linku na web přepravce v odpovědi metody FULLBRANCHES - nová metoda vracející více informací k pobočkám ADD Toptrans ADD Geis ADD Geis Cargo - přidání atributu delivery_date (datum plán. realizace) - přidání atributu reference - přidání atributu reference ADD Toptrans - přidání atributu pro službu ADR (adr_service) ADD PPL Sprint - PPL Sprint paletová přeprava ADD CP DROP ZIPCODES ADD PbH countries4service zipcodes - časová pásma doručení (atribut services) - specifikace Intime a Uloženka (hromadné odmazávání) - časová pásma u ČP - přidání přepravce Pošta bez hranic - nová metoda vracející podporované země v rámci služby - přidání parametru country - přidání statusu

13 ADD Toptrans - přidání přepravce Toptrans ADD GLS - přidání přepravce GLS ADD DPD ADD Geis ADD Intime ADD Uloženka - přidání atributu pro poznámku přepravci (note) - přidání atributu pro poznámku přepravci (note) - přidání atributu pro poznámku přepravci (note) - přidání atributu pro poznámku přepravci (note) ADD Uloženka - Přidání služby Uloženka Partner ADD Intime - Přidání služby Extra Large Colli 24-CZ DROP - Rozšíření metody o možnost hromadného volání ADD Uloženka - Přidání služby Uloženka PNS TRACKSTATUS - Nová metoda pro zjištění posledního stavu zásilky ADD Geis ADD ADD ČP ADD PPL ADD Geis Cargo MANIPULATIONUNITS - Přidání služby Geis Point - Opakované zásilky (příklad implementace) - Přidání služby BB(cenný balík) + rozšíření popisu atributu services (služba křehké) - Přidání služby Večerní doručení -Přidání paletové dopravy (Cargo) -Nová metoda pro paletovou přepravu ADD ČP -Přidání služby BA (Doporučený balíček) + SR(RR standard) ADD Intime ADD ČP ADD PPL ADD Zásilkovna ADD Geis ADD Uloženka ADD DPD -Přidání nového dopravce -Přidání klíče pro reálné číslo objednávky (real_order_id) -Přidání klíče pro reálné číslo objednávky (real_order_id) -Přidání klíče pro reálné číslo objednávky (real_order_id) -Přidání klíče pro reálné číslo objednávky (real_order_id) -Přidání klíče pro reálné číslo objednávky (real_order_id) -Přidání nových služeb u DPD povinný atribut service_type, možnost výměnné zásilky (swap), přidání atributu real_order_id, přidání atributu branch_id pro výdejní místa Pickup -Přidání kapitoly Příklad implementace v administraci obchodu (135) -Úprava textace u statusu 409 (131) -Přehledová tabulka metody ADD (72) 13

14 LABELS ORDER SERVICES BRANCHES ZIPCODES -Přidání nové metody pro hromadné PDF se štítky -Přidání poznámky pro e-shopová řešení -Přidání nové metody pro seznam služeb u dopravce -Přidání nové metody pro seznam poboček u služeb -Přidání nové metody pro povolené PSČ u služeb 14

15 ADD Přidává balík/balíky, které se odešlou ke svozu. Request: $adata = array(); $adata[0] = array( 'eid' => ' ', 'service_type' => 'DR', 'cod_price' => , 'price' => 12300, 'rec_phone' => ' ', 'rec_name' => 'John Carter', 'rec_street' => 'Palackého 12', 'rec_city' => 'Praha 9', 'rec_ ' => 'john@carter.com', 'rec_zip' => '19000', 'del_evening' => true,. }; $adata[1] = array( ); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, " curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); curl_setopt($ch, CURLOPT_HEADER, FALSE); curl_setopt($ch, CURLOPT_POST, TRUE); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($adata)); // pole $adata vstupů curl_setopt($ch,curlopt_httpheader, array("authorization: Basic ". base64_encode('user:api_key), "Content-Type: application/json")); $response = curl_exec($ch); curl_close($ch); $aresponse = json_decode($response); // převod návratových hodnot do pole 15

16 Každý zasílaný balík musí obsahovat unikátní 'eid' (v návratových hodnotách z API pod názvem eshop_id), které jednoznačně identifikuje balík (objednávku) v rámci e-shopu může mít délku maximálně 40 znaků a přijímá alfanumerické hodnoty. Data bez tohoto vyplněného parametru nebudou přijata! Pokud odešlete opětovně data s již uloženým eid, nebudou nově příchozí data uložena, o čemž dostanete zprávu v atributu status, který bude mít hodnotu 208! U sdružených objednávek (víc balíků pro jednoho zákazníka v jeden den), je potřeba předávat do API unikátní dvojice eid a order_number (pořadové číslo balíku - 1, 2, 3 atd.). Pokud je sdružená objednávka na dobírku, uveďte celkovou částku dobírky k prvnímu balíku (order_number = 1). U objednávek, které čítají jen jeden balík, není potřeba vyplňovat parametr order_number. U všech zásilek je potřeba vyplnit pole rec_country (kód země příjemce dle ISO alpha-2 (viz. výchozí hodnotou je Česká republika (CZ)). U všech dobírkových zásilek je potřeba mít vyplněné pole cod_price (částka dobírky) a cod_currency (měna dobírky dle ISO 4217 kódu (pro Kč je například CZK, pro euro je EUR)). Příklad sdružené objednávky, která čítá 3 balíky: $adata [0] = array('eid' => ' ', 'order_number' => '1', 'cod_price' => '10000'...), $adata [1] = array('eid' => ' ', 'order_number' => '2',...), $adata [2] = array('eid' => ' ', 'order_number' => '3',...) Opakované zásilky Pro zaslání opakovaných zásilek (například zásilka, kterou je potřeba znovu zaslat příjemci kvůli špatnému zaslání) je potřeba zaslat nové unikátní eid! Příklad možné realizace: Původní zásilka: array (eid => , vs => ,...); Opakovaná zásilka: array (eid => , vs => ,...); 16

17 Česká pošta Podporované služby: DR balík Do ruky, NP balík Na poštu, RR doporučená zásilka (při zaslání informace o váze zásilky do 0,05 kg RR standard), DV balík Do ruky pro vybrané podavatele, VL cenné psaní, SR RR standard (obdoba RR, jen není potřeba zasílat váhu do 0,05 kg systém při nedoražení váhy udá váhu 0,04 kg), BA doporučený balíček, BB cenný balík, BN balík nadrozměr, NB balík do balíkovny, DT DE balík Do ruky s garantovaným časem dodání, DS balík Do ruky s garantovaným časem dodání v neděli nebo svátek, EE EMS expresní přeprava po ČR, BE Balík Expres, RZP RR Doporučená zásilka do zahraničí Prioritní, VZP VL Cenné psaní do zahraničí Prioritní, EM EMS Expresní přeprava do zahraničí, CSP CS Standardní balík do zahraničí Prioritní, CSE CS Standardní balík do zahraničí Ekonomický, CVP CV Cenný balík do zahraničí Prioritní, CVE CV Cenný balík do zahraničí Ekonomický, CE Obchodní balík do zahraničí. Pokud chcete zaslat sdruženou zásilku (více balíků pro jednoho adresáta) udávejte vždy celkovou udanou cenu (atribut price), případně též celkovou výši dobírky (atribut cod_price) k hlavnímu záznamu (order_number = 1)! Sdružené zásilky mohou být jen od jednoho typu služby (service_type) a u služeb cenné psaní (VL), doporučená zásilka (RR) a cenný balík (BB) nelze vytvořit sdruženou zásilku vůbec! API endpoint přepravce: API endpoint metody ADD: klíč povinná popis rec_name Jméno a příjmení příjemce. rec_firm rec_phone Název firmy příjemce. Telefonní číslo příjemce, povinné při využití služby oznámení pomocí SMS nebo jiném telefonickém kontaktu formát čísla: +420XXXYYYZZZ rec_ příjemce. rec_street rec_city rec_zip Ulice příjemce. (U služby NP není povinné, dotáhne se adresa cílové pošty/poštomatu) Adresační město příjemce. (U služby NP není povinné, dotáhne se z adresy cílové pošty/poštomatu) PSČ příjemce, uvádějte bez mezer ve formátu XXXXX. V případě služeb NP nebo NB se uvádí PSČ cílové pobočky/balíkovny případně je možné (od 17

18 rec_country price cod_price cod_currency vs eid ) zasílat do atributu branch_id a rec_zip vůbec neplnit daty. Kód země příjemce dle ISO alpha-2 (viz. výchozí hodnotou je Česká republika (CZ). Udaná cena zásilky, u sdružených zásilek uvádějte sečtenou hodnotu všech balíků do zásilky s prvním order_number (order_number => 1), u zbylých order_number uvádějte nulovou cenu! Cena dobírky, povinná u všech dobírkových služeb. U sdružených zásilek uvádějte sečtenou dobírkovou hodnotu všech balíků do zásilky s prvním order_number (order_number => 1), u zbylých order_number uveďte nulovou cenu! Měna dobírky dle ISO 4217 kódu (pro Kč je například CZK, pro euro je EUR), povinná položka u všech dobírkových služeb. Variabilní symbol platby, povinný pro dobírkové zásilky (číslo, délka max 10). Unikátní ID balíku v rámci e-shopu(ů), které využívají stejné konfigurační údaje přepravce. order_number Povinný pro sdružené zásilky, u samostatných se nemusí uvádět. Typ služby (DR balík do ruky, RR doporučená zásilka, NP na poštu, DV balík do ruky pro vybrané podavatele, VL cenné psaní), SR doporučená zásilka standard, BA doporučený balíček, BB cenný balík, service_type real_order_id BN balík nadrozměr, NB balík do balíkovny, DT DE balík Do ruky s garantovaným časem dodání, DS balík Do ruky s garantovaným časem dodání v neděli nebo svátek, EE EMS expresní přeprava po ČR, BE Balík Expres, RZP RR Doporučená zásilka do zahraničí Prioritní, VZP VL Cenné psaní do zahraničí Prioritní, EM EMS Expresní přeprava do zahraničí, CSP CS Standardní balík do zahraničí Prioritní, CSE CS Standardní balík do zahraničí Ekonomický, CVP CV Cenný balík do zahraničí Prioritní, CVE CV Cenný balík do zahraničí Ekonomický, CE Obchodní balík do zahraničí. Seznam dostupných služeb je k nalezení přes metodu SERVICES. Reálné číslo objednávky (zobrazuje se na přepravních štítcích a předává se datově přepravci, pokud není vyplněno, tak se předává eid), doporučujeme 18

19 ho tedy vyplňovat, pokud do povinného eid zasíláte jiné hodnoty. services čísla jednotlivých služeb spojených znakem +, které používáte pro zásilky (viz. číselný seznam služeb České pošty dostupný na služba číslo 7 je zahrnuta již v API a nemusíte ji zasílat, tejně tak 41 bezdokladová dobírka. U sdružených zásilek musí být čísla jednotlivých služeb uvedena vždy u prvního balíku ze sdružené zásilky (order_number => 1), u zbylých se uvádět nemusí. pro využití služby křehké zasílejte hodnotu 11 Příklad bezdokladové dobírky se službou křéhké: odvoz zboží (1V) edodejka SMS 76 edodejka 77 edodejka SMS časová pásma - dopolední/odpolední doručení si můžete nastavit plošně na všechny DR zásilky ve vaší klientské zóně nebo nám tuto informaci můžete zasílat v atributu services hodnota pro dopolední doručení je "1A", pro odpolední doručení je "1B". dodání firmě (40), paleta (68) ověření věku - Dodání do vlastních rukou výhradně jen adresáta (8) + je potřeba zaslat rok narození adresáta do atributu full_age_data konfekční velikost zásilky možné hodnoty: S (nejdelší rozměr max. 35 cm), M (nejdelší rozměr max. 50 cm), L (nejdelší rozměr max. 100 cm), XL (nejdelší rozměr max. 240 cm). Případně se provede převod do příslušné kategorie (S/M/L/XL) na základě zaslaných rozměrů v atributech width, height a length. Pokud má klient unifikované rozměry krabic, může si vyplnit výchozí hodnotu v konfiguraci ve své klientské zóně a tento údaj nezasílat. width Šířka balíku v cm, datový typ float. Povinný údaj pro service_type = BN. length Délka balíku v cm, datový typ float. Povinný údaj pro service_type = BN. height Výška balíku v cm, datový typ float. Povinný údaj pro service_type = BN. 19

20 weight return_track require_full_age Váha balíku v kg, datový typ float. Pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou v dotazu metody zadejte boolean (TRUE) nebo hodnotu 1. Doplňková služba ověření věku - Dodání do vlastních rukou výhradně jen adresáta, v dotazu metody zadejte boolean (TRUE) nebo hodnotu 1. full_age_data return_full_errors note wrap_back_count branch_id Pokud chcete využít doplňkovou službu Dodání do vlastních rukou výhradně jen adresáta, je potřeba zaslat rok narození adresáta tedy například 1988, formát musí být XXXX. Pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean). Poznámka přepravci (maximální délka 50 znaků). Počet palet zpět (integer, 1 a více), s touto hodnotou se pracuje pouze u služby NB a pokud máte povoleno v klientské zóně Balíkobotu. ID pošty (NP) nebo balíkovny (NB) na kterou má zásilka směřovat. Seznam aktuálně dostupných pošt/balíkoven můžte získat skrze metodu BRANCHES nebo FULLBRANCHES. V případě vyplnění tohoto atributu není potřeba vyplňovat rec_zip. 20

21 DPD Podporované služby: DPD Private, DPD Private večerní doručení, DPD Private sobotní doručení, DPD Classic, DPD Pickup, DPD Expresní doručení do 10:00, DPD Expresní doručení do 12:00 a DPD Expresní doručení do 18:00. Pokud chcete zaslat sdruženou zásilku (více balíků pro jednoho adresáta) udávejte vždy celkovou výši dobírky (atribut cod_price) k hlavnímu záznamu (order_number = 1)! API endpoint přepravce: API endpoint metody ADD: klíč povinná popis 1 DPD Classic, 2 DPD Private, 3 DPD Pickup, 4 DPD Express 10:00, 5 - service_type DPD Express 12:00, 6 - DPD Express 18:00, 7 - DPD Private večerní doručení, 8 - DPD Private sobotní doručení. Seznam dostupných služeb je k nalezení přes metodu SERVICES. rec_name jméno a příjmení příjemce rec_firm rec_phone název firmy příjemce telefonní číslo příjemce, povinné při využití služby oznámení pomocí SMS nebo jiném telefonickém kontaktu formát čísla: +420XXXYYYZZZ rec_ příjemce rec_street ulice příjemce rec_city adresační město příjemce rec_zip PSČ příjemce, uvádějte bez mezer ve formátu XXXXX kód země příjemce dle ISO alpha-2 (viz. rec_country price výchozí hodnotou je Česká republika (CZ) udaná cena zásilky cod_price cena dobírky, povinná u všech dobírkových služeb cod_currency měna dobírky dle ISO 4217 kódu (pro Kč je například CZK, pro euro je EUR), povinná položka u všech 21

22 dobírkových služeb vs variabilní symbol platby, povinný pro dobírkové zásilky eid unikátní ID balíku v rámci e-shopu(ů), které využívají stejné konfigurační údaje přepravce order_number povinný pro sdružené zásilky, u samostatných se nemusí uvádět reálné číslo objednávky (zobrazuje se na přepravních štítcích a předává se real_order_id datově přepravci, pokud není vyplněno, tak se předává eid), doporučujeme ho tedy vyplňovat, pokud do povinného eid zasíláte jiné hodnoty večerní doručení, datový typ boolean (true/false), výchozí hodnotou je false, tato doplňková služba je možná jen na některá PSČ (viz metoda ZIPCODES del_evening sms_notification credit_card pro službu 7). Pro novější implementace je tento atribut nefunkční, pokud chcete využít DPD Private večerní doručení zašlete ji rovnou jako službu (service_type 7)! příznak, zda má příjemci dorazit SMS oznámení před doručením zásilky, výchozí hodnotou je false Příznak (0 ne / 1- ano), že zákazník může dobírku zaplatit kartou. příznak, zda se jedná o výměnnou zásilku, výchozí hodnotou je false, pro swap width length height weight tento druh zásilek je pak v návratových hodnotách navíc atribut carrier_id_swap šířka balíku v cm, datový typ float délka balíku v cm, datový typ float výška balíku v cm, datový typ float váha balíku v kg, datový typ float branch_id del_insurance note return_track ID pobočky, na níž je zásilka určena k výdeji v rámci služby DPD Pickup (dříve ParcelShop). Seznam aktuálních výdejen DPD Pickup můžete získat přes metodu BRANCHES, případně na Připojištění, datový typ boolean (TRUE) nebo hodnotu 1. Do 50 tisíc Kč jsou zásilky připojištěny automaticky, bere se v potaz až u zásilek s hodnotou nad tento limit. poznámka přepravci (maximální délka 70 znaků) pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou 22

23 v odpovědi metody zadejte boolean (TRUE) nebo hodnotu 1 return_full_errors require_full_age pers_delivery_floor pers_delivery_building pers_delivery_department pin pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean) Ověřené předání 18+, přijímané hodnoty jsou TRUE (boolean) nebo 1 (string / integer). Je nutné mít tuto službu povolenou v klientské zóně. Doručení do oddělení poschodí Doručení do oddělení budova Doručení do oddělení kancelář Zabezepečené předání 4 místný číselný kód 23

24 PPL Parcel balíková přeprava Podporované služby: soukromý balík - PPL Parcel CZ Private (i s pobočkami PPL Partner a večerním doručením), firemní balík PPL Parcel CZ Business, dopolední balík PPL Parcel CZ Dopolední balík a exportní balík PPL Parcel Connect do zahraničí (Slovensko). Nově (od ) je také možné zasílat vážené zásilky (datově se nic nemění, vrací se větší rozšířený štítek (100x185mm) s dalšími nutnými informacemi) pro aktivaci této možnosti je potřeba mít s PPL smlouvu o vážených zásilkách + vyžádat si u obchodního zástupce Balíkobotu aktivaci v konfiguraci přepravce. API endpoint přepravce: API endpoint metody ADD: klíč povinná popis branch_id ID pobočky, na níž je zásilka určena k výdeji v rámci služby PPL Partner, při doručení do domu je nepovinná. Seznam aktuálně aktivních výdejen PPL Partner získáte přes metodu BRANCHES. ID pobočky zasílejte bez prefixu KM, tedy místo KMMH02 posílejte jen MH02. rec_name Jméno a příjmení příjemce. Povinný v případě neuvedení rec_firm. ID služby, kterou se bude zásilka posílat: 2 PPL Parcel Connect (exportní balík) 3 PPL Parcel CZ Dopolední balík service_type 4 PPL Parcel CZ Private (soukromý balík) 8 PPL Parcel CZ Business (firemní balík) 9 PPL Parcel CZ Private - Večerní doručení Seznam dostupných služeb je k nalezení přes metodu SERVICES. rec_firm Název firmy příjemce. Povinný v případě neuvedení rec_name. Telefonní číslo příjemce, povinné při využití služby oznámení pomocí SMS rec_phone nebo jiném telefonickém kontaktu formát čísla (uvádějte i s předvolbou): +AAAXXXYYYZZZ rec_ příjemce. rec_street Ulice příjemce. rec_city Adresační město příjemce. rec_zip PSČ příjemce, uvádějte bez mezer ve formátu XXXXX rec_country Kód země příjemce dle ISO alpha-2 (viz. 24

25 výchozí hodnotou je Česká republika (CZ), pro zásilky mimo ČR je toto pole povinné price Udaná cena balíku používá se pak pro účely připojištění del_insurance. cod_price Cena dobírky, povinná u všech dobírkových služeb. Měna dobírky dle ISO 4217 kódu cod_currency (pro Kč je například CZK, pro euro je EUR), povinná položka u všech dobírkových služeb. vs Variabilní symbol platby, povinný pro dobírkové zásilky. eid Unikátní ID balíku v rámci e-shopu(ů), které využívají stejné konfigurační údaje přepravce. order_number Povinný pro sdružené zásilky, u samostatných se nemusí uvádět. Reálné číslo objednávky (zobrazuje se na přepravních štítcích a předává se real_order_id datově přepravci, pokud není vyplněno, tak se předává eid), doporučujeme ho tedy vyplňovat, pokud do povinného eid zasíláte jiné hodnoty. Večerní doručení, pro využití zašlete datový typ boolean (true) nebo del_evening width length height weight return_track hodnotu 1. Pokud zašlete service_type => 9, nastaví se del_evening automaticky. Šířka balíku v cm, datový typ float. Délka balíku v cm, datový typ float. Výška balíku v cm, datový typ float. Váha balíku v kg, datový typ float. Pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou v odpovědi metody zadejte boolean (TRUE) nebo hodnotu 1. Doplňková služba sobotní doručení pro B2C zásilky, přijímané hodnoty: sat_delivery return_full_errors note del_insurance boolean (TRUE) nebo hodnota 1, dá se také plošně nastavit v klientské zóně pro všechny B2C zásilky. Pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean). Poznámka přepravci (maximální délka 350 znaků, delší text se zkrátí). Přijímané hodnoty jsou TRUE(boolean) a 1 (string/integer). Uvádějte jen u balíků s celkovou hodnotou nad Kč, které chcete připojistit, 25

26 zároveň je potřeba zaslat v atributu price hodnotu balíku balík se pak připojišťuje na cenu price U zahračních zásilek je to pak price

27 PPL Sprint paletová přeprava Podporované služby: PPL Firemní paleta, PPL Soukromá paleta. API endpoint přepravce: API endpoint metody ADD: klíč povinná popis rec_name rec_firm rec_phone Jméno a příjmení příjemce. Název firmy příjemce. Povinný v případě neuvedení rec_firm. Název firmy příjemce. Název firmy příjemce. Povinný v případě neuvedení rec_name. Telefonní číslo příjemce, povinné pro soukromé zásilky (B2C) a doplňkové služby telefonické avízo (AVI) a SMS avízo (SMS), formát čísla: +420XXXYYYZZZ. rec_ příjemce. rec_street Ulice příjemce. rec_city Město příjemce. rec_zip PSČ příjemce, uvádějte bez mezer. Kód země příjemce dle ISO alpha-2 (viz. rec_country service_type price momentálně je možné zasílat pouze po CZ. ID služby, kterou se bude zásilka posílat: 15 PPL Firemní paleta 19 PPL Soukromá paleta Seznam dostupných služeb je k nalezení přes metodu SERVICES. Udaná cena kusu/kusů. Používá se pro účely připojištění del_insurance. cod_price Dobírková částka, povinná u všech dobírkových služeb. Měna dobírky dle ISO 4217 kódu cod_currency (pro Kč je například CZK, pro euro je EUR), povinná položka u všech dobírkových služeb. vs Variabilní symbol platby, povinný u dobírkových zásilek. 27

28 eid Unikátní ID balíku v rámci e-shopu(ů), které využívají stejné konfigurační údaje přepravce. order_number Povinný pro sdružené zásilky, u samostatných se nemusí uvádět. Reálné číslo objednávky (zobrazuje se na přepravních štítcích a předává se real_order_id mu_type pieces_count weight del_exworks comfort_service app_disp wrap_back_count note return_track return_full_errors get_piece_numbers volume del_insurance datově přepravci, pokud není vyplněno, tak se předává eid), doporučujeme ho tedy vyplňovat, pokud do povinného eid zasíláte jiné hodnoty kód manipulační jednotky (jejich seznam s názvy získáte metodou MANIPULATIONUNITS). Počet nákladových kusů stejné manipulační jednotky (např. pokud je součástí zásilky 5 amerických palet, bude hodnota 5), pokud je nákladový kus od manipulační jednotky pouze 1, není potřeba uvádět hodnotu. Celková váha nákladového kusu/kusů v kg, datový typ float (maximum 80 kg). Služba platba příjemcem (datový typ boolean (true/false). Služba výnos na poschodí (datový typ boolean true/false). Služba odvoz starého spotřebiče (datový typ boolean true-false). Počet europalet zpět (hodnota se použije pouze v případě, že je klient smluvním vlastníkem paletové konta PPL Sprint a má tuto skutečnost vyplněnou v klientské zóně), datový typ integer. Poznámka přepravci (maximální délka 300 znaků, delší text se zkrátí). Pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou v odpovědi metody zadejte boolean (TRUE) nebo hodnotu 1. Pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean). Pro navrácení čísel kusů jednotlivých nákladových kusů manipulačních jednotek zašlete hodnotu 1 nebo TRUE (boolean). Celkový objem kusů (pieces_count) od dané manipulační jednotky (mu_type) v m3. Přijímané hodnoty jsou TRUE(boolean) a 1 (string/integer). Uvádějte jen u zásilek s celkovou hodnotou nad Kč, které chcete připojistit, zároveň je potřeba zaslat v atributu price celkovou hodnotu zásilky na tu 28

29 se pak připojišťuje. adr_service Režim přepravy ADR ( 0 NE, 1 ). Výchozí hodnota je 0. 29

30 Zásilkovna Podporované služby: Z-Point pobočky v síti Zásilkovna, Expresní doručení Praha, Expresní doručení Brno, Expresní doručení Ostrava, Doručení na adresu ČR. Vzhledem k velkému množství služeb a jejich častému rozšiřování není u tohoto přepravce přítomen atribut service_type! Veškeré služby / pobočky jsou dohledatelné skrze metodu BRANCHES (viz níže popis atributu branch_id). API endpoint přepravce: API endpoint metody ADD: klíč povinná Popis ID pobočky, na níž je zásilka určena k výdeji, nebo ID poštovní či kurýrní služby, na níž má být zásilka podána. branch_id Seznam potřebných ID služeb/poboček si můžete stáhnout přes metodu BRANCHES nebo FULLBRANCHES. Pozor, ID kurýrních/poštovních služeb se vkládá stejně jako ID poboček do tohoto atributu, ne do service_type, který tento přepravce nemá! rec_name Jméno a příjmení příjemce. rec_firm rec_phone Název firmy příjemce. Telefonní číslo příjemce, povinné při využití služby oznámení pomocí SMS nebo jiném telefonickém kontaktu formát čísla je potřeba zadávat s předvolbou: +AAAXXXYYYZZZ rec_ příjemce. rec_street Ulice příjemce. Povinné u doručení kurýrem (type= service ) nebo na poštu. rec_city rec_zip rec_country price Město příjemce. Povinné u doručení kurýrem (type= service ) nebo na poštu. PSČ příjemce, uvádějte bez mezer ve formátu XXXXX. Povinné u doručení kurýrem (type= service ) nebo na poštu. Kód země příjemce dle ISO alpha-2 (viz. výchozí hodnotou je Česká republika (CZ). Udaná cena zásilky, uvádí se kvůli pojištění (maximální výše Kč / 700 EUR). 30

31 cod_price Výše dobírky, povinná u všech dobírkových zásilek. cod_currency Měna dobírky dle ISO 4217 kódu (pro Kč je například CZK, pro euro je EUR), povinná položka u všech dobírkových služeb. vs Variabilní symbol platby, povinný pro dobírkové zásilky. eid Unikátní ID balíku v rámci expedičních míst, které využívají stejné konfigurační údaje přepravce, max 24 znaků. order_number Povinný pro sdružené zásilky, u samostatných se nemusí uvádět Reálné číslo objednávky (zobrazuje se na přepravních štítcích a předává se real_order_id del_evening weight return_track require_full_age return_full_errors datově přepravci, pokud není vyplněno, tak se předává eid), doporučujeme ho tedy vyplňovat, pokud do povinného eid zasíláte jiné hodnoty. Večerní doručení, datový typ boolean (true/false), výchozí hodnotou je false. Váha balíku v kg, datový typ float. Pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou v odpovědi metody zadejte boolean (TRUE) nebo hodnotu 1. Příznak (0 ne / 1- ano), že se má při předání ověřovat plnoletost příjemce. Pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean). Výměnná zásilka (ke klasickému štítku bude ještě štítek v režimu Reklamační swap asistent + se navrátí carrier_id_swap) zašlete hodnotu 1 nebo TRUE (boolean). Rozměr zásilky šířka (v cm). Povinný pro doručování na polské width Paczkomaty. Případně si můžete v klientské zóně nastavit výchozí rozměry. Doporučujeme ovšem zasílat, protože v případě nepřesných rozměrů vás může dopravce zpětně finančně kontaktovat. Rozměr zásilky výška (v cm). Povinný pro doručování na polské Paczkomaty. Povinný pro doručování na polské Paczkomaty. Případně si height length můžete v klientské zóně nastavit výchozí rozměry. Doporučujeme ovšem zasílat, protože v případě nepřesných rozměrů vás může dopravce zpětně finančně kontaktovat. Rozměr zásilky délka (v cm). Povinný pro doručování na polské Paczkomaty. Povinný pro doručování na polské Paczkomaty. Případně si 31

32 delivery_costs_eur delivery_costs content_data můžete v klientské zóně nastavit výchozí rozměry. Doporučujeme ovšem zasílat, protože v případě nepřesných rozměrů vás může dopravce zpětně finančně kontaktovat. Cena za přepravu, kterou zaplatí příjmce v EUR. Povinné při doručení na Ukrajinu (UA). Pokud máte u všech zásilek stejnou cenu přepravného, můžete si ji nastavit ve své klientské zóně. Pokud je doprava zdarma, zašlete jako hodnotu 0. Cena za přepravu, kterou zaplatí příjmce v měně cílové země (pro UA tedy v UAH). Povinné při doručení na Ukrajinu (UA). Pokud máte u všech zásilek stejnou cenu přepravného, můžete si ji nastavit ve své klientské zóně. Pokud je doprava zdarma, zašlete jako hodnotu 0. Data pro celní řízení, povinná pro zásilky mířící na Ukrajinu (UA), do Švýcarska (CH) a do Ruska (RU). Jednotlivé položky zabalené v zásilce je potřeba dopodrobna popsat dle následujících atributů: content_name_en název produktu anglicky (povinný pro UA, CH, RU) content_name název produktu v jazyce cílové země (povinný, tzn. pro UA ukrajinsky, pro CH německy, pro RU - rusky) content_weight váha položky v kg (povinná položka pro doručení do CH) content_pieces počet produktů (povinné pro UA, CH, RU) content_price_eur hodnota jednoho produktu v EUR (povinné pro UA, RU, CH) content_price hodnota jednoho produktu v měně cílové země (tzn. pro UA v UAH, pro CH v CHF, pro RU v RUB) content_ean EAN produktu (povinný pro CH, UA, RU) content_customs_code celní kód (8mi místný, povinný pro CH, RU, UA) content_country - ISO alpha-2 kód země původu (povinný pro CH, UA, RU) content_invoice_number číslo faktury, které se váže k produktu (povinný pro CH) content_invoice_issue_date datum vystavení faktury (formát YYYY-MM-DD, povinný pro CH) Ukázka zápisu v JSONu pro balík obsahující 2 produkty: "content_data": [{ "content_name_en": "Name EN 1", "content_name": "Name UA 1", "content_weight": 0.05, "content_price_eur": 100, "content_ean": " ", "content_customs_code": " ", "content_country": "CZ"},{ "content_name_en": "Name EN 02", "content_name": "Name UK 02", "content_weight": 0.55, "content_price_eur": 300, 32

33 "content_ean": " ", "content_customs_code": " ", "content_country": "SK"}] rec_region Název okresu/kraje, kam se zásilka posílá. Používá se u zásilek mířících do Rumunska (judet) případně je možné zasílat v rec_city (formát město;judet například TIMISOARA;Timis ) 33

34 Geis Parcel balíková přeprava Podporované služby: Geis Parcel CZ firemní, soukromé a mezistátní zásilky, Geis Point. API endpoint přepravce: API endpoint metody ADD: klíč povinná popis rec_name Jméno a příjmení příjemce. rec_firm rec_phone Název firmy příjemce. Telefonní číslo příjemce, povinné pro soukromé zásilky (B2C), formát čísla (je potřeba zadávat i s předvolbou): +AAAXXXYYYZZZ rec_ příjemce. rec_street Ulice příjemce. Není potřeba zasílat u service_type = 6 (doručení na G-Point). rec_city rec_zip rec_country service_type Adresační město příjemce. Není potřeba zasílat u service_type = 6 (doručení na G-Point). PSČ příjemce, uvádějte bez mezer ve formátu XXXXX. Není potřeba zasílat u service_type = 6 (doručení na G-Point). Kód země příjemce dle ISO alpha-2 (viz. výchozí hodnotou je Česká republika (CZ). Jednotlivé země, kam se dá přes určitou službu (service_type) zasílat, naleznete v metodě COUNTRIES4SERVICE. Není potřeba zasílat u service_type = 6 (doručení na G-Point). ID služby, kterou se bude zásilka posílat: 1 Soukromá zásilka (B2C) 2 Firemní zásilka 3 Mezinárodní zásilka (B2B) 6 Geis Point 7 Garantované doručení (GAR) 8 Doručení do 12. hodin (D12) 9 Mezinárodní zásilka (B2C) Seznam dostupných služeb je k nalezení přes metodu SERVICES. 34

35 branch_id price ID pobočky Geis Point (CZ nebo SK), na níž je zásilka určena k výdeji (seznam dostupný přes metodu BRANCHES se service_type 6 ). Udaná cena celé zásilky, pokud zasíláte zásilku s celkovou cenou nad Kč a chcete jí připojistit, je tento atribut povinný. cod_price Výše dobírky, povinná u dobírkových zásilek. Měna dobírky dle ISO 4217 kódu cod_currency (pro Kč je například CZK, pro euro je EUR), povinná položka u všech dobírkových služeb. vs Variabilní symbol platby, povinný u dobírkových zásilek. eid Unikátní ID balíku v rámci e-shopu(ů), které využívají stejné konfigurační údaje přepravce. order_number Povinný pro sdružené zásilky, u samostatných se nemusí uvádět. Reálné číslo objednávky (zobrazuje se na přepravních štítcích a předává se real_order_id del_insurance credit_card del_exworks weight note reference return_track return_full_errors _notification datově přepravci, pokud není vyplněno, tak se předává eid), doporučujeme ho tedy vyplňovat, pokud do povinného eid zasíláte jiné hodnoty. Přijímané hodnoty jsou TRUE(boolean) a 1 (string/integer). Uvádějte jen u zásilek s celkovou hodnotou nad Kč, které chcete připojistit, zároveň je potřeba zaslat v atributu price celkovou hodnotu zásilky na tu se pak připojišťuje.. Příznak (0 ne / 1- ano), že zákazník může dobírku zaplatit kartou. Služba, při které platí náklady za přepravu příjemce datový typ boolean (true/false), výchozí hodnotou je false. Váha balíku v kg, datový typ float. Poznámka přepravci (maximální délka 57 znaků). Zákaznická reference, maximální délka 20 alfanumerických znaků. Pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou v odpovědi metody zadejte boolean (TRUE) nebo hodnotu 1. Pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean). Pro využití služby příjemci zašlete hodnotu 1 nebo boolean (TRUE), pro využití je potřeba mít službu aktivovánu na straně přepravce. 35

36 bank_account_number IBAN bankovního účtu, na který má být zaslána vybraná dobírka, uvádí se pouze v případě, že má být dobírka zaslána na jiný, než výchozí účet zvolený v administraci přepravce. 36

37 Geis Cargo paletová přeprava Podporované služby: Geis Cargo CZ a Geis Cargo mezinárodní přeprava. API endpoint přepravce: API endpoint metody ADD: klíč povinná popis rec_name Jméno a příjmení příjemce. rec_firm Název firmy příjemce. rec_phone Telefonní číslo příjemce, povinné pro soukromé zásilky (B2C) a doplňkové služby telefonické avízo (AVI) a SMS avízo (SMS), formát čísla: +420XXXYYYZZZ. rec_ příjemce. rec_street Ulice příjemce. rec_city Město příjemce. rec_zip PSČ příjemce, uvádějte bez mezer ve formátu XXXXX. Kód země příjemce dle ISO alpha-2 (viz. rec_country service_type price výchozí hodnotou je Česká republika (CZ). Jednotlivé země, kam se dá přes určitou službu (service_type) zasílat, naleznete v metodě COUNTRIES4SERVICE. ID služby, kterou se bude zásilka posílat: 4 Vnitrostátní paletová zásilka B2B 5 Mezinárodní paletová zásilka B2B 10 Vnitrostátní paletová zásilka B2C 11 Mezinárodní paletová zásilka B2C Seznam dostupných služeb je k nalezení přes metodu SERVICES. Udaná cena celé zásilky. cod_price Dobírková částka, povinná u všech dobírkových zásilek. Měna dobírky dle ISO 4217 kódu cod_currency (pro Kč je například CZK, pro euro je EUR), povinná položka u všech dobírkových služeb. 37

38 vs Variabilní symbol platby, povinný u dobírkových zásilek. eid Unikátní ID balíku v rámci expedičních míst, které využívají stejné konfigurační údaje přepravce. order_number Povinný pro sdružené zásilky, u samostatných se nemusí uvádět. Reálné číslo objednávky (zobrazuje se na přepravních štítcích a předává se real_order_id mu_type pieces_count datově přepravci, pokud není vyplněno, tak se předává eid), doporučujeme ho tedy vyplňovat, pokud do povinného eid zasíláte jiné hodnoty. Kód manipulační jednotky (jejich seznam s názvy získáte metodou MANIPULATIONUNITS). Počet nákladových kusů stejné manipulační jednotky (např. pokud je součástí zásilky 5 amerických palet, bude hodnota 5), pokud je nákladový kus od manipulační jednotky pouze 1, není potřeba uvádět hodnotu. weight Celková váha nákladového kusu/kusů v kg, datový typ float. volume Celkový objem nákladového kusu/kusů v m3. del_exworks vdl_service sms_notification phone_notification b2c_notification note_driver note_recipient reference return_track return_full_errors get_piece_numbers Služba platba příjemcem (datový typ boolean (true/false). Služba DL zpět (datový typ boolean true/false) naskenování dodacích listů podepsaných příjemcem a jejich zpřístupnění odesílateli. Služba SMS avízo (datový typ boolean true/false). Služba telefonické avízo (datový typ boolean true/false). Služba B2C soukromá adresa (datový typ boolean true/false). Poznámka řidiči (přenáší se datově, není vidět na štítku) dlouhá maximálně 62 znaků. Poznámka příjemci (přenáší se datově a je vidět i na štítku) dlouhá maximálně 62 znaků. Zákaznická reference, maximální délka 20 alfanumerických znaků. Pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou v odpovědi metody zadejte boolean (TRUE) nebo hodnotu 1. Pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean). Pro navrácení čísel kusů jednotlivých nákladových kusů manipulačních jednotek zašlete hodnotu 1 nebo TRUE (boolean). 38

39 del_insurance Přijímané hodnoty jsou TRUE(boolean) a 1 (string/integer). Uvádějte jen u zásilek s celkovou hodnotou nad Kč, které chcete připojistit, zároveň je potřeba zaslat v atributu price celkovou hodnotu zásilky na tu se pak připojišťuje. content Textový obsah zásilky je potřeba pokud zašlete del_insurance = TRUE. IBAN bankovního účtu, na který má být zaslána vybraná dobírka, uvádí se bank_account_number pouze v případě, že má být dobírka zaslána na jiný, než výchozí účet zvolený v administraci přepravce. 39

40 Uloženka Podporované služby: Uloženka, Zmluvný balík s poistením Slovenská pošta, DPD Classic na Slovensko, DPD Private pro ČR a SK, DPD Parcel Shop, Balík do ruky Česká pošta a Balík na poštu Česká pošta, Uloženka Partner, Doručení na adresu (D+1), Expres Kurýr SK, Expres na poštu SK, BalíkoBOX SK, Depo SK. API endpoint přepravce: API endpoint metody ADD: klíč povinná popis ID pobočky, na níž je zásilka určena k výdeji. branch_id service_type eid Povinné pro služby číslo 1, 5, 10, 11, 20, 21 a 22. Pro službu Balík na poštu (7) je zde potřeba vyplnit PSČ pošty bez mezer. Číslo služby (1 Uloženka, 2 Zmluvný balík s poistením Slovenská pošta, 3 DPD Classic na Slovensko, 4 DPD Private pro ČR a SK, 5 DPD ParcelShop, 6 Balík do ruky Česká pošta, 7 Balík na poštu Česká pošta, 11 Partner, 17 Doručení na adresu D+1, 19 Expres Kurýr SK, 20 Expres na poštu SK, 21 BalíkoBOX SK, 22 Depo SK). Seznam dostupných služeb je k nalezení přes metodu SERVICES. Unikátní ID balíku v rámci e-shopu(ů), které využívají stejné konfigurační údaje přepravce. rec_name Jméno a příjmení příjemce. rec_firm Název firmy příjemce. rec_phone Telefonní číslo příjemce, povinné při využití služby oznámení pomocí SMS nebo jiném telefonickém kontaktu formát čísla: +420XXXYYYZZZ Povinné pro služby číslo 1, 4, 5, 6, 7, 11, 17 a 19. rec_ příjemce. Povinné pro služby číslo 3, 4, 6, 17 a 19. rec_street Ulice příjemce. Povinné pro služby číslo 2, 3, 4, 6, 17 a 19. rec_city Město příjemce. Povinné pro služby číslo 2, 3, 4, 6, 17 a 19. rec_zip rec_country PSČ příjemce, uvádějte bez mezer ve formátu XXXXX. Povinné pro služby číslo 2, 3, 4, 6, 17 a 19. Kód země příjemce dle ISO alpha-2 (viz. výchozí hodnotou je Česká 40

41 price cod_price cod_currency vs credit_card order_number real_order_id require_full_age password weight note return_track return_full_errors republika (CZ). Udaná cena zásilky (tedy všech balíků v zásilce). Povinná pro službu 2, 19. Cena dobírky celé zásilky, u sdružených zásilek uvádějte sečtenou dobírkovou hodnotu všech balíků do zásilky s prvním order_number (order_number => 1), u zbylých order_number uveďte nulovou cenu! U služby DPD Classic do EU (service_type = 3) lze posílat dobírkové zásilky pouze do SK, RO a GB. Měna dobírky dle ISO 4217 kódu (pro Kč je například CZK, pro euro je EUR), povinná položka u všech dobírkových zásilek. Variabilní symbol platby, uvádí se poté jako variabilní symbol u vyplácených dobírek. Doporučujeme ho tedy vyplňovat u všech dobírkových zásilek. Příznak (0 ne / 1- ano), že zákazník může dobírku zaplatit kartou. Platbu kartou je možné využít jen u služby 1. Povinný pro sdružené zásilky, u samostatných se nemusí uvádět. Pozor u služeb České pošty (6 a 7), DPD ParceShop (5) a Slovenské pošty (2, 19) nelze posílat více balíkové zásilky! reálné číslo objednávky (zobrazuje se na přepravních štítcích a předává se datově přepravci, pokud není vyplněno, tak se předává eid), doporučujeme ho tedy vyplňovat, pokud do povinného eid zasíláte jiné hodnoty Příznak (0 ne / 1- ano), že se má při předání ověřovat plnoletost. Ověření plnoletosti je možné využít jen u služby 1. Heslo pro ověření při předání zásilky, maximální délka 99 znaků. Heslo je možné využít jen u služby 1. Váha balíku v kg, datový typ float. Povinná pro služby 2, 6, 7, 17, 19. poznámka přepravci (maximální délka 75 znaků) pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou v odpovědi metody zadejte boolean (TRUE) nebo hodnotu 1 pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean) 41

42 Intime Podporované služby: Small Colli 24-CZ, Medium Colli 24-CZ, Large Colli 24-CZ, Extra Large Colli 24- CZ, Poštomat CZ, Poštomat SK, Large Colli 48-SK, Parcel EU a Parcel EU+. API endpoint přepravce: API endpoint metody ADD: klíč povinná popis ID poštomatu jejich seznam je dostupný přes metodu BRANCHES (jako id branch_id service_type eid zasílejte hodnotu name, paříklad CZPRA0942 jakožto jednoznačný identifikátor) Číslo služby (1 Small Colli 24-CZ, 2 Medium Colli 24-CZ, 3 Large Colli 24-CZ, 4 Poštomat CZ, 5 Poštomat SK, 6 Large Colli 48-SK, 7 Extra Large Colli 24-CZ, 8 Parcel EU, 9 Parcel EU+). Seznam dostupných služeb je k nalezení přes metodu SERVICES. Unikátní ID balíku v rámci e-shopu(ů), které využívají stejné konfigurační údaje přepravce. rec_name Jméno a příjmení příjemce. rec_firm Název firmy příjemce. rec_phone Telefonní číslo příjemce, povinné při využití služby oznámení pomocí SMS nebo jiném telefonickém kontaktu formát čísla: +420XXXYYYZZZ Povinné pro služby číslo 4 a 5 (Poštomaty CZ a SK). rec_ příjemce. rec_street Ulice příjemce. rec_city Město příjemce. rec_zip PSČ příjemce, uvádějte bez mezer ve formátu XXXXX. rec_country price del_insurance Kód země příjemce dle ISO alpha-2 (viz. Udaná cena zásilky (tedy všech balíků v zásilce). Povinná pokud se zasílá připojištění (del_insurance TRUE). Připojištění, datový typ boolean (TRUE) nebo hodnota 1 (string/integer). 42

43 cod_price cod_currency vs order_number Do 50ti tisíc Kč jsou zásilky připojištěny automaticky, bere se v potaz až u zásilek s hodnotou nad tento limit. Cena dobírky celé zásilky, u sdružených zásilek uvádějte sečtenou dobírkovou hodnotu všech balíků do zásilky s prvním order_number (order_number => 1), u zbylých order_number uveďte nulovou cenu! Země, do kterých se dají zasílat doběrečné zásilky, naleznete v metodě COD4SERVICES. Měna dobírky dle ISO 4217 kódu (pro Kč je například CZK, pro euro je EUR), povinná položka u všech dobírkových zásilek. Variabilní symbol platby, uvádí se poté jako variabilní symbol u vyplácených dobírek. Doporučujeme ho tedy vyplňovat u všech dobírkových zásilek. Povinný pro sdružené zásilky, u samostatných se nemusí uvádět. Pozor služby Poštomat CZ a SK (ID 4 a 5) nelze posílat více balíkové zásilky! weight NE Celková váha zásilky v kg, datový typ float. note return_track poznámka přepravci (maximální délka 75 znaků) pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou v odpovědi metody zadejte boolean (TRUE) nebo hodnotu 1 Příznak (0 ne / 1- ano), že se má při předání ověřovat plnoletost příjemce. require_full_age return_full_errors V případě, že klient tuto možnost nemá povolenou od přepravce, vrací se v response require_full_age = 413 pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean) Měna udané ceny (price). Pokud není zaslána, bere se jako výchozí měna ins_currency zaslaná v cod_currency. Pokud je hodnota ins_currency rozdílná, přepočítá se hodnota udané ceny dle aktuálního kurzu ČNB. Zásilky mířící po CZ připojišťuje Intime v CZK, do EU pak v EUR. 43

44 GLS Podporované služby: Business Parcel (balíkové doručení + FlexDelivery/FlexDeliverSMS), ShopDelivery Service (doručení na GLS ParcelShop výdejní místa) a Express Parcel. API endpoint přepravce: API endpoint metody ADD: klíč povinná popis ID pobočky, na níž je zásilka určena k výdeji v rámci služby ShopDelivery, při branch_id doručení do domu je nepovinná. Seznam aktuálně aktivních výdejen získáte přes metodu BRANCHES. rec_name Jméno a příjmení příjemce. ID služby, kterou se bude zásilka posílat: 1 Business Parcel (doručení do ruky) service_type rec_firm rec_phone 2 ShopDelivery Service (doručení na výdejní místo) 3 Express Parcel (expresní zásilka) Seznam dostupných služeb je k nalezení přes metodu SERVICES. Název firmy příjemce. Telefonní číslo příjemce, povinné při využití služby oznámení pomocí SMS nebo jiném telefonickém kontaktu formát čísla: +420XXXYYYZZZ rec_ příjemce. rec_street Ulice příjemce (při doručení na GLS ParcelShop není potřeba). rec_city Adresační město příjemce (při doručení na GLS ParcelShop není potřeba). rec_zip rec_country PSČ příjemce, uvádějte bez mezer ve formátu XXXXX (při doručení na GLS ParcelShop není potřeba). Kód země příjemce dle ISO alpha-2 (viz. výchozí hodnotou je Česká republika (CZ), pro zásilky mimo ČR je toto pole povinné. price Udaná cena zásilky. Používá se pro účely připojištění (del_insurance). cod_price cena dobírky, povinná u všech dobírkových služeb měna dobírky dle ISO 4217 kódu (pro cod_currency Kč je například CZK, pro euro je EUR), povinná položka u všech dobírkových služeb 44

45 vs variabilní symbol platby, povinný pro dobírkové zásilky eid unikátní ID balíku v rámci e-shopu(ů), které využívají stejné konfigurační údaje přepravce order_number povinný pro sdružené zásilky, u samostatných se nemusí uvádět real_order_id weight return_track return_full_errors note reálné číslo objednávky váha balíku v kg (datový typ float), propisuje se na štítek pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou v odpovědi metody zadejte boolean (TRUE) nebo hodnotu 1 pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean) Poznámka přepravci maximální délka 64 znaků. Indikátor připojištění. Přijímá hodnoty TRUE (boolean) nebo 1 (string / del_insurance integer). Zásilka se připojišťuje na výši udané ceny (price). V klientské zóně si můžete nastavit automatické připojišťování všech zásilek (pak nemusíte zasílat tento atribut). Měna udané ceny (price). Pokud není zaslána, bere se jako výchozí měna ins_currency zaslaná v cod_currency. GLS připojišťuje zásilky v měně země odesilatele. Tzn. pro zásilky z CZ se používá jako měna CZK, pro zásilky z SK se používá jako měna EUR. Pokud je hodnota ins_currency rozdílná, přepočítá se hodnota udané ceny dle aktuálního kurzu ČNB. Výměnná zásilka (ke klasickému štítku se vrátí ještě štítek do krabice + se swap navrátí carrier_id_swap). Přijímané hodnoty jsou 1 (string nebo integer) nebo true (boolean). 45

46 Toptrans paletová přeprava Podporované služby: Toptrans 24 hodin (Standard), Toptime, Privat, Weekend, Osobní odběr a Po avizaci. Každá objednávka (EID eshop_id) může mít v systému maximálně 1 záznam carrier_id z důvodu maximálního počtu různých druhů manipulačních jednotek (mu_type_*), který je 3. Proto u tohoto přepravce není atribut order_number. API endpoint přepravce: API endpoint metody ADD: klíč povinná popis rec_name Jméno a příjmení příjemce. rec_firm Název firmy příjemce. rec_phone Telefonní číslo příjemce, formát čísla: +ABCXXXYYYZZZ. rec_ příjemce. rec_street Ulice příjemce. rec_city Město příjemce. rec_zip PSČ příjemce, uvádějte bez mezer ve formátu XXXXX. Kód země příjemce dle ISO alpha-2 (viz. rec_country service_type price výchozí hodnotou je Česká republika (CZ). ID služby, kterou se bude zásilka posílat: 1 24 hodin (Standard), 2 Toptime, 3 Privat, 4 Weekend, 5 Osobní odběr, 6 Po avizaci Seznam dostupných služeb je k nalezení přes metodu SERVICES. Udaná cena celé zásilky. cod_price Dobírková částka, povinná u všech dobírkových služeb. cod_currency Měna dobírky dle ISO 4217 kódu (pro Kč je například CZK, pro euro je EUR), povinná položka u všech dobírkových zásilek. vs Variabilní symbol platby, povinný u dobírkových zásilek. eid Unikátní ID balíku v rámci e-shopu(ů), které využívají stejné konfigurační údaje přepravce. 46

47 real_order_id mu_type_one pieces_count_one mu_type_two pieces_count_two mu_type_three pieces_count_three Reálné číslo objednávky (předává se datově přepravci), doporučujeme ho tedy vyplňovat, pokud do povinného eid zasíláte jiné hodnoty. Kód manipulační jednotky (seznam s názvy získáte metodou MANIPULATIONUNITS). Počet nákladových kusů stejné manipulační jednotky (např. pokud je součástí zásilky 5 amerických palet, bude hodnota 5), pokud je nákladový kus od manipulační jednotky pouze 1, není potřeba uvádět hodnotu. Viz mu_type_one v případě jiných man. jednotek v zásilce. Viz pieces_count_one pro mu_type_two. Viz mu_type_one v případě dalších man. jednotek v zásilce. Viz pieces_count_one pro mu_type_three. weight Celková váha nákladového kusu/kusů v kg, datový typ float. volume Celkový objem zásilky v m3. note Poznámka přepravci (maximální délka 50 znaků). comfort_service Doplňková služba TOP COMFORT (pro využití zašlete hodnotu 1). comfort_plus_service Doplňková služba TOP COMFORT Plus (pro využití zašlete hodnotu 1). swap wrap_back_count wrap_back_note vdl_service over_dimension adr_service delivery_date return_track Obousměrná zásilka (1, 2 na sběrný dvůr). Počet vratných obalů (integer celé číslo). Popis vratných obalů (max. délka 40 znaků). Dodací listy zpět (0 NE, 1 ). Zásilka nadrozměr (0 NE, 1 ). Režim přepravy ADR (0 NE, 1 ). Pro doplnění obsahu slouží atribut adr_content. Datum plánované realizace doručení zásilky, uvádí se jako datum ve formátu YYYYmm-dd (např , ). Pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou v odpovědi metody zadejte boolean (TRUE) nebo hodnotu 1. Celé číslo bankovního účtu, na který má být zaslána vybraná dobírka (formát bank_account_number <předčíslí>-<číslo_účtu>/<kód_banky>), uvádí se pouze v případě, že má být dobírka zaslána na jiný, než výchozí účet zvolený v administraci přepravce Toptrans. 47

48 return_full_errors get_piece_numbers Pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean). Pro navrácení čísel kusů jednotlivých nákladových kusů manipulačních jednotek zašlete hodnotu 1 nebo TRUE (boolean). content_one Obsah maniplačních jednotek 1 (mu_type_one), maximální počet znaků 40. content_two Obsah maniplačních jednotek 2 (mu_type_two), maximální počet znaků 40. content_three Obsah maniplačních jednotek 3 (mu_type_three), maximální počet znaků 40. phone_delivery_notification phone_order_notification Pro telefoní avizaci vykládky zašlete hodnotu 1 nebo TRUE (boolean). Pro telefoní avizaci nakládky zašlete hodnotu 1 nebo TRUE (boolean). comfort_exclusive_service Doplňková služba TOP COMFORT Exclusive (pro využití zašlete hodnotu 1). Povinný v případě, že je adr_service = 1. Jednotlivé ADR položky v zásilce je potřeba dopodrobna popsat dle následujících atributů: adr_pieces_count počet kusů dané ADR jednotky, povinný adr_un id ADR jednotky (seznam získáte z metody ADRUNITS), povinný adr_weight váha (kg) jednotek, povinný pokud není vyplněno adr_volume adr_volume objem (m3) jednotek, povinný pokud není vyplněno adr_weight Ukázka zápisu v JSONu pro balík obsahující 2 různé ADR jednotky (adr_un): adr_content "adr_content":[ { "adr_pieces_count":2, "adr_un":4, "adr_weight":3.8, "adr_volume":0.85 }, { "adr_pieces_count":3, "adr_un":12, "adr_weight":5.8 "adr_volume":0.35 } ] 48

49 Pošta bez hranic (PbH) Podporované služby: DHL, GLS, UPS, Slovenská pošta, Transoflex, Maďarská pošta, Cargus, Rakouská pošta (doručení na adresu/výdejní místa), Česká pošta Balík do ruky, Česká pošta Balík na poštu, PPL, DPD, FAN Courier, Poslká pošta, Inpost Kurier, Hermes, Speedy, Colissimo, Meest a Nova Poshta. Na rozdíl od ostatních balíkových přeprav nelze z důvodu nepodporování přepravce vytvářet sdružené zásilky! Každý balíček tedy musí mít své unikátní EID. API endpoint přepravce: API endpoint metody ADD: klíč povinná popis rec_name jméno a příjmení příjemce ID služby, kterou se bude zásilka posílat: DHL (1), GLS (2), UPS (3), Slovenská pošta (4), Transoflex (5), Maďarská pošta (6), Cargus (7), Rakouská pošta (8), Česká pošta Balík do ruky (9), Česká pošta service_type rec_firm Balík na poštu(10), PPL (11), DPD(12), Polská pošta (13), polský Inpost Kurier (14), FAN Courier (15), Hermes (16), Speedy (17), Colissimo (18), Meest (19), Nova Poshta (20). Seznam dostupných služeb je k nalezení přes metodu SERVICES. název firmy příjemce rec_phone NE telefonní číslo příjemce, formát čísla: +AAAXXXYYYZZZ rec_ příjemce rec_street rec_city rec_region rec_zip ulice příjemce (v případě doručení na výdejní místo DHL DE zde zadejte ulici výdejního místa získaného z metody BRANCHLOCATOR) město příjemce, (v případě doručení na výdejní místo DHL DE zde zadejte město výdejního místa získaného z metody BRANCHLOCATOR) jméno okresu/kraje, kam se zásilka posílá, povinný pro zásilky do Rumunska (judet) RO FAN - RO Cargus - PSČ příjemce (v případě doručení na výdejní místo DHL DE zde zadejte PSČ výdejního místa získaného z metody BRANCHLOCATOR)/ ID lokality, uvádějte bez mezer. Není povinné u doručení do Rumunska (RO). ID lokality se uvádí namísto PSČ u doručení přes Speedy do BG (service_type 49

50 rec_country price = 17 ), u doručení do UA přes Meest (service_type = 19 ) a u doručení do UA přes Nova Poshta (service_type = 20 ). Seznamy lokalit jsou dostupné ve formě XML kvůli své velikosti: BG Speedy - UA Meest přímo od přepravce (nejaktuálnější) - (údaje pro API komunikaci naleznete v klientské zóně) Nova Poshta přímo od přepravce (nejaktuálnější) - (údaje pro API komunikaci naleznete v klientské zóně) kód země příjemce dle ISO alpha-2 (viz. udaná cena zásilky, v případě zásilek na Ukrajinu (UA) se udaná cena bere jako součet content_price_eur cod_price cena dobírky, povinná u všech dobírkových služeb měna dobírky dle ISO 4217 kódu cod_currency vs eid real_order_id return_track return_full_errors content_data (pro Kč je například CZK, pro euro je EUR), povinná položka u všech dobírkových služeb variabilní symbol platby unikátní ID balíku v rámci e-shopu(ů), které využívají stejné konfigurační údaje přepravce reálné číslo objednávky (faktury) pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou v odpovědi metody zadejte boolean (TRUE) nebo hodnotu 1 pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean) Data pro celní řízení, povinná pro zásilky mířící na Ukrajinu (UA). Jednotlivé položky zabalené v zásilce je potřeba dopodrobna popsat dle následujících atributů: content_name_en název produktu anglicky content_name_ua název produktu ukrajinsky content_weight váha položky v kg (nepovinná položka) content_pieces počet produktů (nepovinná položka) 50

51 content_price_eur hodnota jednoho produktu v EUR content_ean EAN produktu content_customs_code celní kód content_country - ISO alpha-2 kód země původu Ukázka zápisu v JSONu pro balík obsahující 2 produkty: "content_data": [{ "content_name_en": "Name EN 1", "content_name_ua": "Name UA 1", "content_weight": 0.05, "content_price_eur": 100, "content_ean": " ", "content_customs_code": " ", "content_country": "CZ"},{ "content_name_en": "Name EN 02", "content_name_ua": "Name UK 02", "content_weight": 0.55, "content_price_eur": 300, "content_ean": " ", "content_customs_code": " ", "content_country": "SK"}] invoice_number Číslo faktury, povinné pro zásilky na Ukrajinu (UA). ID pobočky, na níž je zásilka určena k výdeji. Seznam aktuálně aktivních výdejen pro jednotlivé služby získáte přes metodu BRANCHES. Doručení na pobočku umožňují následující služby: Nova Poshta (service_type = 20 ), Fan branch_id open_before_payment test_before_payment del_insurance Courier (service_type = 15 ), Maďarská pošta (service_type = 6 ), Rakouská pošta (service_type = 8 ). Výdejní místa v Německu (DE) nejsou předávána oproti ostatním službám přes metodu BRANCHES, ale metodou BRANCHLOCATOR (získání seznamu aktuálních výdejních míst pro zadaná kritéria město + případně PSČ / ulice). Doplňková služba u přepravce Speedy do BG (service_type = 17 ). Zákazník si může otevřít balík a zkontrolovat obsah před převzetím. Pro využítí zašlete hodnotu 1, nebo boolean TRUE. Doplňková služba u přepravce Speedy do BG (service_type = 17 ). Zákazník si může vyzkoušet zboží před převzetím. Pro využítí zašlete hodnotu 1, nebo boolean TRUE. Připojištění, datový typ boolean (TRUE) nebo hodnota 1 (string/integer). rec_house_number Číslo popisné, pokud pro danou adresu neexistuje doplňte "0". 51

52 rec_block rec_enterance rec_floor rec_flat_number Identifikátor bloku (přenáší se jen u přepravce BG Speedy). Číslo vchodu (přenáší se jen u přepravce BG Speedy). Číslo podlaží (přenáší se jen u přepravce BG Speedy). Číslo bytu / apartmánu (přenáší se jen u přepravce BG Speedy). rec_name_patronymum Patronymum - otčestvo. Povinný pro přepravce Nova Poshta. ID lokality, uvádějte bez mezer. Pokud chcete zasílat ID lokality a zároveň PSČ příjemce (rec_zip), zasílejte ID lokality do tohoto atributu. Přepravci se pak předají oba údaje. ID lokality se uvádí u doručení přes Speedy do BG (service_type = 17 ), u rec_locale_id doručení do UA přes Meest (service_type = 19 ). Seznamy lokalit jsou dostupné ve formě XML kvůli své velikosti: weight rec_id BG Speedy - UA Meest přímo od přepravce (nejaktuálnější) - (údaje pro API komunikaci naleznete v klientské zóně) Váha zásilky v kg. Povinná u zásilek, ke kterým mají být vytištěny štítky cílového přepravce + navráceno číslo zásilky v rámci cílového přepravce (aktuálně lze využít například u zásilek německého DHL). Pro využití možnosti zasílání na výdejní místa v Německu musí být adresát (příjemce) registrován na stránkách německého DHL. Po registraci získá své unikátní Post Number, které je nutné k zasílání na výdejní místa. Bez tohoto ID není možné zasílat na výdejní místa. Registraci je možné udělat zde. 52

53 DHL Express Podporované služby: Express Worlwide zásilky (pokrývá doručení zásilek do 220 států světa), Express Worldwide dokumenty (pokrývá doručení dokumentů do 220 států světa), Express Worldwide 9:00, Express Worldwide 12:00, Economy Select (pozemní přeprava, pokrývá EU + Norsko a Švýcarsko), Domestic Express a Domestic Express 12:00 (vnitrostátní přeprava). Oproti ostatním přepravcům, se vytvářejí sdružené zásilky pomocí atributu pieces_count tedy zadáním počtu balíčků v zásilce celá zásilka je tedy pod jedním záznamem metody ADD. Další důležitou odlišností je nemožnost zasílat dobírkové zásilky! Seznamy PSČ z metody ZIPCODES jsou orientační, protože DHL bere v potaz při vytváření zásilky také dostupnost vlastních zdrojů. Štítky mají větší rozměry, proto se na A4 vejdou pouze 2. Také rozměr PDF pro Zebra tisk je větší (104x190), proto je potřeba pořídit si kotouče s těmito rozměry. API endpoint přepravce: API endpoint metody ADD: klíč povinná popis rec_name jméno a příjmení příjemce ID služby, kterou se bude zásilka posílat: Worlwide zásilky (1), Express Worldwide dokumenty (2), Express Worldwide 9:00 service_type rec_firm (3), Express Worldwide 12:00 (4), Economy Select (5), Domestic Express 12:00 (6), Domestic Express (7). Seznam dostupných služeb je k nalezení přes metodu SERVICES. název firmy příjemce rec_phone telefonní číslo příjemce, formát čísla: +AAAXXXYYYZZZ rec_ příjemce rec_street ulice příjemce rec_city adresační město příjemce rec_zip rec_country PSČ příjemce, uvádějte bez mezer. Pro cílově země (AE, AF,AG,AI,AL,AN,AO,AW,BB,BF,BH,BI,BJ,BM,BO,BS,BT,BW,BZ,CD,CF,CG, CI,CK,CL,CM,CO,CR,CV,DJ,DM,DO,EC,EG,ER,ET,FJ,FK,GA,GD,GH,GI,GM, GN,GQ,GT,GW,GY,HK,HN,HT,IE,IQ,IR,JM,JO,KE,KH,KI,KM,KN,KP,KW,KY, LA,LB,LC,LK,LR,LS,LY,ML,MM,MO,MR,MS,MT,MU,MW,MZ,NA,NE,NG,NI,NP, NR,NU,OM,PA,PE,PF,PY,QA,RW,SA,SB,SC,SD,SL,SN,SO,SR,SS,ST,SV,SY, TC,TD,TG,TL,TO,TT,TV,TZ,UG,UY,VC,VE,VG,VN,VU,WS,XA,XB,XC,XE,XL, XM,XN,XS,YE,ZM,ZW) je tato položka nepovinná. kód země příjemce dle ISO alpha-2 (viz. 53

54 price cod_currency eid udaná cena zásilky (předává se pro celní účely u zásilek mimo EU + v případě připojištění nad rámec standardního pojištění) měna udané ceny dle ISO 4217 kódu (pro Kč je například CZK, pro euro je EUR), povinná položka unikátní ID balíku v rámci e-shopu(ů), které využívají stejné konfigurační údaje přepravce pieces_count počet balíčků v zásilce (pokud není vyplněno, přidá se k zásilce hodnota 1) content popis obsahu zásilky, maximální délka 90 znaků real_order_id weight reálné číslo objednávky, předává se jako reference Hmotnost celé zásilky. V případě nezaslání se uvede výchozí hodnota z konfigurace. indikátor připojištění nad rámec standardního pojištění, akceptované hodnoty jsou boolean (TRUE) nebo hodnota 1, stejně tak je možno použít metodu services a v ní zaslat hodnotu II. Standardní výše pojištění zásilek: del_insurance Express produkty 19 SDR / kg zásilky (SDR je konvertibilní měna, kterou stanovuje ČNB) Economy Select 8,33 SDR /kg zásilky (SDR je konvertibilní měna, kterou stanovuje ČNB) přepravné, clo a DPH hradí příjemce (nutno konzultovat s DHL předem), del_exworks akceptované hodnoty jsou boolean (TRUE) nebo hodnota 1, stejně tak je možné zasílat tuto službu v atribut terms_of_trade s hodnotou EXW speciální doplňkové služby: services HB nebezpečné zboží baterie: Lithium ion batteries in compliance with Section II of P.I. 965 CAO. Obsah těchto zásilek je nutno předem konzultovat s DHL. HD nebezpečné zboží baterie se zařízením: Lithium ion batteries in compliance with Section II of P.I Obsah těchto zásilek je nutno předem konzultovat s DHL. HV nebezpečné zboží baterie uvnitř zařízení: Lithium ion batteries in compliance with Section II of P.I Obsah těchto zásilek je nutno předem konzultovat s DHL. HM nebezpečné zboží baterie se zařízením: Lithium metal batteries in compliance with Section II of P.I Obsah těchto zásilek je nutno předem 54

55 konzultovat s DHL. HW nebezpečné zboží baterie uvnitř zařízení: Lithium metal batteries in compliance with Section II of P.I Obsah těchto zásilek je nutno předem konzultovat s DHL. HN nebezpečné zboží. Obsah těchto zásilek je nutno předem konzultovat s DHL. DD příplatek za INCOTERM DDP v případě zemí mimo EU, kde přepravné, CLO a DPH hradí odesílatel. WY Paperless trade. Zaslání faktur pro celní účely elektronicky (v případě vybrání této doplňkové služby je potřeba také zaslat base64 PDF řetězec v atributu invoice_pdf). II- připojištění zásilky nad rámec standardního pojištění (obdoba atributu del_insurance). Pokud chcete nakombinovat více služeb dohromady, spojte je znakem +. Tedy například chci využít služeb WY a DD, tak je potřeba zaslat WY+DD Obchodní podmínky, možnosti hodnot: terms_of_trade DAP přepravné hradí odesilatel, clo a DPH hradí příjemce (výchozí nastavení u všech zásilek) DDP přepravné, clo a DPH hradí odesílatel (nutno konzultovat s DHL předem) EXW přepravné, clo a DPH hradí příjemce (nutno konzultovat s DHL předem) invoice_pdf return_track return_full_errors swap swap_option povinný při zaslání doplňkové služby WY, řetězec musí být base64 PDF pro správné předání pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou v odpovědi metody, zadejte boolean (TRUE) nebo hodnotu 1 pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean) pro navrácení zpátečního štítku zašlete hodnotu 1 nebo TRUE (boolean), pro tento druh zásilek je pak v návratových hodnotách navíc atribut carrier_id_swap Pokud chcete nastavit jinou platnost zpátečního štítku než máte vybranou v klientské zóně, můžete zaslat následující hodnoty: 3 měsíce, 6 měsíců, 12 měsíců, 24 měsíců. 55

56 Slovenská pošta Podporované služby: Balík (na adresu / na poštu / do BalíkoBOXu), Balík zmluvní zákazníci (na adresu / na poštu / do BalíkoBOXu), Expres kuriér (na adresu / na poštu / do BalíkoBOXu) a Doporučený list. Vícekusové zásilky lze vytvářet pouze pro službu Expres kuriér na adresu / na poštu (omezení přepravce). API endpoint přepravce: API endpoint metody ADD: klíč povinná popis rec_name Jméno a příjmení příjemce. Povinné pokud není vyplněno rec_firm. rec_firm Název firmy příjemce. Povinné pokud není vyplněno rec_name. Telefonní číslo příjemce, povinné při využití služby oznámení pomocí SMS nebo rec_phone jiném telefonickém kontaktu formát čísla: +421XXXYYYZZZ. Povinný pro zásilky do BalíkoBOXu. rec_ příjemce. Povinný pro zásilky na poštu / do BalíkoBOXu. rec_street Ulice příjemce. U doručení na poštu / BalíkoBOX není povinné. rec_city Město příjemce. U doručení na poštu / BalíkoBOX není povinné. PSČ příjemce, uvádějte bez mezer ve formátu XXXXX. V případě služeb na poštu rec_zip rec_country price cod_price cod_currency nebo do BalíkoBOXu se uvádí PSČ cílové pošty / BalíkoBOXu případně můžete zaslat do atributu branch_id. Kód země příjemce dle ISO alpha-2 (viz. Udaná cena zásilky, u sdružených zásilek uvádějte sečtenou hodnotu všech balíků do zásilky s prvním order_number (order_number => 1), u zbylých order_number uvádějte nulovou cenu! Výše dobírky, povinná u všech dobírkových služeb. U sdružených zásilek uvádějte sečtenou dobírkovou hodnotu všech balíků do zásilky s prvním order_number (order_number => 1), u zbylých order_number uveďte nulovou cenu! Měna dobírky dle ISO 4217 kódu (pro Kč je například CZK, pro euro je EUR), povinná položka u všech dobírkových služeb. 56

57 vs Variabilní symbol platby, povinný pro dobírkové zásilky (číslo, délka max 10). del_insurance eid order_number service_type real_order_id services weight return_track return_full_errors note branch_id Připojištění, datový typ boolean (TRUE) nebo hodnota 1 (string/integer). Unikátní ID balíku v rámci e-shopu(ů), které využívají stejné konfigurační údaje přepravce. Pořadí balíku v zásilce, povinný pro vícekusové zásilky, možné pouze pro EXA a EXP. Typ služby (BZA Balík na adresu zmluvní zákazníci, BZP Balík na poštu zmluvní zákazníci, BZB Balík do BalíkoBOXu zmluvní zákazníci, EXA Expres kuriér na adresu, EXP Expres kuriér na poštu, EXB Expres kuriér do BalíkoBOXu, BNA Balík na adresu, BNP Balík na poštu, BNB Balík do BalíkoBOXu), RRA Doporučený list. Seznam dostupných služeb je k nalezení přes metodu SERVICES. Reálné číslo objednávky (zobrazuje se na přepravních štítcích a předává se datově přepravci, pokud není vyplněno, tak se předává eid), doporučujeme ho tedy vyplňovat, pokud do povinného eid zasíláte jiné hodnoty. Kódy jednotlivých služeb spojených znakem +, které používáte pro zásilky (viz. číselný seznam služeb Slovenské pošty dostupný na U sdružených zásilek musí být čísla jednotlivých služeb uvedena vždy u prvního balíku ze sdružené zásilky (order_number => 1), u zbylých se uvádět nemusí. Váha balíku v kg, datový typ float. Pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou v dotazu metody zadejte boolean (TRUE) nebo hodnotu 1. Pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean). Poznámka přepravci (maximální délka 200 znaků). ID pošty (NP) nebo BalíkoBoxu (NB) na kterou má zásilka směřovat. Seznam aktuálně dostupných pošt/balíkoboxu můžte získat skrze metodu BRANCHES nebo FULLBRANCHES. V případě vyplnění tohoto atributu není potřeba vyplňovat rec_zip. 57

58 UPS Podporované služby: Express, Express Saver, Standard a Expedited. Oproti ostatním přepravcům, se vytvářejí sdružené zásilky pomocí atributu pieces_count tedy zadáním počtu balíčků v zásilce celá zásilka je tedy pod jedním záznamem metody ADD. Zásilkám mimo EU je potřeba vyplnit data pro celní prohlášku (content_data). API endpoint přepravce: API endpoint metody ADD: klíč povinná popis rec_name Jméno a příjmení příjemce. rec_firm Název firmy příjemce. rec_phone Telefonní číslo příjemce, povinné při využití služby oznámení pomocí SMS nebo jiném telefonickém kontaktu formát čísla: +AAAXXXYYYZZZ. Povinný pro mezinárodní zásilky. rec_ příjemce. rec_street Ulice příjemce. rec_city Město příjemce. rec_zip PSČ příjemce. Zkratka stát/okresu příjemce. Povinný při doručení do US (např. CA pro stát rec_region rec_country Kalifornie) / CA (např. BC Britská Kolumbie) / IE (např. ). Komletní seznam zde. Kód země příjemce dle ISO alpha-2 (viz. price Udaná cena zásilky, hodnota se používá pro účely připojištění. cod_price Výše dobírky, povinná u dobírkových zásilek. Měna dobírky dle ISO 4217 kódu (pro cod_currency Kč je například CZK, pro euro je EUR), povinná položka u všech dobírkových zásilek a zásilek, které chcete připojistit (del_insurance = 1 ). vs Variabilní symbol platby, povinný pro dobírkové zásilky. del_insurance Připojištění, datový typ boolean (TRUE) nebo hodnota 1 (string/integer). eid Unikátní ID balíku v rámci e-shopu(ů), které využívají stejné konfigurační údaje 58

59 service_type branch_id přepravce. Typ služby (1 Express, 2 Express Saver, 3 Standard, 4 Expedited). Seznam dostupných služeb je k nalezení přes metodu SERVICES. ID UPS Access Pointu výdejního místa. Možno zasílat v rámci jakékoli služby (service_type) UPS nepředává seznamy všech výdejních míst, proto nejsou oproti ostatním přepravcům seznamy předávány přes metodu BRANCHES. Pro implementaci nabízí UPS 2 řešení: 1. Locator Plugin předpřipravené řešení, callback obsahuje ID výdejního místa (branch_id) ukázkové demo 2. BRANCHLOCATOR. pieces_count Počet balíčků v zásilce (pokud není vyplněno, přidá se k zásilce hodnota 1). Reálné číslo objednávky (zobrazuje se na přepravních štítcích a předává se real_order_id datově přepravci, pokud není vyplněno, tak se předává eid), doporučujeme ho tedy vyplňovat, pokud do povinného eid zasíláte jiné hodnoty. weight return_track return_full_errors length height width content_data Váha zásilky v kg, datový typ float. V případě neuvedení se doplní automaticky výchozí hodnota vyplněná v konfiguraci přepravce z klientské zóny. Pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou v dotazu metody zadejte boolean (TRUE) nebo hodnotu 1. Pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean). Rozměr kusu v zásilce délka v cm. Rozměr kusu v zásilce výška v cm. Rozměr kusu v zásilce šířka v cm. Data pro celní řízení, povinná pro zásilky mířící mimo EU. Jednotlivé položky zabalené v zásilce je potřeba dopodrobna popsat dle následujících atributů: content_name_en název produktu anglicky content_weight váha položky v kg (nepovinná položka) content_pieces počet produktů content_price hodnota (cena) jednoho produktu content_currency měna ve které je uveden content_price content_ean EAN produktu (nepovinná položka, 6-15 alfanumerických znaků) content_country - ISO alpha-2 kód země původu Ukázka zápisu v JSONu pro balík obsahující 2 produkty: "content_data": [{ "content_name_en": "Name EN 1", 59

60 note require_full_age swap del_exworks "content_weight": 0.05, "content_pieces": 3, "content_price": , "content_currency": "EUR", "content_ean": " ", "content_country": "CZ"},{ "content_name_en": "Name EN 02", "content_weight": 0.55, "content_pieces": 2, "content_price": , "content_currency": "EUR", "content_ean": " ", "content_country": "SK"}] Poznámka přepravci, maximální délka 35 znaků. Přenáší se pak jako Reference2. Služba Adult singnature required podpis dospělé osoby při převzetí zásilky. Možné hodnoty jsou: 1 hodnota 2 nebo 3 vybraná jako výchozí v nastavení konfigurace přepravce v klientské zóně, 2 podpis příjemce při předání zásilky, 3 podpis příjemce a ověření věku při převzetí zásilky. Příznak pro výměnnou zásilku. Možné hodnoty jsou: 1 UPS Print Return Label (součástí klasického šítku bude zároveň návratový štítek štítek do krabice), 2 UPS Electronic Return Label (návratový štítek je zaslán na uvedený v rec_ ). Příznak pro platbu přepravy / cla a dani přijemcem. Možné hodnoty: 0 přepravné + daně a clo platí odesilatel výchozí nastavení 1 přepravné platí příjemce 2 daně a clo platí příjemce 3 přepravné + daně a clo platí příjemce del_exworks_account_number UPS ID účtu. Povinný v případě del_exworks = 1 / 2 / 3. del_exworks_zip PSČ vázající se k del_exworks_account_number. Povinný v případě del_exworks = 1 / 2 / 3. content Obecný popis zásilky (maximálně 35 znaků). Pokud není zaslán, použije se výchozí popis z konfigurace přepravce (možno změnit v klientské zóně) reference neutralize neutralize_name Reference 2 jako reference 1 se předává real_order_id, případně vs u dobírkových zásilek (pokud není zasláno ani jedna z těchto hodnot, vyplní se eid). Maximálně 35 znaků. Zároveň je předáváno jako číslo faktury u zásilek mimo EU. Příznak pro neutralizaci zásilky (fakturace cla a daně na 3. subjekt). Datový typ string ( 1 ano, 0 ne). Defaultně 0. Jméno kontaktní osoby pro neutralizaci. neutralize_firm Název firmy pro neutralizaci. Povinný v případě, že neutralize = 1. neutralize_account_number neutralize_street UPS ID účtu pro neutralizaci. Adresa (ulice + čp) subjektu pro neutralizaci. Povinný v případě, že neutralize = 60

61 1. neutralize_city Adresa (město) subjektu pro neutralizaci. Povinný v případě, že neutralize = 1. neutralize_zip Adresa (PSČ) subjektu pro neutralizaci. Povinný v případě, že neutralize = 1. neutralize_country Adresa (kód země příjemce dle ISO alpha-2) subjektu pro neutralizaci. neutralize_region Adresa (zkratka stát/okresu, povinná u sídla subjektu v US (např. CA pro stát Kalifornie) / CA (např. BC Britská Kolumbie) / IE (např. ). Kompletní seznam zde.) subjektu pro neutralizaci. neutralize_phone Kontaktní telefon subjektu pro neutralizaci. Povinný v případě, že neutralize = 1. neutralize_ Kontaktní subjektu pro neutralizaci. Povinný v případě, že neutralize = 1. 61

62 TNT Podporované služby: Express / Express dokumenty, Express 9:00 / Express 9:00 dokumenty, Express 12:00 / Express 12:00 dokumenty, Economy Expres, Economy Express 12:00 a Night Express / Night Express dokumenty. Sdružené zásilky se vytvářejí pomocí atributu pieces_count tedy zadáním počtu balíčků v zásilce celá zásilka je tedy pod jedním záznamem metody ADD. Zásilkám mimo EU je potřeba vyplnit data pro celní prohlášku (content_data). API endpoint přepravce: API endpoint metody ADD: klíč povinná popis rec_name Jméno a příjmení příjemce. rec_firm Název firmy příjemce. rec_phone Telefonní číslo příjemce, povinné při využití služby oznámení pomocí SMS nebo jiném telefonickém kontaktu formát čísla: +AAAXXXYYYZZZ. Povinný pro zásilky mezinárodní zásilky. rec_ příjemce. rec_street Ulice příjemce. rec_city Město příjemce. rec_zip PSČ příjemce. Zkratka stát/okresu příjemce. Povinný při doručení do US (např. CA pro stát rec_region rec_country Kalifornie) / CA (např. BC Britská Kolumbie) / IE (např. ). Komletní seznam zde. Kód země příjemce dle ISO alpha-2 (viz. price Udaná cena zásilky, hodnota se používá pro účely připojištění. cod_price Výše dobírky, povinná u dobírkových zásilek. cod_currency Měna dobírky dle ISO 4217 kódu (pro Kč je například CZK, pro euro je EUR), povinná položka u všech dobírkových zásilek a zásilek, které chcete připojistit (del_insurance = 1 ). vs Variabilní symbol platby, povinný pro dobírkové zásilky. del_insurance Připojištění, datový typ boolean (TRUE) nebo hodnota 1 (string/integer). 62

63 eid Unikátní ID balíku v rámci e-shopu(ů), které využívají stejné konfigurační údaje přepravce. service_type Seznam dostupných služeb je k nalezení přes metodu SERVICES. pieces_count Počet balíčků v zásilce (pokud není vyplněno, doplní se k zásilce hodnota 1). Reálné číslo objednávky (zobrazuje se na přepravních štítcích a předává se real_order_id datově přepravci, pokud není vyplněno, tak se předává eid), doporučujeme ho weight return_track return_full_errors tedy vyplňovat, pokud do povinného eid zasíláte jiné hodnoty. Celková váha zásilky v kg, datový typ float. Povinná pro nedokumentové zásilky. V případě neuvedení se doplní automaticky výchozí hodnota vyplněná v konfiguraci přepravce z klientské zóny. Pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou v dotazu metody zadejte boolean (TRUE) nebo hodnotu 1. Pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean). volume Celkový objem zásilky v m3. Povinný pro všechny nedokumentové zásilky. length height width note content_data Rozměr zásilky délka v cm. Povinné pro nedokumentové zásilky mířící mimo EU. Rozměr zásilky výška v cm. Povinné pro nedokumentové zásilky mířící mimo EU. Rozměr zásilky šířka v cm. Povinné pro nedokumentové zásilky mířící mimo EU. Poznámka přepravci, přenáší se maximálně 60 znaků. Data pro celní řízení, povinná pro nedokumentové zásilky mířící mimo EU. Jednotlivé položky zabalené v zásilce je potřeba dopodrobna popsat dle následujících atributů: content_name_en název zboží anglicky content_weight celková váha zboží v kg content_pieces počet kusů daného zboží content_description popis zboží content_price hodnota zboží content_country - ISO alpha-2 kód země původu (nepovinná položka) Ukázka zápisu v JSONu pro balík obsahující 2 produkty: "content_data": [{ "content_name_en": "Name EN 1", 63

64 "content_weight": 0.05, "content_pieces": 3, "content_price": , "content_description": "Description 1", "content_country": "CZ"},{ "content_name_en": "Name EN 02", "content_weight": 0.55, "content_pieces": 2, "content_price": , "content_description": "Description 2", "content_country": "SK"}] speciální doplňkové služby: services pickup_date del_exworks_account_number swap LQ Limited Quantities (označní limitovaného množství pro přepravu nebezpečných zásilek DG Dangerous Goods) HZ Hazardous Dangerous Goods nebezpečný obsah zásilky PR prioritně Pokud chcete nakombinovat více služeb dohromady, spojte je znakem +. Tedy například chci využít služeb HZ a LQ, tak je potřeba zaslat HZ+LQ Datum (formát YYYY-MM-DD) plánovaného předání zásilky přepravci. Pokud není vyplněné přiřazuje se automaticky datum vytvoření zásilky v systému. Číslo TNT účtu pro platbu přepravy. Příznak, že je zásilka obousměrná má být vrácen štítek a číslo zásilky (carrier_id_swap) pro zpětnou zásilku. 64

65 DHL Parcel SK Podporované služby: soukromý balík DHL Parcel, B2B firemní balík DHL Parcel Business a mezinárodní zásilky DHL Parcel International. Pro zasílání do sítě výdejních míst DHL ServicePoint (ParcelShop) je potřeba dodat branch_id u služby DHL Parcel. API endpoint přepravce: API endpoint metody ADD: klíč povinná popis ID pobočky, na níž je zásilka určena k výdeji v rámci služby DHL ServicePoint branch_id (ParcelShop), při doručení do domu je nepovinná. Seznam aktuálně aktivních výdejen získáte přes metodu BRANCHES. rec_name Jméno a příjmení příjemce. Povinný v případě neuvedení rec_firm. ID služby, kterou se bude zásilka posílat: service_type 1 DHL Parcel (vnitrostátní B2C zásilky) 2 DHL Parcel International (mezinárodní zásilky) 3 DHL Parcel Business (vnitrostátní B2B zásilky) Seznam dostupných služeb je k nalezení přes metodu SERVICES. rec_firm Název firmy příjemce. Povinný v případě neuvedení rec_name. Telefonní číslo příjemce, povinné při využití služby oznámení pomocí SMS rec_phone nebo jiném telefonickém kontaktu formát čísla (uvádějte i s předvolbou): +AAAXXXYYYZZZ rec_ příjemce. rec_street Ulice příjemce. rec_city Adresační město příjemce. rec_zip PSČ příjemce, uvádějte bez mezer ve formátu XXXXX rec_country price Kód země příjemce dle ISO alpha-2 (viz. Udaná cena balíku používá se pak pro účely připojištění del_insurance. cod_price Cena dobírky, povinná u všech dobírkových služeb. Měna dobírky dle ISO 4217 kódu cod_currency (pro Kč je například CZK, pro euro je EUR), povinná položka u všech dobírkových služeb. 65

66 vs Variabilní symbol platby, povinný pro dobírkové zásilky. eid Unikátní ID balíku v rámci e-shopu(ů), které využívají stejné konfigurační údaje přepravce. order_number Povinný pro sdružené zásilky, u samostatných se uvádět nemusí. Reálné číslo objednávky (zobrazuje se na přepravních štítcích a předává se real_order_id weight return_track sat_delivery return_full_errors note del_insurance datově přepravci, pokud není vyplněno, tak se předává eid), doporučujeme ho tedy vyplňovat, pokud do povinného eid zasíláte jiné hodnoty. Váha balíku v kg, datový typ float. Váha je povinná, pokud ji nezašlete vyplní se výchozí váha nastavená v klientské zóně. Pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou v odpovědi metody zadejte boolean (TRUE) nebo hodnotu 1. Doplňková služba sobotní doručení pro B2C zásilky, přijímané hodnoty: boolean (TRUE) nebo hodnota 1, dá se také plošně nastavit v klientské zóně pro všechny B2C zásilky. Pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean). Poznámka přepravci (maximální délka 300 znaků). Přijímané hodnoty jsou TRUE (boolean) a 1 (string/integer). Uvádějte jen u balíků s hodnotou nad EUR, které chcete připojistit, zároveň je potřeba zaslat v atributu price hodnotu balíku. 66

67 SPS Slovak Parcel Service Podporované služby: vnitrostátní doručení Expres / Expres do 12:00 / Expres do 09:00. Sdružené zásilky se vytvářejí pomocí atributu pieces_count tedy zadáním počtu balíčků v zásilce celá zásilka je tedy pod jedním záznamem metody ADD. API endpoint přepravce: API endpoint metody ADD: klíč povinná Popis eid Unikátní ID balíku v rámci e-shopu(ů), které využívají stejné konfigurační údaje přepravce. pieces_count Počet balíčků v zásilce (pokud není vyplněno, přidá se k zásilce hodnota 1). branch_id ID pobočky, na níž je zásilka určena k výdeji v rámci doručení na ParcelShop. Seznam aktivních výdejen získáte přes metodu BRANCHES. rec_name Jméno a příjmení příjemce. ID služby, kterou se bude zásilka posílat: service_type rec_firm rec_phone sms_notification phone_notification 1 Expres (vnitrostátní zásilky) 2 Expres do 12:00 (vnitrostátní zásilky) 3 Expres do 09:00 (vnitrostátní zásilky) 4 Export (mezinárodní zásilky) Seznam dostupných služeb je k nalezení přes metodu SERVICES. Název firmy příjemce. Telefonní číslo příjemce, povinné při využití služby oznámení pomocí SMS nebo jiném telefonickém kontaktu formát čísla (uvádějte i s předvolbou): +AAAXXXYYYZZZ SMS avízo příjemce. Přijímané hodnoty jsou TRUE (boolean) a 1 (string/integer). Tuto avizaci si můžete nastavit plošně pro všechny zásilky v klientské zóně. Telefonická avizace příjemce. Přijímané hodnoty jsou TRUE (boolean) a 1 (string/integer). Tuto avizaci si můžete nastavit plošně pro všechny zásilky v klientské zóně. rec_ příjemce. Povinný pro avizaci (bezplatná). _notification ová notifikace příjemce. Přijímané hodnoty jsou TRUE (boolean) a 67

68 1 (string/integer). Tato avizace je bezplatná a můžete si ji nastavit plošně pro všechny zásilky v klientské zóně. rec_street Ulice příjemce. rec_city Adresační město příjemce. rec_zip PSČ příjemce, uvádějte bez mezer ve formátu XXXXX. rec_country price del_insurance Kód země příjemce dle ISO alpha-2 (viz. Udaná cena balíku používá se pak pro účely připojištění del_insurance. Přijímané hodnoty jsou TRUE (boolean) a 1 (string/integer). Uvádějte jen u balíků s hodnotou nad EUR, které chcete připojistit, zároveň je potřeba zaslat v atributu price hodnotu balíku. cod_price Cena dobírky, povinná u všech dobírkových služeb. Měna dobírky dle ISO 4217 kódu cod_currency credit_card (pro Kč je například CZK, pro euro je EUR), povinná položka u všech dobírkových služeb. Příznak zda může být dobírková zásilka zaplacena kartou. vs Variabilní symbol platby, povinný pro dobírkové zásilky. Reálné číslo objednávky (předává se datově přepravci, pokud není real_order_id weight return_track return_full_errors sat_delivery del_exworks vyplněno, tak se předává přednostně vs u dobírkových zásilek, jinak eid), doporučujeme ho tedy vyplňovat, pokud do povinného eid zasíláte jiné hodnoty. Váha balíku v kg, datový typ float. Váha je povinná, pokud ji nezašlete vyplní se výchozí váha nastavená v klientské zóně. Pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou v odpovědi metody zadejte boolean (TRUE) nebo hodnotu 1. Pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean). Doplňková služba sobotní doručení pro vnitrostání zásilky, přijímané hodnoty: boolean (TRUE) nebo hodnota 1. Platbu za přepravu uhradí příjemce. Přijímané hodnoty: boolean (TRUE) nebo hodnota 1. 68

69 Gebrüder Weiss Podporované služby: Priority Goods 9:00 / 12:00 / 16:00, Direct Goods, Pick Up, Self Pickup by Consignee. Přepravce se specializuje na paletovou přepravu zásilky se vytvářejí skrze kombinace EID + order_number a k nim mu_type (typ manipulační jednotky) a pieces_count (počet kusů dané manipulační jednotky). API endpoint přepravce: API endpoint metody ADD: klíč povinná popis rec_name Jméno a příjmení příjemce. rec_firm Název firmy příjemce. rec_phone rec_ Telefonní číslo příjemce, povinné pro doplňkové služby telefonické avízo (phone_notification) a SMS avízo (sms_notification), formát čísla bez mezer a s mezinárodní předvolbou (např ). příjemce. rec_street Ulice + č.p. příjemce. rec_city Město příjemce. rec_zip PSČ příjemce, uvádějte bez mezer. Kód země příjemce dle ISO alpha-2 (viz. rec_country service_type price del_insurance ins_currency Jednotlivé země, kam se dá přes určitou službu (service_type) zasílat, naleznete v metodě COUNTRIES4SERVICE. ID služby, kterou se bude zásilka posílat. Seznam dostupných služeb je k nalezení přes metodu SERVICES. Udaná cena celé zásilky. Povinná v případě zaslání del_insurance = 1 (připojištění zásilky). Příznak pro připojištění zásilky. Přijímané hodnoty true (boolean) nebo hodnota 1 (string/integer). Měna udané ceny (price). Pokud není zaslána, bere se jako výchozí měna zaslaná v cod_currency. cod_price Dobírková částka, povinná u všech dobírkových zásilek. cod_currency Měna dobírky dle ISO 4217 kódu 69

70 (pro Kč je například CZK, pro Euro je EUR), povinná položka u všech dobírkových zásilek (cod_price > 0). vs Variabilní symbol platby, povinný u dobírkových zásilek (cod_price > 0). eid Unikátní ID balíku v rámci expedičních míst, které využívají stejné konfigurační údaje přepravce. order_number Povinný pro vícekusových zásilky, u samostatných se nemusí uvádět. Reálné číslo objednávky (zobrazuje se na přepravních štítcích a předává se real_order_id mu_type pieces_count datově přepravci, pokud není vyplněno, tak se předává eid), doporučujeme ho tedy vyplňovat, pokud do povinného eid zasíláte jiné hodnoty. Kód manipulační jednotky (jejich seznam s názvy získáte metodou MANIPULATIONUNITS). Počet nákladových kusů stejné manipulační jednotky (např. pokud je součástí zásilky 5 amerických palet, bude hodnota 5), pokud je nákladový kus od manipulační jednotky pouze 1, není potřeba uvádět hodnotu. weight Celková váha nákladového kusu/kusů v kg, datový typ float. volume Celkový objem nákladového kusu/kusů v m3. sms_notification phone_notification note reference return_track return_full_errors get_piece_numbers content del_exworks Služba SMS avízo (datový typ boolean true/false). Služba telefonické avízo. Přijímané hodnoty true (boolean) nebo 1 (string). Poznámka přepravci (přenáší se datově, není vidět na štítku) dlouhá maximálně 70 znaků. Zákaznická reference, maximální délka 26 alfanumerických znaků. Pro navrácení trackovacího linku na web přepravce s vytvářenou zásilkou v odpovědi metody zadejte boolean (TRUE) nebo hodnotu 1. Pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean). Pro navrácení čísel kusů jednotlivých nákladových kusů manipulačních jednotek zašlete hodnotu 1 (string nebo integer) nebo true (boolean). Textový obsah zásilky. Služba platba přepravného, cla a DPH příjemcem. Přijímané hodnoty jsou true (boolean) a 1 (string nebo integer). 70

71 Obchodní podmínky, možnosti hodnot: terms_of_trade EXW přepravné, clo a DPH hradí příjemce (nutno konzultovat s GW předem). Alternativa k del_exworks = 1. Datum plánované realizace doručení zásilky, uvádí se jako datum ve delivery_date formátu YYYY-mm-dd (např , ). Zadávejte v případě potřeby pro využití doplňkové služby in time service!. 71

72 Přehledová tabulka metody ADD ČP P P L D P D Zás Geis Ulž InT G L S eid A A A A A A A A A A A A A A A A A order_number A A A A A A A A A A A real_order_id A A A A A A A A A A A A A A A A A service_type A A A A A A A A A A A A A A A A A branch_id A A A A A A A A A A A price A A A A A A A A A A A A A A A A A del_insurance A A A A A A A A A A A A del_evening A del_exworks A A A A A cod_price A A A A A A A A A A A A A A A A cod_currency A A A A A A A A A A A A A A A A A vs A A A A A A A A A A A A A A A A rec_name A A A A A A A A A A A A A A A A A rec_firm A A A A A A A A A A A A A A A A A rec_street A A A A A A A A A A A A A A A A A rec_city A A A A A A A A A A A A A A A A A rec_zip A A A A A A A A A A A A A A A A A rec_region A A A A rec_country A A A A A A A A A A A A A A A A A rec_ A A A A A A A A A A A A A A A A A rec_phone A A A A A A A A A A A A A A A A A weight A A A A A A A A A A A A A A A A require_full_age A A A A A password credit_card A A A A sms_notification A A services A A A A A width A A A A A A A A length A A A A A A A A height A A A A A A A A note A A A A A A A A A A A A A swap A A A A A A vdl_service A A volume A A A A A A T T P b H D H L SP U P S T N T DHL sk S P S G W 72

73 pieces_count A A A A A A A mu_type A A A pieces_count_one A pieces_count_two A pieces_count_three A mu_type_one A mu_type_two A mu_type_three A comfort_service A A comfort_plus_service A over_dimension A wrap_back_count A A A wrap_back_note A app_disp A delivery_date A A return_track A A A A A A A A A A A A A A A A A bank_ccount_number A content A A A terms_of_trade A A invoice_pdf A full_age_data A sat_delivery A A A get_piece_numbers A A A A return_full_errors A A A A A A A A A A A A A A A A A content_one A content_two A content_three A phone_delivery_notification A phone_order_notification A _notification A A swap_option A comfort_exclusive_service A pers_delivery_floor A pers_delivery_building A pers_delivery_department A pin A content_data A A A A invoice_number A open_before_payment A 73

74 test_before_payment A adr_service A A adr_content A rec_name_patronymum A rec_locale_id A del_exworks_account_number A pickup_date A phone_notification A A A delivery_costs_eur A delivery_costs A ins_currency A A A rec_id A reference A A A neutralize A neutralize_name A neutralize_firm A neutralize_account_number A neutralize_street A neutralize_city A neutralize_region A neutralize_country A neutralize_phone A neutralize_ A 74

75 Datové typy atributů metody ADD Atribut Datový typ Délka/ hodnoty eid String Max 24 chars order_number Integer real_order_id String service_type String branch_id String price Float del_insurance Enum 0 / 1 del_evening Enum 0 / 1 del_exworks Enum 0 / 1 cod_price Float cod_currency String 3 vs String rec_name String rec_firm String rec_street String rec_city String rec_zip String rec_region String rec_country String rec_ String rec_phone String weight Float require_full_age Enum 0 / 1 password String credit_card Enum 0 / 1 sms_notification Enum 0 / 1 services String width Float length Float height Float note String swap Enum 0 / 1 vdl_service Enum 0 / 1 volume Float pieces_count Integer mu_type String 75

76 pieces_count_one Integer pieces_count_two Integer pieces_count_three Integer mu_type_one String mu_type_two String mu_type_three String comfort_service Enum 0 / 1 comfort_plus_service Enum 0 / 1 over_dimension Enum 0 / 1 wrap_back_count Integer wrap_back_note String app_disp Enum 0 / 1 delivery_date String YYYY-MM-DD return_track Enum 0 / 1 bank_account_number String content String terms_of_trade String invoice_pdf String full_age_data String sat_delivery Enum 0 / 1 get_piece_numbers Enum 0 / 1 return_full_errors Enum 0 / 1 content_one String content_two String content_three String phone_delivery_notification Enum 0 / 1 phone_order_notification Enum 0 / 1 _notification Enum 0 / 1 swap_option String comfort_exclusive_service Enum 0 / 1 pers_delivery_floor Enum 0 / 1 pers_delivery_building Enum 0 / 1 pers_delivery_department Enum 0 / 1 pin Integer content_data Array invoice_number String carrier_id String package_id Integer label_url String 76

77 track_url String open_before_payment Enum 0 / 1 test_before_payment Enum 0 / 1 adr_service Enum 0 / 1 adr_content rec_name_patronymum rec_locale_id del_exworks_account_number Array String String String pickup_date String YYYY-MM-DD phone_notification Enum 0 / 1 delivery_costs_eur delivery_costs Float Float ins_currency String 3 reference String neutralize Enum 0 / 1 neutralize_name String neutralize_firm String neutralize_account_number String neutralize_street String neutralize_city String neutralize_region String 2 neutralize_country String 2 neutralize_phone String neutralize_ String 77

78 Struktura odpovědi po převedení na datový typ pole při nevalidních datech: array( ); 0 => array( ), 1 => array(... ), rec_name => 406, rec_street => 406 status => 200 Struktura odpovědi v JSONu při nevalidních datech s využitím atributu return_full_errors: { } "0": { "errors": { "0": { "type": "413", "attribute": "rec_street", "message": "Nedorazil název ulice s číslem popisným příjemce." }, "1": { "type": "406", "attribute": "rec_zip", "message": "Nedorazilo PSČ příjemce." } } }, "1": { "errors": { "0": { "type": "413", "attribute": "rec_zip", "message": "Nepovolené PSČ příjemce." } } }, "status": "400" Pokud se v příchozích datech nalezne jakákoli chyba, neuloží se do systému Balíkobotu nic. Při zaslání atributu return_full_errors v requestu metody ADD se vrací chyby s podrobným 78

79 popisem. V pořadí, v jakém data (balíky) dorazila, v takovém jsou uspořádány jednotlivé odpovědi (indexy v poli). Balíky, které měly správně zaslaná data, mají návratovou hodnotu status => 200. Ostatní mají v indexu asociativního pole daný problémový vstup pojmenovaný stejně jako vstupní parametry (viz. metoda ADD) a popis chyby. Struktura odpovědi po převedení na datový typ pole při validních datech: array( ); 0 => array( carrier_id => DR M, package_id => 185, label_url => carrier_id_swap => DR M, track_url => pieces => array( 0 => , 1 => , 2 => ) ), 1 => array( ),... labels_url => Pokud se v příchozích datech nenalezne jakákoli chyba, data se uloží. V pořadí, v jakém data (balíky) dorazila, v takovém jsou uspořádány jednotlivé odpovědi (indexy v poli). Každý balík má v návratovém poli tato data: carrier_id ID balíku v rámci dopravce, používá se pro případný track&trace (metoda TRACK). package_id ID balíku v rámci API Balikobot, používá se při odmazání balíku ze systému (metoda DROP). label_url - URL na štítek pro daný balík/zásilku. carrier_id_swap ID zpáteční zásilky v případě vyžádání přes atribut swap (DPD, DHL), štítky pro výměnou zásilky jsou vráceny spolu se standardními v label_url. track_url URL na track&trace zásilky přímo na webu přepravce, vrací se pouze u zásilek, u kterých si zažádáte skrze atribut return_track. 79

80 pieces pole s čísly kusů spadajících do zásilky počet těchto čísel je roven hodnotě zaslané v atributu pieces_count (v případě Toptransu se jedná o součet všech tří atributů pieces_count_*). Čísla kusů se pak dají využívat v T&T na webu přepravců pro případné dohledání konkrétního kusu ze zásilky. Využívají se tedy pouze u paletových přeprav (Toptrans, PPL Sprint, Geis Cargo, Gebrüder Weiss). Vyžádat si lze přes atribut get_piece_numbers. Pokud zašlete stejné EID zásilky, nevytvoří se, ani nepřeuloží data, ale zašle se vám znovu nazpět stejné carrier_id, package_id, label_url a navíc ještě status 208 jakožto příznak, že tato zásilka již existovala. Pokud zašlete v requestu více jak jednu zásilku, dostanete nazpět mimo výše uvedených dat ještě labels_url, ve kterém se nachází URL na PDF se štítky všech zásilek zaslaným v tomto requestu (pro hromadný tisk). Návratová data si uložte pro další práci (odmazání, track&trace, tisk štítků)! Pro PDF návratové URL (příklad můžete určovat přes GET parametr p umístění štítku v A4 formátu (1, 2, 3 nebo 4). Výsledná podoba URL je tedy například taková: Příklad implementace pozicování naleznete v kapitole Příklad implementace v administraci obchodu (113). 80

81 ZPL štítky Pokud vlastníte tiskárnu značky Zebra, můžete místo formátu PDF využít pro přímý tisk formát ZPL. Aktuálně existují 2 způsoby jak získat přímo ZPL namísto PDF pro tisk: 1. Nastavení v rámci konfigurace přepravce v klientské zóně výběr výchozích vracených štítků (PDF A4 / PDF pro Zebra / ZPL pro Zebru). Pokud si nastavíte ZPL pro Zebru, pak bude vracen z metody ADD štítek s doplněným GET parametrem zpl=1 a není potřeba dále nic dělat. 2. K vrácené label_url / labels_url z metody ADD si dolepíte GET parametr zpl=1. Tzn. URL pak vypadá takto tato zpětná konverze PDF -> ZPL, případně ZPL -> PDF bohužel není možná u přepravce SPS a DHL Express. 81

82 DROP Odstranit lze pouze zásilky, které ještě nebyly odeslány ke svozu metodou ORDER. ENDPOINT URL: Request JSON Data: { id :PACKAGE_ID} Seznam používaných parametrů PACKAGE_ID ID balíku, které předalo API při vložení balíku do systému (response požadavku ADD package_id). JSON Request 1 odmazání jednoho balíku (dostupná u všech přepravců) { id :PACKAGE_ID} JSON Response 1 odmazání jednoho balíku: { status :200} Balík byl v pořádku odmazán. { status :404} Balík s daným ID buďto neexistuje, nebo byl již odeslán ke svozu. { status :403} Balík s daným ID nelze odmazat, protože je z vícekusové zásilky a není posledním balíkem. Příklad: přes metodu ADD jsem vytvořil vícekusovou zásilku o 3 balících (balíky mají společné EID, každý má rozdílné order_number 1, 2, 3). Pokud chci odmazat jako první balík s order_number = 3, proběhne DROP v pořádku. Pokud budu chtít odmazat jako první balík s order_number = 1 nebo 2, vrátí se mi status 403. Request 2 hromadné odmazání balíků (nová rozšířená verze dostupná pro všechny přepravce mimo Intime a Uloženky) JSON s více balíky: [{"id": PACKAGE_ID }, {"id": PACKAGE_ID }, {"id": PACKAGE_ID }] 82

83 Response 2 v1: {"0": { } "status": 404 // balík neexistuje nebo již je ve svozu }, "1": { "status": 200 // balík je možno odmazat, ale ne v tomto requestu }, "status": 400 // během operace došlo nejméně u jednoho balíku k chybě Response 2 v2: {"0": { "status": 403 // balík pochází z vícekusové zásilky a není poslední (order_number) }, "1": { "status": 200 // balík je možno odmazat, ale ne v tomto requestu }, "status": 400 // během operace došlo nejméně u jednoho balíku k chybě 83

84 TRACK Vrací všechny stavy balíku/balíků, ve kterých se dosud ocitl s textovým popisem. Maximální počet dotazovaných zásilek je 4. Pokud zašlete více zásilek, bude vám navrácen status 413! Request: $adata= array( id => CARRIER_ID ); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, ); curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); curl_setopt($ch, CURLOPT_HEADER, FALSE); curl_setopt($ch, CURLOPT_POST, TRUE); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($adata)); // pole $adata vstupů curl_setopt($ch,curlopt_httpheader, array( Authorization: Basic. base64_encode( USER:API_KEY), Content-Type: application/json )); $response = curl_exec($ch); curl_close($ch); $aresponse = json_decode($response); // převod návratových hodnot do pole Seznam používaných parametrů CARRIER_ID ID v rámci přepravce předané metodou ADD (parametr carrier_id) Do pole $adata je možné dosadit i více zásilek: $adata= array( 0 => array( id => CARRIER_ID ), 1 => array( id => CARRIER_ID ), ); 84

85 Response: array( ); 0 = array( ), 1 => array( ) status => 404 Zásilka (s indexem 0) buďto neexistuje, nebo o ní zatím nejsou dostupné žádné informace. array( ); status => 406 Nedorazila žádné ID(s). array( ); 0 => array( ), 0 => Last info, 1 => Info,.. 1 => array( ),..... V pořadí, v jakém data (balíky) dorazila, v takovém jsou uspořádány jednotlivé odpovědi (indexy v poli). Každý balík má v návratovém poli informace seřazené od nejaktuálnější po nejstarší, obsah je dán dopravcem. 85

86 TRACK V2 Vrací všechny stavy balíku/balíků, ve kterých se dosud ocitl s textovým popisem. Maximální počet dotazovaných zásilek je 4. Pokud zašlete více zásilek, bude vám navrácen status 413! Na rozdíl od základní verze se vrací data více strukturovaně každý stav je rozpadlý na datum a čas + textový popis stavu + status_id odpovídající návratové hodnotě metody TRACKSTATUS. ENDPOINT: Příklad request data v JSONu (stejné jako u klasické metody TRACK): [{"id": " CARRIER_ID "},{"id": " CARRIER_ID "}] CARRIER_ID ID v rámci přepravce předané metodou ADD (parametr carrier_id) Příklad response v JSONu: { "0": { "0": {"date": " :15:01","name": "Doručení", "status_id":2}, "1": {"date": " :29:39","name": "Naložení na rozvoz", "status_id":1}, "2": {"date": " :27:10","name": "Příjem na depo", "status_id":1}, "7": {"date": " :03:28","name": "Zákaznická reference", "status_id":-1} }, "1": { "0": {"date": " :15:01","name": "Doručení", "status_id":2}, "1": {"date": " :29:58","name": "Naložení na rozvoz", "status_id":1}, "2": {"date": " :27:10","name": "Příjem na depo", "status_id":1}, "7": {"date": " :03:28","name": "Zákaznická reference", "status_id":-1} } } 86

87 TRACKSTATUS Vrací poslední stav balíku/balíků ve formě čísla a textové prezentace. Vstupy zpracovává stejně jako metoda TRACK. Maximální počet dotazovaných zásilek je 4. Pokud zašlete více zásilek, bude vám navrácen status 413! Request: $adata= array( id => CARRIER_ID ); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, ); curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); curl_setopt($ch, CURLOPT_HEADER, FALSE); curl_setopt($ch, CURLOPT_POST, TRUE); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($adata)); // pole $adata vstupů curl_setopt($ch,curlopt_httpheader, array( Authorization: Basic. base64_encode( USER:API_KEY), Content-Type: application/json )); $response = curl_exec($ch); curl_close($ch); $aresponse = json_decode($response); // převod návratových hodnot do pole Seznam používaných parametrů CARRIER_ID ID v rámci přepravce předané metodou ADD (parametr carrier_id) Do pole $adata je možné dosadit i více zásilek: $adata= array( 0 => array( id => CARRIER_ID ), 1 => array( id => CARRIER_ID ) 87

88 ); Response: array( ); 0 => array( status_id => 1, status_text => Zásilka byla doručena příjemci. ), 1 => array( status_id => 2, status_text => Zásilka je doručována příjemci. ),.. V pořadí, v jakém data (balíky) dorazila, v takovém jsou uspořádány jednotlivé odpovědi (indexy v poli). Každý balík má v návratovém poli status kód posledního stavu, ve kterém se nachází. Track status kódy -1 Zásilka zatím nebyla předána přepravci. 0 Zásilka nebyla doručena odmítnutí příjemcem. (případně Zásilka nebyla doručena chyba u přepravce. ) 1 Zásilka byla doručena příjemci. 2 Zásilka je doručována příjemci. (případně Zásilka je připravena k výdeji. ) 3 Zásilka stornována. 4 Zásilka byla doručena zpět odesilateli. (novinka od ) 88

89 OVERVIEW Soupis dosud neodeslaných balíků se základními informacemi. Není potřeba implementovat, je spíše pro kontrolu. Request: $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, ); curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); curl_setopt($ch, CURLOPT_HEADER, FALSE); curl_setopt($ch, CURLOPT_POST, TRUE); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($adata)); // pole $adata vstupů curl_setopt($ch,curlopt_httpheader, array( Authorization: Basic. base64_encode( USER:API_KEY), Content-Type: application/json )); $response = curl_exec($ch); curl_close($ch); $aresponse = json_decode($response); // převod návratových hodnot do pole Response: array( ); status => 404 V systému nejsou žádné neodeslané balíky. Příklad návratových hodnot: array( 0 => array( eshop_id => , carrier_id => , package_id => 10, label_url => ), 1 => array( ), 89

90 ); 2 => array( ),... eshop_id ID v e-shopu carrier_id ID balíku v rámci přepravce (pro metodu TRACK) package_id ID balíku v rámci API (použitelné pro metodu DROP) label_url odkaz na PDF se štítkem 90

91 LABELS Metoda vracející hromadné PDF se štítky pro vyžádané balíčky (package_ids) u vybraného dopravce. Doplňková metoda pro klienty, kteří netisknou štítky ihned po přidání metodou ADD, ale až dávkově a chtějí mít štítky v hromadném PDF. Request URL: JSON request example: {"package_ids":[package_id_1, PACKAGE_ID_2, PACKAGE_ID_3]} PACKAGE_ID_1, PACKAGE_ID_2, PACKAGE_ID_3 atd. package_id vrácené z metody ADD. Response JSON 1: { } status => 404 Špatná struktura dat/nedorazila žádná data. Response JSON 2: { } status => 406 V systému nejsou žádné neodeslané balíky s těmito package_ids. Response 3: { labels_url => status => 200 } labels_url odkaz na PDF se štítky. 91

92 PACKAGE Kompletní informace ke konkrétnímu balíku. Není potřeba implementovat, je spíše pro kontrolu. Request: $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, ); curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); curl_setopt($ch, CURLOPT_HEADER, FALSE); curl_setopt($ch, CURLOPT_POST, TRUE); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($adata)); // pole $adata vstupů curl_setopt($ch,curlopt_httpheader, array( Authorization: Basic. base64_encode( USER:API_KEY), Content-Type: application/json )); $response = curl_exec($ch); curl_close($ch); $aresponse = json_decode($response); // převod návratových hodnot do pole PACKAGE_ID nahraďte za package_id předané metodou ADD (to stejné vrací metoda OVERVIEW) Response: array( ); status => 404 Zásilka s daným PACKAGE_ID není v systému, nebo nenáleží pod použité API klíče. Příklad návratových hodnot: array( vs => , cod_price => , rec_firm =>, rec_zip => 19000, rec_phone => , rec_name => John Carter, rec_street => Kovarska 12, rec_city => Praha9, 92

93 ); rec_country => CZ, rec_ => rec_contact =>, del_insurance => 1, del_evening => 0, length => 45.00, width => , height => 18.50, weight => 0.00, sms_notification => 0, eshop_id => , carrier_id => , package_id => 10, label_url => http =>\/\/pdf.balikobot.cz\/dpd\/enormdy1nfwwxdaelge2 Návratové informace jsou závislé na tom, co se předá do API během requestu ADD + obsahuje další informace jako je eshop_id, carrier_id, package_id a label_url, které se předávají po jeho založení (ADD). 93

94 ORDER Předání dat do systému přepravce ( objednání svozu ) pro dosud neodeslané balíky. Request: $adata= array( note => Pozor křehké věci, date => , package_ids => array(33, 34, 37, 38) ); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, ); curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); curl_setopt($ch, CURLOPT_HEADER, FALSE); curl_setopt($ch, CURLOPT_POST, TRUE); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($adata)); // pole $adata vstupů curl_setopt($ch,curlopt_httpheader, array( Authorization: Basic. base64_encode( USER:API_KEY), Content-Type: application/json )); $response = curl_exec($ch); curl_close($ch); $aresponse = json_decode($response); // převod návratových hodnot do pole Seznam používaných parametrů Pro zaslání dat přepravci stačí zavolat příslušnou URL, parametry jsou nepovinné. note nepovinný, poznámka pro dopravce (jen pro PPL). date nepovinný, datum přijetí dopravce ke svozu (jen pro PPL) pokud není vyplněno, vyplní se datum aktuálního dne. package_ids nepovinný (pro vlastní řešení), výčet ID balíků (package_id vrácené při metodě ADD), které budou zahrnuty do objednávaného svozu. Pokud je tento parametr prázdný, budou do 94

95 objednávaného svozu zahrnuty všechny dosud neodeslané balíky. Žádáme vývojáře e-shopových řešení, aby nám tuto informaci zasílali povinně. Nastávají situace, kdy má jeden klient více obchodů s jednou smlouvou u dopravce a zasílá data do Balíkobota z více řešení pod jedním klientským účtem a objednáním svozu z jedné administrace se do svozu zahrnou všechny zásilky, i ty které jsou pod jinou administrací! Response: array( status => 406 ); status 406 chcete objednat svoz, ale v systému nejsou žádné balíky pro import. status 503 technologie dopravce není momentálně dostupná. array( order_id => 29, file_url => handover_url => labels_url => status => 200 ); order_id číslo objednání svozu (používá se jako parametr pro opětovné navrácení informací file_url + handover_url + labels_url daného svozu). Pro každého dopravce je přiřazeno právě jedno číslo. file_url odkaz na soubor pro import/předání dopravci (jen u České pošty) nepoužívá se u klientů kteří mají aktivované přímé napojení na API (aktuálně většina). handover_url odkaz na PDF s předávacím archem s výpisem všech předávaných zásilek. labels_url odkaz na PDF se všemi štítky, které byly zahrnuty do objednaného svozu. 95

96 ORDERVIEW Informace k poslednímu/konkrétnímu svozu file_url, handover_url, labels_url, order_id. Není potřeba implementovat, je spíše pro kontrolu. Request URL: Seznam používaných parametrů ORDER_ID 3. segment URL, který určuje, o jakém svozu chcete získat zpětně informace. Pokud tento segment nevyplníte, získáte tím údaje o poslední objednávce svozu. Response: array( ); status => 406 status 406 svoz s Vámi zaslaným ORDER_ID neexistuje. array( order_id => 29, file_url => handover_url => labels_url => package_ids => array( 0 => 145, 1 => 146, 2 => 147, ) ); order_id číslo objednaného svozu. file_url odkaz na soubor pro import/předání dopravci (jen u České pošty) nepoužívá se u klientů kteří mají aktivované přímé napojení na API (aktuálně většina) handover_url odkaz na PDF s předávacím archem s výpisem všech předávaných zásilek. labels_url odkaz na PDF se všemi štítky, které byly zahrnuty do objednaného svozu. 96

97 package_ids seznam zásilek (package_id), které se váží k tomuto svozu. 97

98 ORDERPICKUP Metoda pro objednání kurýra v případě, že nemá klient domluvené pravidelné svozy na své expediční místo. Tato metoda je dostupná zatím pouze pro přepravce DHL! Pokud nechcete tuto metodu implementovat, máte možnost si svoz objednat přes rozhraní ve vaší klientské zóně. Request URL: Request JSON formát: {"date":" ", "time_from": "14:00", "time_to": "16:30", "weight":"128.5", "package_count": 8, "message":"3. rampa za vrátnicí."} Seznam používaných parametrů date povinný, datum (formát YYYY-mm-dd) na které je objednán kurýr pro vyzvednutí zásilek, datum může být maximálně 10 dní od aktuálního dne time_from povinný, začátek časové okna, kdy budou zásilky připraveny ke svozu (formát HH:ii) time_to povinný, čas do kdy má přijet svoz (formát HH:ii, rozdíl mezi time_from a time_to musí být alespoň 60 minut) weight povinný, přibližná váha zásilek v kg, které bude kurýr vyzvedávat package_count povinný, přibližný počet balíčků, které bude kurýr vyzvedávat message nepovinný, speciální instrukce pro kurýra Response: V případě, že jsou všechny položky validní, vrací se status 200 { status : 200 }. V případě chyby na straně přepravce, se vrací {["other":"406"],"status":"400"}. Pokud v requestu chybí některý z povinných atributů, vrací se standardně výčet chyb stejně jako u metody ADD. Tedy například: { [ "date":"413","time_from":"406" ],"status":"400"} 98

99 SERVICES Vrací seznam služeb, které se dají použít u daného dopravce. Pokud se v seznamu nevrátí nic (NULL), znamená to, že do atributu service_type se nemusí nic zadávat. Například u dopravce Zásilkovna se její služby zasílají přímo v branch_id. Zde je tedy seznam všech poboček a služeb v metodě BRANCHES, protože není možná kombinace speciální služby a výdejní pobočky. Request: Response 1: array( ); status => 200, service_types => array( DR => Balík Do ruky, RR => Doporučená zásilka, NP => Balík Na poštu, VL => Cenné psaní, DV => Balík Do ruky pro vybrané podavatele ) Response 2: array( ); status => 200, service_types => array( 2 => Exportní balík, 3 => Dopolední doručení, 4 => Soukromý balík, 8 => Firemní balík ) Response 3: array( status => 200, 99

100 ); service_types => NULL service_types výčet služeb, které jsou podporovány. Klíče jsou ID služeb (předávané do atributu service_type v metodě ADD, případně jako parametr SERVICE_TYPE v metodě BRANCHES) a hodnoty jsou názvy daných služeb. Pokud je prázdné (jako např. u Zásilkovny), tak není potřeba předávat do atributu service_type nic. 100

101 MANIPULATIONUNITS Vrací seznam názvů a id (hodnot pro atribut mu_type) možných manipulačních jednotek pro paletovou přepravu (Geis Cargo). Request URL: Response (Geis): array( ); status => 200, units => array( 0 => array( name => EUROPALETA, code => FP ), 1 => array( name => POLOPALETA, code => KH, ),.. ) 101

102 BRANCHES Vrací seznam poboček, na které se dají posílat zásilky u konkrétní služby. Čísla poboček se poté dají předat do atributu branch_id v metodě ADD. U dopravce Zásilkovna se zde předávají i čísla dalších služeb (např. Česká pošta nebo Expresní doručení Ostrava), které se předávají také do atributu branch_id. Request URL: Seznam používaných parametrů SERVICE_TYPE 3. segment URL určující pro kterou službu budou navráceny pobočky/psč. SERVICE_TYPE přijímá jen klíče, které jsou vraceny pro daného dopravce metodou SERVICES. Pokud se vrátí NULL v atributu service_types z metody SERVICES, pak tento segment ničím nedoplňujte a zašlete ho prázdný (například u přepravce Zásilkovna zde můžete použít místo SERVICE_TYPE ISO kód země příjemce jako filtr tzn. např. pro všechny CZ výdejní místa stačí zavolat URL Response 1 (Zásilkovna array( status => 200, service_type => NULL, branches => array( 0 => array( type => branch, zip => 35002, id => 1234, name => Cheb 2, city => Cheb, country => CZ ), 1 => array( type => service, zip => 00000, id => 136, name => Expresní doručení Brno, city =>, country => CZ ),.. 102

103 ); Response 2 (PPL): ) array( ); status => 200, service_type => 4, branches => NULL service_type ID služby pro který je vyžádán seznam poboček, která byla zadána v URL. branches Výčet poboček s doplňujícími informacemi: type typ pobočky, nabývá hodnot branch (výdejní místo) nebo service (služba). id identifikátor pobočky, který se předává do atributu branch_id v metodě ADD. zip PSČ pobočky. name název pobočky. street ulice, ve které se pobočka nachází. Navrací se jen u záznamů, u kterých tuto informaci máme. city město, ve kterém se pobočka nachází. Navrací se jen u záznamů, u kterých tuto informaci máme. country ISO alpha-2 zkratka státu, ve kterém se pobočka nachází. Navrací se jen u záznamů, u kterých tuto informaci máme. 103

104 FULLBRANCHES Obdoba metody BRANCHES s tím, že se pro každou pobočku vrací více informací. Tato metoda není dostupná pro všechny přepravce, její rozšířování je řešeno na základě poptávky a dostupnosti dat od přepravce. Neváhejte nás tedy kontaktovat pokud budete chtít u nějakého přepravce pro jeho pobočky další rozšiřující informace. Request URL: Seznam používaných parametrů SERVICE_TYPE 3. segment URL určující pro kterou službu budou navráceny pobočky/psč. SERVICE_TYPE přijímá jen klíče, které jsou vraceny pro daného dopravce metodou SERVICES. Pokud se vrátí NULL v atributu service_types z metody SERVICES, pak tento segment ničím nedoplňujte a zašlete ho prázdný (například u přepravce Zásilkovna zde můžete použít místo SERVICE_TYPE ISO kód země příjemce jako filtr tzn. např. pro všechny CZ výdejní místa stačí zavolat URL Pro dotáhnutí rozšířených informací k pobočkám České pošty u služby Balík Na poštu zašlete NP. Response: array( status => 200, service_type => NULL, branches => array( 0 => array( type => branch, ) ); service_type ID služby pro který je vyžádán seznam poboček, která byla zadána v URL. branches Výčet poboček s doplňujícími informacemi 104

105 Tabulka atributů nesoucích doplňující informace o pobočce Atribut význam dat. typ Zásilkovna Česká pošta PbH id branch_id int A A name název string A A A city město string A A A city_part část obce String A street ulice string A A A zip PSČ string A A A district okres string A A region kraj string A country ISO-2 kód země string A A currency měna string A type pobočka/služba string A photo_small foto pobočky malé string A photo_big foto pobočky velké string A url URL pobočky/služby string A latitude zeměpisná šířka float A A A longitude zeměpisná délka float A A A directions_global obecné pokyny string A directions_car pokyny pro motoristy string A directions_public pokyny pro pěší string A A wheelchair_accessible dostupné pro vozíčkáře int 0/1 claim_assistant reklamační asistent int 0/1 A dressing_room šatna int 0/1 A opening_monday ot. doba v pondělí string A A A opening_tuesday ot. doba v úterý string A A A opening_wednesday ot. doba ve středu string A A A opening_thursday ot. doba ve čtvrtek string A A A opening_friday ot. doba v pátek string A A A opening_saturday ot. doba v sobotu string A A A opening_sunday ot. doba v neděli string A A A type typ služby A A Poznámka: Datový typ int 0/1 hodnota 0 je brána jako NE, 1 jako A. 105

106 BRANCHLOCATOR Pro vstupní parametry vrací seznam poboček a jejich informací (výstupem je obdoba metody FULLBRANCHES). Tato metoda je dostupná pro přepravce: UPS - seznamy poboček nenabízí a je potřeba si je stahovat individuálně nebo skrze jejich plugin. PbH seznam poboček je potřeba pro doručování na výdejní místa v Německu (pro vstupní parametry se pak vrátí seznam výdejních míst z okruhu 15 kilometrů) UPS Request URL: UPS Request JSON formát: {"country":"cz", "city": "Praha", "zip": "16000", "street":"seifertova 7", "max_results": 15, "radius":10} Seznam používaných parametrů u UPS country povinný, ISO alpha-2 kód státu (viz. city povinný, město zip nepovinný, PSČ pro upřesnění výchozího bodu vyhledávání poboček street nepovinný, ulice, případně ulice s číslem popisným pro upřesnění výchozího bodu vyhledávání poboček max_results nepovinný, maximální počet vrácený poboček (výchozí je neomezený) radius nepovinný, okruh hledaných poček v km (výchozí je 50 km) Response: {"status": "200", "branches": { "0": { "id": "U ", // branch_id }}} 106

107 PbH Request URL: PbH Request JSON formát: {"country":"de", "city": "Berlin", "zip": "13347", "street":" Schönwalder", "type":"postfiliale", } Seznam používaných parametrů u PbH country povinný, ISO alpha-2 kód státu (viz. aktuálně je přijímané pouze DE city povinný v případě že není zadáno PSČ (zip), město zip povinný v případě že není zadáno město (city), PSČ pro upřesnění výchozího bodu vyhledávání poboček street nepovinný, ulice, případně ulice (bez čísla popisného) pro upřesnění výchozího bodu vyhledávání poboček type nepovinný, možné hodnoty ( postfiliale výdejní místa Německé pošty nebo partnerská výdejní místa, packstation výdejní automaty), výchozí hodnotou je postfiliale Response: { "status": "200", "branches": { "0": { "id": "U ", // branch_id }}} 107

108 COD4SERVICES Metoda vracející seznam služeb (service_type) a k nim výčet zemí (rec_country), do kterých lze zasílat doběrečné zásilky. Na úrovni země je dále doplněna maximální výše dobírky (max_price) a měna (currency). Výstup metody je postupně doplňován, k je plně dostupná pro přepravce PPL, Česká pošta a Pošta bez hranic. Request URL: Response example: { "status": 200, "service_types": { "0": { "service_type": "DR", "cod_countries": { "CZ": {"max_price": ,"currency": "CZK"} } }, "15": { "service_type": "VZP", "cod_countries": { "UA": { "currency": "UAH", "max_price": 36000}, "LV": {"currency": "USD", "max_price": 2000}, "HU": {"currency": "EUR", "max_price": 2500}, "SK": {"currency": "CZK", "max_price": } } } } 108

109 COUNTRIES4SERVICE Seznam států, do kterých lze zasílat skrze jednotlivé služby přepravce. Requestu URL: Response: array( ); status => 200, service_types => array( 0 => array( service_type => 1, countries => array( CZ, SK, DE ) ), 1 => array( service_type => 1, countries => array( CZ ) ),.. ) service_type ID služby, ke které se váží možné země (countries). countries - seznam ISO-2 country kódů zemí, do kterých lze zasílat skrze danou službu. 109

110 ZIPCODES Vrací výčet PSČ, na které se dají posílat zásilky u konkrétní služby. Tato PSČ jsou platná pro atribut rec_zip v metodě ADD. Request URL 1: Request URL 2: Seznam používaných parametrů SERVICE_TYPE 3. segment URL určující pro kterou službu budou navráceny pobočky/psč. SERVICE_TYPE přijímá jen klíče, které jsou vraceny pro daného dopravce metodou SERVICES. Pokud se vrátí NULL v atributu service_types z metody SERVICES, pak tento segment ničím nedoplňujte a zašlete ho prázdný. COUNTRY nepovinný 4. segment URL určující zemi, pro kterou se mají vrátit PSČ. Seznam zemí, do kterých je možno zasílat přes konkrétní služby přepravce je dostupný skrze metodu COUNTRIES4SERVICE. Příklad: Budu chtít všechna PSČ od přepravce PPL, služby PPL Parcel Connect (service_type 2) z Maďarska (HU). URL tedy bude mít tuto podobu: Response 1 (Česká Pošta): array( ); status => 200, service_type => DR, type => zip, zip_codes => array( 0 => array( zip => 35002, 1B => false, country => CZ ), 1 => array( zip => 19000, 1B => true, country => CZ ),. ) 110

111 Response 2 (Geis): array( status => 200, service_type => 1, type => zip_range, zip_codes => array( 0 => array( zip_start => 10000, zip_end => 10199, country => CZ ), 1 => array( zip_start => 35000, zip_end => 35299, country => CZ ),.. ) ); Response 3 (Uloženka služba ČP balík Na poštu): array( status => 200, service_type => 7, type => zip, zip_codes => NULL ); Response 4 (DHL, service_type = 1, country = AD, type zip_range) JSON: { "status": 200, "service_type": 1, "type": "zip_range", "country": "AD", "zip_codes": { "0": { "city": "AIXIRIVALL", "zip_start": "25999", "zip_end": "25999" }, } 111

112 Response 5 (DHL, service_id = 1, country = AE, type city) JSON: { "status": 200, "service_type": 1, "type": "city", "country": "AE", "zip_codes": { "0": {"city": "ABU DHABI"}, "1": {"city": "AJMAN CITY"}, } service_type ID služby pro který je vyžádán seznam PSČ. type PSČ mohou být navrácena dvěma způsoby: buďto jako rozsahy (zip_range) nebo jednotlivě (zip), případně u zemí, kde PSČ nemají (například Spojené arabské emiráty) se vrací city. zip_codes Výčet PSČ: zip PSČ pobočky, přítomen pokud je type zip. zip_start Začátek rozsahu PSČ, přítomen pokud je type zip_range. zip_end Konec rozsahu PSČ, přítomen pokud je type zip_range. 1B příznak, že na dané PSČ je možno zasílat balíky v odpoledním časovém pásmu (hodnota true) country ISO alpha-2 zkratka státu, ve kterém se pobočka nachází. Navrací se jen u záznamů, u kterých tuto informaci máme. city název města, pokud je type city, případně zip_range. Poznámka: Pokud je type zip_range, tak všechna PSČ v tomto rozsahu se berou jako validní. 112

113 CHECK Metoda pro validaci příchozích dat. Přijímá stejná data jako metoda ADD. Jediný rozdíl je v tom, že v případě validních dat neukládá data do systému Balíkobotu (nevytvoří štítky). Pouze vrátí informaci, že jsou data v pořádku / nebo vrátí seznam chyb stejně jako metoda ADD. Request URL 1: Response 1 (2 zásilky v pořádku) JSON {"0": { "status": "200"}, "1": {"status": "200"}, "status": "200"} Response 2 (2 zásilky, u 1. chybná ) JSON {"0": {"errors": { "0": { "type": "413", "attribute": "rec_country", "message": "Pro vybranou službu je možné doručení pouze po ČR." }}}, "1": {"status": "200"}, "status": "400"} Celkový status je v případě všech validních dat 200. Pokud jsou v některé zásilce objevena nevalidní data je 400. V případě nějaké chyby dat v zásilce se vrací seznam chyb ve stejném formátu jako když si u metody ADD zavoláte return_full_errors =

114 ADRUNITS Vrací seznam názvů (name), kódu jednotky (code) a unikátního id (hodnot pro atribut adr_un) možných ADR jednotek. Request URL: Response (Toptrans): { "status": 200, "units": { "0": { "id": "1", "code": "432", "name": "PŘEDMĚTY PYROTECHNICKÉ pro technické účely" }, "1": { "id": "2", "code": "1001", "name": "ACETYLÉN, ROZPUŠTĚNÝ" },. } 114

115 ACTIVATEDSERVICES Vrací zda je přepravce aktivován, případně zda jsou aktivovány všechny služby (service_type). Na úrovni Geis a PPL je navíc rozlyšována paletová (Cargo) a balíková (Parcel) přeprava. Request URL: Response (PPL): { "status": 200, "active_parcel": true, "active_cargo": true, "service_types": { "2": "PPL Parcel Connect", "3": "PPL Parcel CZ Dopolední balík", } } active_parcel boolean, aktivní balíková přeprava? active_cargo boolean, aktivní paletová přeprava? (PPL Sprint / Geis Cargo / TopTrans) service_types seznam povolených služeb (obdoba výstupu z metody SERVICES), pokud např. nemá expediční místo povolenou paletovou přepravu u GEIS, tak ve výstupu nejsou služby vázané na peletovou přepravu. 115

116 B2A Tato metoda slouží k vytvoření objednávky pro přepravu zásilky z místa B (typicky dodavatel nebo předchozí příjemce zásilek klienta) do místa A (expediční místo z profilu vyplněného v klientské zóně). Důležité je neplést si tuto službu s příznakem swap (atribut na úrovni metody ADD, výměnná zásilka). Tuto službu nenabízí všichni implementovaní přepravci a její vytváření se liší. V některých případech je téměř totožná s metodou ADD, v některých je zadávání zjednodušeno. Na dalších stránkách je tato metoda popsaná pro jednotlivé přepravce. 116

117 B2A PPL Parcel Vyzvednutí balíku jinde, než je smluvně dáno (svozové místo). Balíky nejsou označeny etiketou a plátce je objednavatel. Štítky přiváží řidič na místo vyzvednutí ( B ). API endpoint: klíč povinná popis rec_name Jméno a příjmení místa vyzvednutí. Povinný v případě neuvedení rec_firm. rec_firm Název firmy místa vyzvednutí. Povinný v případě neuvedení rec_name. service_type rec_phone rec_ 1 PPL Parcel Business CZ (místo vyzvednutí v CZ ) 11 PPl Parcel Import (místo vyzvednutí v SK ) Telefonní číslo místa vyzvednutí. Formát čísla (uvádějte i s předvolbou): +AAAXXXYYYZZZ místa vyzvednutí. rec_street Ulice místa vyzvednutí. rec_city Adresační město místa vyzvednutí. rec_zip PSČ místa vyzvednutí, uvádějte bez mezer ve formátu XXXXX Kód země místa vyzvednutí dle ISO alpha-2 (viz. rec_country Zasílá se buď CZ (service_type = 1) nebo SK (service_type = 11) eid Unikátní ID objednávky přepravy v rámci expedičního místa. pieces_count Počet balíků připravených na nakládku. Výchozí hodnota je 1. real_order_id return_full_errors note pickup_date Referenční číslo objednávky přepravy. Pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean). Poznámka přepravci (maximální délka 300 znaků, delší text se zkrátí). Datum (formát YYYY-MM-DD) plánované reallizace přepravy (vyzvednutí balíků na místě B ). Pokud není vyplněné přiřazuje se automaticky datum následujícího pracovního dne. pickup_time_from Není povinné. Preferovaný čas přepravy OD. Formát HH:mm ( např. 13:30). pickup_time_to Není povinné. Preferovaný čas přepravy DO. Formát HH:mm ( např. 15:30). 117

118 Request příklad (objednávka přepravy na 3 balíky): [{ }] "eid":" ", "service_type":"1", "pickup_date":" ", "pickup_time_from":"13:30", "pickup_time_to":"15:30", "pieces_count":3, Response příklad: { "0": { }, "package_id": 24, "status_message": "OK, přeprava byla objednána.", "status": "200" "status": "200"} package_id unikátní ID objednávky v rámci přepravce v API. status_message textové vyjádření standardního výstupu status. status vyjádření jak operace dopadla (možné hodnoty: 200 OK, 208 přeprava pod zaslaným eid již byla objednána dříve, 400 Chyba při validaci dat, 503 Chyba při vytváření objednávky). 118

119 B2A Geis Parcel Vytváří zásilku typu objednávka produktu Parcel. Objednávku lze vytvořit nejdříve na následující pracovní den. Štítky přiváží řidič na místo vyzvednutí ( B ). Objednat přepravu lze z CZ do CZ, SK do SK, CZ do SK nebo SK do CZ. Oproti klasické metodě ADD je zde měné atributů (není možné například připojištění) + se počet balíků zadává přes atribut pieces_count. API endpoint: klíč povinná popis rec_name Jméno a příjmení místa vyzvednutí. rec_firm rec_phone Název firmy místa vyzvednutí. Telefonní číslo místa vyzvednutí, povinné pro soukromé zásilky (B2C), formát čísla (je potřeba zadávat i s předvolbou): +AAAXXXYYYZZZ rec_ místa vyzvednutí. rec_street Ulice místa vyzvednutí. rec_city Adresační město místa vyzvednutí. rec_zip PSČ místa vyzvednutí, uvádějte bez mezer ve formátu XXXXX. rec_country service_type branch_id Kód země místa vyzvednutí dle ISO alpha-2 (viz. ID služby, kterou se bude zásilka posílat: 1 Soukromá vnitrostátní přeprava (B2C) 2 Firemní vnitrostátní přeprava (B2B) 6 Geis Point 3 Mezinárodní firemní přeprava (B2B) 9 Mezinárodní soukromá přeprava (B2C) ID pobočky Geis Pointu (CZ nebo SK), na níž je zásilka určena k výdeji (seznam dostupný přes metodu BRANCHES se service_type 6 ). cod_price Výše doběrečného, povinné pro dobírkové zásilky. Datový typ float. Měna dobírky dle ISO 4217 kódu cod_currency bank_account_number (pro Kč je například CZK, pro euro je EUR). Povinná položka v případě, že je zasláno cod_price > 0. IBAN bankovního účtu, na který má být zaslána vybraná dobírka, uvádí se pouze v případě, že má být dobírka zaslána na jiný, než výchozí účet zvolený 119

120 v administraci přepravce. eid Unikátní ID objednávky přepravy v rámci expedičního místa. pieces_count Počet balíků připravených na nakládku. Výchozí hodnota je 1. real_order_id weight note_driver note_recipient reference return_full_errors Reálné číslo objednávky (zobrazuje se na přepravních štítcích a předává se datově přepravci, pokud není vyplněno, tak se předává eid), doporučujeme ho tedy vyplňovat, pokud do povinného eid zasíláte jiné hodnoty. Váha zásilky v kg, datový typ float. Poznámka přepravci (maximální délka 50 znaků). Poznámka příjemci (maximální délka 50 znaků). Zákaznická reference, maximální délka 20 alfanumerických znaků. Pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean). pickup_date Datum (formát YYYY-MM-DD) plánované reallizace přepravy (vyzvednutí balíků na místě B ). Pokd není vyplněné přiřazuje se automaticky datum následujícího pracovního dne. Maximální počet dní na objednání přepravy dopředu je 30. Request příklad (objednávka přepravy na 3 balíky, cílové místo Geis Point): [{ "eid":" ", "service_type":"6", "branch_id":"gp ", "pickup_date":" ", "pieces_count":3, }] 120

121 Response příklad: { "0": { }, "carrier_id": " ", "package_id": 24, "track_url": " "status_message": "OK, přeprava byla objednána.", "status": "200" "status": "200"} carrier_id ID objednávky v rámci dopravce, používá se pro případný track&trace (metoda TRACK). package_id unikátní ID objednávky v rámci přepravce v API. track_url URL na tracking přepravy. status_message textové vyjádření standardního výstupu status. status vyjádření jak operace dopadla (možné hodnoty: 200 OK, 208 přeprava pod zaslaným eid již byla objednána dříve, 400 Chyba při validaci dat, 503 Chyba při vytváření objednávky). 121

122 B2A Geis Cargo Vytváří zásilku typu objednávka produktu Cargo. Objednávku lze vytvořit nejdříve na následující pracovní den. Štítky přiváží řidič na místo vyzvednutí ( B ). V případě objednávky vyzvednutí více různých manipulačních jednotek (mu_type) zasílejte všechna data v jednom requestu (technicky není možné přidat k již vytvořené objednávce přepravy další kusy k vyzvednutí). API endpoint: klíč povinná popis rec_name Jméno a příjmení místa vyzvednutí. rec_firm Název firmy místa vyzvednutí. rec_phone Telefonní číslo místa vyzvednutí, povinné pro soukromé zásilky (B2C) a doplňkové služby telefonické avízo (AVI) a SMS avízo (SMS), formát čísla: +420XXXYYYZZZ. rec_ místa vyzvednutí. rec_street Ulice místa vyzvednutí. rec_city Město místa vyzvednutí. rec_zip PSČ místa vyzvednutí, uvádějte bez mezer ve formátu XXXXX. Kód země místa vyzvednutí dle ISO alpha-2 (viz. rec_country service_type cod_price cod_currency výchozí hodnotou je Česká republika (CZ). ID služby, kterou se bude zásilka posílat: 4 Vnitrostátní paletová zásilka B2B 10 Vnitrostátní paletová zásilka B2C Výše doběrečného, povinné pro dobírkové zásilky. Datový typ float. Měna dobírky dle ISO 4217 kódu (pro Kč je například CZK, pro euro je EUR). Povinná položka v případě, že je zasláno cod_price > 0. eid Unikátní ID objednávky přepravy v rámci expedičního místa. order_number Povinný pro sdružené zásilky, u samostatných se nemusí uvádět. real_order_id Reálné číslo objednávky předává se jako referenční číslo. 122

123 mu_type pieces_count Kód manipulační jednotky (jejich seznam s názvy získáte metodou MANIPULATIONUNITS). Počet nákladových kusů stejné manipulační jednotky (např. pokud je součástí zásilky 5 amerických palet, bude hodnota 5), pokud je nákladový kus od manipulační jednotky pouze 1, není potřeba uvádět hodnotu. weight Celková váha nákladového kusu/kusů v kg, datový typ float. volume Celkový objem nákladového kusu/kusů v m3. note_driver note_recipient reference return_full_errors Poznámka řidiči (přenáší se datově, není vidět na štítku) dlouhá maximálně 62 znaků. Poznámka příjemci (přenáší se datově a je vidět i na štítku) dlouhá maximálně 62 znaků. Zákaznická reference, maximální délka 20 alfanumerických znaků. Pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean). Request příklad (objednávka přepravy na 3 kusy manipulační jednoty EP a 4 kusy manipulační jednotky UV): [{ "eid":" ", "order_number":1, "service_type":"10", "mu_type":"ep", "pickup_date":" ", "pieces_count":3, },{ "eid":" ", "order_number":2, "mu_type":"uv", "pieces_count":4, }] 123

124 Response příklad: { "0": { }, "carrier_id": " ", "package_id": 5, "track_url":" "status_message": "OK, přeprava byla objednána.", "status": "200" "status": "200"} carrier_id ID objednávky v rámci dopravce, používá se pro případný track&trace (metoda TRACK). package_id unikátní ID objednávky v rámci přepravce v API. track_url URL na tracking přepravy. status_message textové vyjádření standrního výstupu status. status vyjádření jak operace dopadla (možné hodnoty: 200 OK, 208 přeprava pod zaslaným eid již byla objednána dříve, 400 Chyba při validaci dat, 503 Chyba při vytváření objednávky). 124

125 B2A DPD Sběrný balík (není povolená vícekusová zásilka). Vyzvednutí balíku jinde, než je smluvně dáno (svozové místo). Balíky nejsou označeny etiketou a plátce je objednavatel. Štítky přiváží řidič na místo vyzvednutí ( B ). API endpoint: klíč povinná popis rec_name Jméno a příjmení místa vyzvednutí. Povinný v případě neuvedení rec_firm. rec_firm Název firmy místa vyzvednutí. Povinný v případě neuvedení rec_name. service_type rec_phone rec_ 1 B2B Classic 2 B2C Private Telefonní číslo místa vyzvednutí. Formát čísla (uvádějte i s předvolbou): +AAAXXXYYYZZZ místa vyzvednutí. rec_street Ulice místa vyzvednutí. rec_city Adresační město místa vyzvednutí. rec_zip PSČ místa vyzvednutí, uvádějte bez mezer ve formátu XXXXX Kód země místa vyzvednutí dle ISO alpha-2 (viz. rec_country Sběrný balík lze v současnosti objednat pouze v rámci CZ. eid Unikátní ID objednávky přepravy v rámci expedičního místa. real_order_id weight Referenční číslo objednávky přepravy. Váha balíku v kg. Pokud se nezašle, doplní se výchozí hodnota z konfigurace přepravce z klientské zóny. Datum (formát YYYY-MM-DD) plánované reallizace přepravy (vyzvednutí pickup_date note return_full_errors balíků na místě B ). Pokud není vyplněné přiřazuje se automaticky datum následujícího pracovního dne. Poznámka přepravci. Maximální délka 200 znaků. Pro navrácení chyb v textové podobě namísto standardních číselných kódů zašlete hodnotu 1 nebo TRUE (boolean). 125

126 Response příklad: { "0": { }, "carrier_id": " ", "package_id": 24, "status_message": "OK, přeprava byla objednána.", "status": "200" "status": "200"} carrier_id ID objednávky v rámci dopravce, používá se pro případný track&trace (metoda TRACK). package_id unikátní ID objednávky v rámci přepravce v API. status_message textové vyjádření standardního výstupu status. status vyjádření jak operace dopadla (možné hodnoty: 200 OK, 208 přeprava pod zaslaným eid již byla objednána dříve, 400 Chyba při validaci dat, 503 Chyba při vytváření objednávky). 126

127 Seznam zkratek států/provincií/okresů pro rec_region USA - státy Zkratka Alabama AL Alaska AK American Samoa AS Arizona AZ Arkansas AR California CA Colorado CO Connecticut CT Delaware DE District of Columbia DC Federated States of Micronesia FM Florida FL Georgia GA Guam GU Hawaii HI Idaho ID Illinois IL Indiana IN Iowa IA Kansas KS Kentucky KY Louisiana LA Maine ME Marshall Islands MH Maryland MD Massachusetts MA Michigan MI Minnesota MN Mississippi MS Missouri MO Montana MT Nebraska NE Nevada NV 127

128 New Hampshire New Jersey New Mexico New York North Carolina North Dakota Northern Mariana Islands Ohio Oklahoma Oregon Palau Pennsylvania Puerto Rico Rhode Island South Carolina South Dakota Tennessee Texas Utah Vermont Virgin Islands Virginia Washington West Virginia Wisconsin Wyoming NH NJ NM NY NC ND MP OH OK OR PW PA PR RI SC SD TN TX UT VT VI VA WA WV WI WY Kanada - provincie a státy Zkratka Alberta AB British Columbia BC Manitoba MB New Brunswick NB Newfoundland and Labrador NL Northwest Territories NT Nova Scotia NS 128

129 129 Nunavut NU Ontario ON Prince Edward Island PE Quebec QC Saskatchewan SK Yukon YT Irsko - okresy Zkratka Carlow CW Cavan CN Clare CE Cork CO Donegal DL Dublin D Galway G Kerry KY Kildare KE Kilkenny KK Laois LS Leitrim LM Limerick LK Longford LD Louth LH Mayo MO Meath MH Monaghan MN Offaly OY Roscommon RN Sligo SO Tipperary TA Waterford WD Westmeath WH Wexford WX Wicklow WW

130 Seznam názvů dopravců v URL requestech cp Česká pošta s.p., nasazeno dhl DHL Express, nasazeno dhlsk DHL Parcel Slovensko, nasazeno dpd Direct Parcel Distribution CZ s.r.o., nasazeno geis Geis CZ s.r.o., Parcel i Cargo, CZ i SK verze nasazeno gls General Logistics Systems Czech Republic s.r.o., nasazeno intime IN TIME SPEDICE s. r.o., nasazeno pbh Pošta bez hranic (Frogman s.r.o.), nasazeno ppl PPL CZ s.r.o. Parcel i Sprint, nasazeno sp Slovenská pošta a.s., nasazeno sps Slovak Parcel Service s.r.o., nasazeno tnt TNT, nasazeno toptrans TOPTRANS EU a.s., nasazeno ulozenka Uloženka s.r.o., nasazeno ups UPS, nasazeno zasilkovna Zásilkovna s.r.o., nasazeno 130

131 Seznam významu návratových kódů parametru status 200 OK, operace proběhla v pořádku. 208 položka s doloženým ID již existuje. Data, která jsou navrácena, patří k původnímu záznamu. 400 operace neproběhla v pořádku, zkontrolujte konkrétní data. 403 přepravce není pro použité klíče aktivovaný. 404 zásilka neexistuje, nebo již byla zpracována. 406 nedorazila žádná data ke zpracování nebo nemůžou být akceptována. 409 konfigurační soubor daného dopravce nebo profil není vyplněn/konflikt mezi přijatými daty u zásilky (například u DPD pokud je u zásilky, která má být zaslána službou DPD Classic, zaslána dobírka cod_price a zároveň příznak, že se jedná o výměnnou zásilku swap, zašle se v navrácených datech u obou těchto atributů error code 409 konflikt dat). 413 špatný formát dat. 423 tato funkce je dostupná jen pro živé klíče. 501 technologie toho dopravce ještě není implementována, pro bližší informace sledujte web technologie dopravce není dostupná, požadavek bude vyřízen později. 131

132 Tabulka chybových statusů z metody ADD - doporučujeme používat atribut return_full_errors = 1, který je přesnější a vrací texty rozšířené status klíč Textový popis 404 insert_error Chyba při ukládání dat do systému. 406 eid Nedorazilo eshop ID. 406 service_type Nedorazilo ID vybrané služby přepravce. 406 cod_currency Nedorazil ISO kód měny. 406 branch_id Nedorazilo ID pobočky. 406 rec_name Nedorazilo jméno příjemce. 406 rec_street Nedorazila ulice s číslem popisným příjemce. 406 rec_city Nedorazilo město příjemce. 406 rec_zip Nedorazilo PSČ příjemce. 406 rec_country Nedorazil ISO kód země příjemce. 406 rec_phone Nedorazilo telefonní číslo příjemce. 406 rec_ Nedorazil příjemce. 406 price Nedorazila udaná cena zásilky. 406 vs Nedorazil variabilní symbol pro dobírkovou zásilku. 406 service_range Balíček nelze přidat, protože není vyplněna číselná řada v klientské zóně. 406 config_data Balíček nelze přidat, protože chybí potřebná data v klientské zóně. 406 weight Nedorazil údaj o váze zásilky. 413 eid Eshop ID je delší než je maximální povolená délka. 413 service_type Neznámé ID služby přepravce. 413 cod_price Nepovolená dobírka. 413 cod_currency Nepovolený ISO kód měny. 413 price Nepovolená částka udané ceny. 413 branch_id Neznámé ID pobočky. 413 rec_ Špatný formát u příjemce. 132

133 413 order_number Sdružená zásilka není povolena. 413 rec_country Nepovolený ISO kód země příjemce. 413 rec_zip Nepovolené PSČ příjemce. 413 weight Neplatný formát váhy/váha překračuje maximální povolenou hodnotu. 413 swap Výměnná zásilka není pro vybrau službu povolena. 413 rec_phone Špatný formát telefonního čísla. 413 credit_card Platba kartou není pro tuto službu/pobočku povolena. 413 service_range Balíček nelze přidat, protože číselná řada v klientské zóně je již přečerpaná. 413 b2c_service Službu B2C service není možné použít. Zkontrolujte, zda ji máte povolenou na straně přepravce. 413 credit_card Služba platba dobírky kartou není možná. Zkontrolujte, zda ji máte povolenou na straně přepravce. 413 del_insurance Zásilku není možno připojistit. 413 del_exworks Služba exworks není možná. Zkontrolujte, zda ji máte povolenou na straně přepravce. 413 mu_type Nepovolený kód manipulační jednotky. 413 pieces_count Počet nákladových kusů musí být alespoň sms_notification Služba SMS avízo není povolená. 413 phone_notification Služba telefonické avízo není povolená. 413 pers_delivery Služba doručení do oddělení potřebuje zaslat všechny potřebné informace budovu, poschodí i kancelář. 416 delivery_date Datum má špatný formát nebo není povoleno. 409 cod_price + swap Nepovolená kombinace služeb dobírky a výměnné zásilky. 133

134 Tipy pro implementátory 1. Pozor na atributy price a cod_price u metody ADD. Price je udaná cena zásilky, tzn. hodnota balíků. Cod_price je finální cena dobírky, kterou má zákazník zaplatit. 2. Update údajů jednotlivých balíků není možný. Pokud potřebujete změnit údaje na některé zásilce, je potřeba ji nejprve odmazat pomocí metody DROP a poté znovu vložit přes metodu ADD. 3. Pro plné využití možností Balikobotu Vám doporučujeme ukládat veškeré hodnoty (mimo statusů), které dostáváte nazpět. Tzn.: a) carrier_id (číslo balíku v rámci dopravce parametr pro metodu TRACK), package_id (číslo balíku v rámci API Balikobot parametr pro metodu DROP), label_url (štítek pro konkrétní balík), labels_url (PDF se štítky pro balíky z posledního requestu) z metody ADD. b) order_id (číslo objednaného svozu, přes tento identifikátor můžete využít metody ORDERVIEW pro zpětné získání informací o konkrétním svozu), file_url (odkaz pro stažení datové věty České pošty), handover_url (PDF s předávacím listem pro dopravce), labels_url (PDF se štítky všech balíků zahrnutých pro tento svoz) z metody ORDER. 4. Pokud se vám nedaří komunikovat s API, resp. nedostáváte žádné odpovědi, přidejte si do nastavení curl requestu tento řádek: curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); Některé servery můžou mít problém s naším certifikátem. 5. Při testování dopravce Uloženka se vrací v PDF jen ukázkové štítky, které nekorespondují se zaslanými daty. Pro ostré API klíče pak jsou již data v pořádku. 6. Jedním z kritických bodů správného napojení je správné namapování služeb (atribut service_type v metodě ADD) u jednotlivých přepravců na metodu SERVICES (99). Výsledek je vidět v kapitole Příklad implementace v administraci obchodu (137). 134

135 Příklad implementace v administraci obchodu V příkladu implementace je vidět jak by měla být provedena implementace API Balikobot na detailu objednávky a přehledu objednávek. Přehled objednávek Tisk štítku (metoda ADD), smazání štítku (metoda DROP), sledování zásilky (metoda TRACK), hromadný tisk štítků (metoda LABELS) a předání dat přepravci - objednání svozu (metoda ORDER) by měly být součástí přehledu objednávek pro komfortní práci uživatele. Na obrázku níže je vidět 9 objednávek (ID 1-9). Stavy ve stejnojmenném sloupci berte jen jako orientační. Poslední 3 objednávky (ID 1-3) jsou již vyřízené (stav Vyřízená ), zaslané do Balikobotu a byly součástí některého předchozího svozu. Proto mají ve sloupci Akce dostupná tlačítka Sledování zásilky (po stisku request na API metodou TRACK) a Tisk štítku (odkaz na PDF máte již z dřívějšího dotazu na API metodou ADD nezapomeňte si vždy návratová data uložit!). Obrázek 1 - Přehled objednávek 135

136 Prostřední 3 objednávky (ID 4-6) mají stav K expedici a fyzicky jsou ještě na skladě eshopu. Uživatel má v tu chvíli možnost ještě upravit objednávku (v tu chvíli je potřeba odmazat jí z API metodou DROP a poté znovu vytvořit metodou ADD, jinak u ní zůstau původní data), nebo ji úplně zrušit tlačítko Smazání štítku (metoda DROP, smaže zásilku z API Balikobot nebude předána datově přepravci). Pro opětovné vytisknutí štítku slouží tlačítko Tisk štítku (odkaz na PDF máte již z dřívějšího dotazu na API metodou ADD nezapomeňte si vždy návratová data uložit!). Tyto objednávky se odesílají do svozu. Objednávky s ID 7-9 mají stav Nevyřízená a data z této objednávky ještě vůbec nebyla zaslána do Balikobotu. Proto má uživatel možnost jen vytisknout štítek (metoda ADD zaslání dat do API). Pro hromadný tisk štítků lze využít checkboxů u jednotlivých objednávek a tlačítka Tisk štítků (metoda LABELS dá se použít pro objednávky, které jsou již zaslány do API). Pro předání dat přepravci slouží tlačítko Objednat svoz (metoda ORDER). 136

137 Detail objednávky nezaslaná do API Objednávka, která ještě nebyla zaslána do API Balikobot by měla mít na svém detailu několik důležitých informací: přepravce (pokud si uživatel chce změnit na jiného), výběr konkrétní služby přepravce (data dodávaná metodou SERVICES), zvolení počtu balíků (pokud se jedná o sdruženou zásilku, tak může být zásilka tvořená více balíky) a input box pro doplnění váhy zásilky (pokud váha není vyplněná, předáváme výchozí váhu nastavenou v klientské zóně obchodu). Nesmí chybět tlačítko Tisk štítku přes které metodou ADD zašlete data o objednávce a v návratových hodnotách (ukládejte si všechny navrácené hodnoty ke každé objednávce) je odkaz na PDF se štítkem, který pak můžete uživateli zobrazit. Obrázek 2 - Detail objednávky před odesláním do API 137

138 Detail objednávky zaslaná do API, před objednáním svozu Objednávka, která již byla zaslána do API Balikobot (ale ještě nebyla předána ke svozu) by měla mít na svém detailu, oproti ještě nezaslané objednávce do API, tlačítko Smazání štítku. Smazáním štítku se myslí odmazání dat o této konkrétní objednávce z API (metoda DROP). Pokud si po odmazání uživatel klikne na Tisk štítku, je potřeba zaslat tedy znovu všechna data o objednávce (metoda ADD). K odmazání z API by mělo nastávat ve dvou případech: 1) pokud se objednávka zrušila na straně eshopu a nebude se tak expedovat, 2) pokud uživatel po prvním odeslání dat do API editoval objednávku a je potřeba data upravit i v API, aby se změny projevili na štítku a v předaných datech dopravci po takovémto odmazání je potřeba při kliknutí na tlačítko Tisk štítku zaslat nová data do API (metoda ADD) a navrácené hodnoty si uložit. DŮLEŽITÉ! Obrázek 3 - Detail objednávky v API před objednáním svozu 138

139 Detail objednávky zaslaná do API, po předání dat přepravci Objednávka, která již byla zaslána do API Balikobot a byla zároveň vyexpedována (zaslána ke svozu), by měla mít na svém detailu tlačítko Tisk štítku (odkaz na PDF se štítkem získaný z metody ADD) a tlačítko Sledování zásilky (metoda TRACK). Obrázek 4 - Detail objednávky zaslané do API a vyexpedované 139

140 Tisk štítku Před tiskem PDF se štítkem/štítky je potřeba umožnit uživateli vybrat pozici na které/od které se štítky zobrazí (vybrau pozici pak jednoduše předejte v GET parametru v URL na štítek například pro výběr pozice 3 se poté za URL dolepí?p=3 ). Obrázek 5 - Tisk štítku U dopravců Zásilkovna a Intime jsou pro úsporu tisku štítky na 1/8 A4 uživatelé si tedy mohou vybrat z osmi pozic! U zbylých přepravců jsou štítky na 1/4 A4 (viz Obrázek 2). Pozor na zobrazení PDF s jedním štítkem! Pokud si uživatel nevybere pozici, tak je navrácen štítek s rozměry pro Zebra tiskárny (1/4 A4) a při tisku na A4 formát se mu bez předchozího nastavení štítek roztáhne přes celou stránku nebo se zarovná na střed! 140

141 Sledování zásilky (Track & Trace) Pro rychlé dohledání stavu zásilky doporučujeme umístit tlačítko Sledování zásilky jak na přehled objednávek, tak na detail objednávky. Po kliknutí na tlačítko je potřeba zaslat nám požadavek (metodou TRACK s číslem zásilky) a API vrátí pole (array) všech stavů, ve kterých se zásilka dosud nacházela, seřazených od nejnovějšího po nejstarší (index 0 poslední stav). Obrázek 6 - Sledování zásilky pop-up Nejlepším způsobem jak doručené informace zobrazit je pop-up okno, například jako na obrázku výše. 141

142 Předání dat přepravci - objednání svozu Po kliknutí na tlačítko Objednat svoz doporučujeme zobrazit kontrolní výpis s počty objednávek ke svozu. Uživatel pak může následně objednat svoz zvláště pro jednoho dopravce (metoda ORDER s parametrem přepravce) nebo všechny najednou (metoda ORDER zavolaná tolikrát, kolik je dopravců, vždy s parametrem daného přepravce. Počty balíků máte jednak uložené na vaší straně, nebo si je můžete vyžádat pro kontrolu přes metodu ORDERVIEW. Obrázek 7 Předání dat přepravci - objednání svozu 142