API2

Úlohou API2 je sprístupniť služby Zelenej pošty klientom tak, aby k nim mohli pristupovať odkiaľkoľvek. Väčšina funkcionality portálu Zelenej pošty je implementovaná práve cez API2. Oproti predchádzajúcemu API1 prináša niekoľko výrazných vylepšení. Okrem rozšírenia počtu služieb patrí medzi tie najpodstatnejšie aj možnosť volať webovú službu ako cez SOAP tak aj REST-like spôsobom.

Dokumentácia REST prístupu k službám sa nachádza na adrese zelenaposta.docs.apiary.io. Na tomto webe je možné vidieť jednotlivé požiadavky a odpovede na ne v JSON formáte. Taktiež môžete jednotlivé služby priamo z tohto webu testovať na vývojovom prostredí Zelenej pošty.

Dokumentácia SOAP prístupu k službám sa nachádza priamo na stránkach Zelenej pošty.

Autentifikácia

Väčšina metód vyžaduje prihlásenie pod používateľským účtom. Autentifikáciu je možné realizovať na HTTP úrovni alebo na úrovni SOAP požiadavky v prípade SOAP-like volania služieb.

HTTP autentifikácia

Pri oboch možnostiach volania služieb je možné využiť HTTP autentifikáciu. V prípade volania služieb REST-like spôsobom je HTTP autentifikácia jedinou možnosťou autentifikácie. SOAP-ové API podporuje aj iné spôsoby autentifikácie. Pri použití HTTP autentifikácie sa používa HTTP hlavička Authorization.

Autentifikovať sa je možné dvoma metódami:

1. základnou autentifikáciou s autentifikačnou schémou Basic. Ak je napr. meno používateľa Aladdin a heslo je OpenSesame, tak sa pošle hlavička v tvare:

   Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l
   

   pričom reťazec QWxhZGRpbjpPcGVuU2VzYW1l vznikol base64-zakódovaním reťazca Aladdin:OpenSesame (t.j. base64encode("$username:$password")).

2. Autentifikácia tokenom s autentifikačnou schémou Token.

   Authorization: Token $token
   

OAuth 2.0 autentifikácia

Je možné využiť aj OAuth 2.0 autentifikáciu, kedy sa prihlasuje pomocou prístupového tokenu. Token je možné získať využitím služby api/2/oauth. Postup je nasledovný:

1. Použije sa adresa https://www.zelenaposta.sk/oauth/request-token?client_id=[clientId]&redirect_uri=[redirectUrl], kde [clientId] je klientský identifikátor aplikácie a [redirectUrl] je spätná adresa, na ktorú sa následne vracia. Príklad ak [clientId] = 123456 a [redirectUrl] = https://yourwebsite.com tak, výsledná adresa vyzerá takto: https://www.zelenaposta.sk/oauth/request-token?client_id=123456&redirect_uri=https%3A%2F%2Fwww.yourwebsite.com%2F.

Nezabudnite hodnotu [redirectUrl] zakódovať tak aby spĺňala podmienky URL formátu query stringu (v PHP metóda urlencode()), tj. špeciálne znaky nahradené percentuálnymi náhradami, atď.

2. Návštevou adresy bude používateľ vyzvaný na prihlásenie sa do systému Zelenej Pošty. Keď sa prihlási (alebo už prihlásený je) je mu zobrazená stránka, na ktorej môže povoliť aplikácii prístup k svojim dátam v systéme Zelenej pošty.

3. Po odsúhlasení je používateľ vrátený na zadanú [redirectUrl], pričom ako jeden z GET parametrov je vrátený požiadavkový token. Spätná URL teda vyzerá napr. takto: https://www.yourwebsite.com/?code=13b435432483b199961bc6cdc063e5d3c93a06a9.

4. S týmto tokenom je možné následne vytvoriť prístupový token využitím metódy getAccessToken v službe api/2/oauth.

5. Po vytvorení prístupového tokenu je možné sa prihlasovať sa v službách Zelenej pošty nasledovne:

   Authorization: Bearer $accessToken
   

Služby

Služby sú dostupné na URL adresách: