ONLINE API GLS GLS online webová služba SOAP pro tiskové služby

Transkript

1 ONLINE API GLS GLS online webová služba SOAP pro tiskové služby URL: HU - SK - CZ - RO - SI - HR -

2 Popis WSDL Styl rpc Typ operace: Požadavek-odpověď. Koncový bod přijme zprávu a odešle zpět příslušnou zprávu (odpověď). SOAP akce: printlabel Vstup: printlabelrequest (soap:body, use = encoded) *username typ string - uživatelské jméno vyžádejte si od GLS *password typ string - heslo vyžádejte si od GLS *senderid typ string - zákaznické číslo GLS vyžádejte si od GLS *sender_name typ string - jméno odesilatele *sender_address typ string - adresa odesilatele *sender_city typ string - město odesilatele *sender_zipcode typ string - PSČ odesilatele *sender_country typ string - kód země nebo název země odesilatele sender_contact typ string - kontaktní osoba odesilatele sender_phone typ string - telefon odesilatele sender_ typ string - ová adresa odesilatele *consig_name typ string - jméno příjemce *consig_address typ string - adresa příjemce *consig_city typ string - město příjemce *consig_zipcode typ string - PSČ příjemce *consig_country typ string - kód země nebo název země příjemce consig_contact typ string - kontaktní osoba příjemce consig_phone typ string - telefon nebo SMS číslo příjemce pro služby consig_ typ string - ová adresa příjemce bude také použitá pro služby *pcount typ int - počet balíků / štítků k vytištění *pickupdate typ string - datum vyzvednutí ve tvaru yyyy-mm-dd (rok-měsíc-den) content typ string - obsah balíku informace vytištěná na štítku clientref typ string - reference zákazníka codamount typ decimal - částka k dobírce codref typ string - reference dobírky použito, pokud je nastavena částka k dobírce services typ svcdataarray - pole s položkami typu svcdata - pole služeb code typ string - třípísmenný kód služby, viz seznam služeb v Příloze A info typ string - parametr pro službu

3 *printertemplate typ string *printit typ Boolean uložen v seznamu *timestamp typ string *hash typ string customlabel typ Boolean - typ tiskárny seznam v příloze B - true (pravda) pokud má být štítek vytištěn, false (nepravda) pokud má být - timestamp (časové razítko) požadavku ve formátu yyyymmddhhmmss - otisk (hash) požadavku Příloha C - pokud je true (pravda), zajistí klient tisk žádná data štítku nejsou vrácena - *Povinná pole jsou označena hvězdičkou - za nepovinné hodnoty nedosazujte null, je potřeba prázdný řetězec o do services dosaďte alespoň prázdné pole - abychom se vyhnuli zneužití služby (spam), povolujeme pouze 5 totožných požadavků za 5 minut. Pokud potřebujete vytisknout více štítků se stejnými údaji, vložte počet do proměnné pcount

4 Výstup: printlabelresponse (soap:body, use = encoded) return typ printlabel_result pcls typ ArrayOfString - pole s prvky typu string vrací seznam vytištěných čísel balíků pcls_withcheckdigit typ ArrayOfString - pole s prvky typu string vrací seznam čísel balíků s kontrolní číslicí (checkdigit) pdfdata typ string - pdf data pro vytištění nebo pro zobrazení pdf. Kódováno funkcí base64 depo typ string - dodatečná data pro vlastní tisk u klienta driver typ string - dodatečná data pro vlastní tisk u klienta successfull typ Boolean - pokud je nepravda (false), budou nastaveny errcode a errdesc errcode typ int - číselný kód chyby, viz Příloha D errdesc typ string - popis chyby - pcls a pdfdata jsou vracena pouze, pokud je printit pravda (true) a zároveň je successfull pravda (true) - depo a driver se vrací pouze, pokud je customlabel pravda (true) v takovém případě se nevrací žádná pdfdata - ukázkový kód pro klienta NuSOAP naleznete client v Příloze E - ukázkový kód v C# pro použití pdfdata z výsledku naleznete v Příloze F

5 Příloha A Seznam služeb Kód služby T12 Název služby Express Service Parametr PSS Pick&Ship Service Datum převzetí ve formátu yyyy-mm-dd (rok-měsíc-den) PRS Pick&Return Service Datum převzetí ve formátu yyyy-mm-dd (rok-měsíc-den) XS Exchange Service pro zpáteční balík je nutné vytisknout druhý štítek SZL DocumentReturn Service Číslo dokumentu string (řetězec), max. 15 znaků INS DeclaredValueInsurance Service Hodnota balíku SBS Standby Service DDS DayDefinite Service Datum dodání ve formátu yyyy-mm-dd (rok-měsíc-den) SDS ScheduledDelivery Service Časový rozsah dodávky ve formátu HH:mm-HH:mm SAT Saturday Service AOS AddresseeOnly Service Lze použít jméno příjemce/kontaktní osoby 24H EXW Guaranteed24 Service Exworks Service Service SM1 SMS Service Telefonní číslo pro SMS a text SMS ve formátu telefonní č. v mezinárodním formátu sms text. Pro číslo balíku lze použít proměnnou #ParcelNr#. SM2 PreAdvice Service Telefonní číslo pro SMS v mezinárodním formátu CS1 Contact Service Lze použít telefonní číslo příjemce/kontaktní telefonní číslo TGS ThinkGreen Service FDS FlexDelivery Service FSS FlexDeivery SMS Service Telefonní číslo pro SMS v mezinárodním formátu není k dispozici bez FDS PSD ShopDelivery Service DropOffPoint ID DPV DeclaredParcelValue Používá se pro HR s PSČ 20xxx pro deklaraci hodnoty balíku - ne všechny služby jsou k dispozici v každé zemi a v každé oblasti - u služeb PSS/PRS není štítek vytištěn, je pouze objednána služba

6 Příloha B Typy tiskových šablon Typ A6 A6_PP A6_ONA4 A4_2x2 A4_4x1 T_85x85 Popis Formát A6, prázdný štítek Formát A6, předtištěný štítek Formát A6, vytištěno na A4 Formát A4, 4 etikety v rozložení 2x2 Formát A4, 4 etikety v rozložení 4x1 termoetikety formátu 85x85 mm

7 Příloha C Kontrolní otisk (hash) otisk (hash) slouží k ověření integrity odeslaného požadavku výpočet: spojte obsah následujících parametrů do řetězce (string) a použijte nad nimi algoritmus sha1(): username, password, senderid, sender_name, sender_address, sender_city, sender_zipcode, sender_country, sender_contact, sender_phone, sender_ , consig_name, consig_address, consig_city, consig_zipcode, consig_country, consig_contact, consig_phone, consig_ , pcount, pickupdate, content, clientref, codamout, codref (všechny vstupní parametry kromě services, printertemplate, printit, timestamp, hashcode) Ukázková funkce v PHP: function gethash($data) { $hashbase = ''; foreach($data as $key => $value) { if ($key!= 'services' && $key!= 'hash' && $key!= 'timestamp' && $key!= 'printit' && $key!= 'printertemplate' && $key!= 'customlabel') { $hashbase.= $value; return sha1($hashbase); Ukázková funkce v C#: using System.Security.Cryptography; private string gethash() { string expression = string.format("{0{1{2{3{4{5{6{7{8{9{10{11{12{13{14{15{16 {17{18{19{20{21{22{23{24", user, pwd, senderid, sendername, senderaddress, sendercity, senderzipcode, sendercountry, sendercontact, senderphone, sender , consigname, consigaddress, consigcity, consigzipcode, consigcountry, consigcontact, consigphone, consig , pcount, pickupdate, content, clientref, codamount, codref)); SHA1 sha1 = SHA1.Create(); string hash = sha1.computehash(system.text.encoding.utf8.getbytes(expression)); return BitConverter.ToString(hash).Replace("-", "").ToLower();

8 Příloha D Chybové kódy Typ Popis 0 OK 1 Autentizace se nezdařila 2 Neplatný hash (otisk) 3 Data se nepodařilo uložit, zkuste to prosím později 4 Neplatná tisková šablona, konzultujte prosím dokumentaci 5 Chybějící parametry: 6 Neplatné časové razítko (timestamp) 7 Neplatná země odesilatele 8 Neplatná země příjemce 9 Neplatná země odesilatele 10 Neplatné PSČ příjemce 11 Neplatné datum převzetí 12 Počet balíků musí být 1 do Chybí kontaktní osoba pro exportní balík 14 Pro tuto exportní zemi není povolena dobírka 15 Maximální hodnota dobírky je: 16 Neplatné zaokrouhlování dobírky - nejmenší část je 17 Neplatný kód služby/služeb: 18 Neplatná/neplatné kombinace služeb: 19 Služba/služby není/nejsou k dispozici v zemi převzetí: 20 Služba/služby není/nejsou k dispozici mezi zemí odesílatele a zemí příjemce: 21 Služba/služby není/nejsou k dispozici v zemi/psč příjemce: 22 Neplatné/chybějící parametry služby/služeb: 23 Služba FSS je platná pouze s objednanou službou FDS 24 U balíků do HR s PSČ 20xxx prosím odešlete deklarovanou hodnotu balíku přes parametr DPV 25 V posledních 5 minutách byl odeslán stejný požadavek pětkrát!

9 Příloha E Ukázkový PHP kód v klientu NuSOAP <?php require_once('lib/nusoap.php'); $_HTTP =!empty($_server['https'])? ' : ' $wsdl_path = $_HTTP.$_SERVER['HTTP_HOST'].'/webservices/soap_server.php?wsdl&ver= '; $client = new nusoap_client($wsdl_path,'wsdl'); $client->soap_defencoding = 'UTF-8'; $client->decode_utf8 = false; $in = array( 'username' => 'username', 'password' => 'password', 'senderid' => ' ', 'sender_name' => 'sendername', 'sender_address' => 'senderaddress', 'sender_city' => 'sendercity', 'sender_zipcode' => '2351', 'sender_country' => 'HU', 'sender_contact' => 'sendercontact', 'sender_phone' => 'senderphone', 'sender_ ' => 'valaki@valaki.sk', 'consig_name' => 'consigname', 'consig_address' => 'consigaddress', 'consig_city' => 'consigcity', 'consig_zipcode' => '2351', 'consig_country' => 'HU', 'consig_contact' => 'consigcontact', 'consig_phone' => 'consigphone', 'consig_ ' => 'valaki@valaki.sk', 'pcount' => 1, 'pickupdate' => ' ', 'content' => 'tartalom', 'clientref' => 'clientref', 'codamount' => '1526', 'codref' => 'codref', 'services' => array(), 'printertemplate' => 'A4_2x2', 'printit' => true, 'timestamp' => ' ', 'hash' => 'xsd:string', 'customlabel' => false ); $in['hash'] = gethash($in); $return = $client->call('printlabel', $in); if ($return) { if ($return['successfull']) { header('contenttype: application/pdf'); die(base64_decode($return['pdfdata'])); else { var_dump($return);

10 function gethash($data) { $hashbase = ''; foreach($data as $key => $value) { if ($key!= 'services' && $key!= 'hash' && $key!= 'timestamp' && $key!= 'printit' && $key!= 'printertemplate' && $key!= 'customlabel') { $hashbase.= $value; return sha1($hashbase);?>

11 Přidání reference k projektu: Příloha F Použití pdfdata z výsledku v C# (Visual Studio 2008)

12 Pro přijímání metod z webové reference použijte přidaný jmenný prostor (namespace): Příklad zpracování výsledků: byte[] data = Convert.FromBase64String(result.pdfdata); System.IO.File.WriteAllBytes(@"c:\temp\label.pdf", data);