ONLINE API GLS GLS online webová služba SOAP pro tiskové služby
URL: HU - https://online.gls-hungary.com/webservices/soap_server.php?wsdl&ver=14.11.03.01 SK - https://online.gls-slovakia.sk/webservices/soap_server.php?wsdl&ver=14.11.03.01 CZ - https://online.gls-czech.com/webservices/soap_server.php?wsdl&ver=14.11.03.01 RO - https://online.gls-romania.ro/webservices/soap_server.php?wsdl&ver=14.11.03.01 SI - https://connect.gls-slovenia.com/webservices/soap_server.php?wsdl&ver=14.11.03.01 HR - https://online.gls-croatia.com/webservices/soap_server.php?wsdl&ver=14.11.03.01
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_email typ string
- emailová 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_email typ string
- emailová 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
-
*printertemplate typ string
- typ tiskárny – seznam v příloze B
*printit typ Boolean uložen v seznamu
- true (pravda) pokud má být štítek vytištěn, false (nepravda) pokud má být
*timestamp typ string
- timestamp (časové razítko) požadavku ve formátu yyyyMMddHHmmss
*hash typ string
- otisk (hash) požadavku – Příloha C
customlabel typ Boolean
- 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
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
Příloha A Seznam služeb
Kód služby
Název služby
T12
Express Service
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
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
24H
Guaranteed24 Service
EXW
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
E-mail
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
-
Parametr
pro zpáteční balík je nutné vytisknout druhý štítek
Lze použít jméno příjemce/kontaktní osoby
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
Příloha B Typy tiskových šablon
Typ
Popis
A6
Formát A6, prázdný štítek
A6_PP
Formát A6, předtištěný štítek
A6_ONA4
Formát A6, vytištěno na A4
A4_2x2
Formát A4, 4 etikety v rozložení 2x2
A4_4x1
Formát A4, 4 etikety v rozložení 4x1
T_85x85
termoetikety formátu 85x85 mm
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_email, consig_name, consig_address, consig_city, consig_zipcode, consig_country, consig_contact, consig_phone, consig_email, 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, senderEmail, consigName, consigAddress, consigCity, consigZipcode, consigCountry, consigContact, consigPhone, consigEmail, 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(); }
Příloha D Chybové kódy
Typ
Popis 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 25
OK Autentizace se nezdařila Neplatný hash (otisk) Data se nepodařilo uložit, zkuste to prosím později Neplatná tisková šablona, konzultujte prosím dokumentaci Chybějící parametry: Neplatné časové razítko (timestamp) Neplatná země odesilatele Neplatná země příjemce Neplatná země odesilatele Neplatné PSČ příjemce Neplatné datum převzetí Počet balíků musí být 1 do 99 Chybí kontaktní osoba pro exportní balík Pro tuto exportní zemi není povolena dobírka Maximální hodnota dobírky je: Neplatné zaokrouhlování dobírky - nejmenší část je Neplatný kód služby/služeb: Neplatná/neplatné kombinace služeb: Služba/služby není/nejsou k dispozici v zemi převzetí: Služba/služby není/nejsou k dispozici mezi zemí odesílatele a zemí příjemce: Služba/služby není/nejsou k dispozici v zemi/PSČ příjemce: Neplatné/chybějící parametry služby/služeb: Služba FSS je platná pouze s objednanou službou FDS U balíků do HR s PSČ 20xxx prosím odešlete deklarovanou hodnotu balíku přes parametr DPV V posledních 5 minutách byl odeslán stejný požadavek pětkrát!
Příloha E Ukázkový PHP kód v klientu NuSOAP soap_defencoding = 'UTF-8'; $client->decode_utf8 = false; $in = array( 'username' => 'username', 'password' => 'password', 'senderid' => '000000000', 'sender_name' => 'sendername', 'sender_address' => 'senderaddress', 'sender_city' => 'sendercity', 'sender_zipcode' => '2351', 'sender_country' => 'HU', 'sender_contact' => 'sendercontact', 'sender_phone' => 'senderphone', 'sender_email' => '
[email protected]', 'consig_name' => 'consigname', 'consig_address' => 'consigaddress', 'consig_city' => 'consigcity', 'consig_zipcode' => '2351', 'consig_country' => 'HU', 'consig_contact' => 'consigcontact', 'consig_phone' => 'consigphone', 'consig_email' => '
[email protected]', 'pcount' => 1, 'pickupdate' => '2014-01-29', 'content' => 'tartalom', 'clientref' => 'clientref', 'codamount' => '1526', 'codref' => 'codref', 'services' => array(), 'printertemplate' => 'A4_2x2', 'printit' => true, 'timestamp' => '20140129150000', '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); }
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); } ?>
Příloha F Použití pdfdata z výsledku v C# (Visual Studio 2008) Přidání reference k projektu:
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);
