Zelená pošta pro Android

Zelená pošta pro Android

Instalovat
Zelená pošta pro Android

Zelená pošta pro iPhone/iPad

Instalovat

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.

Testovať SOAP-ové API je možné pomocou multiplatformnej desktopovej aplikácie SoapUI alebo pomocou rozšírenia do prehliadača Wizdler, ktoré je dostupné pre prehliadače Chrome a Firefox).

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.

HTTP autentifikácia

V prípade volania služieb REST-like spôsobom je HTTP autentifikácia jedinou možnosťou 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
    

SOAP autentifikácia

V SOAP správach sú použité nasledovné menné priestory:

Alias Menný priestor
wsse http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd
wsu http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd

Autentifikácia je riešená formou SOAP hlavičky wsse:Security.

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Header>
        <Security xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
            …
        </Security>
    </Header>
    <Body>
        …
    </Body>
</Envelope>

Obsahom wsse:Security hlavičky je element wsse:UsernameToken, ktorého obsah závisí od konkrétneho typu použitého prihlásenia.

<UsernameToken>
    …
</UsernameToken>

V elemente wsse:UsernameToken sú povolené nasledovné elementy:

Názov Povinný Popis
wsse:Username Áno Meno používateľa.
wsse:Password Nie Heslo. V atribúte Type je typ prihlásenia.
wsse:Nonce Nie Nonce token.
wsse:Created Nie Čas vytvorenia požiadavky.

Podporované typy prihlásenia sú nasledovné:

Názov Popis
wsse:PasswordText Autentifikácia menom a heslom. Je možné tiež použiť štandardný názov http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText.
wsse:PasswordDigest Digest autentifikácia. Je možné tiež použiť štandardný názov http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest.
zp:AuthToken Autentifikácia tokenom.

Autentifikácia menom a heslom

Najjednoduchším spôsobom prihlásenia je pomocou mena a hesla. Prihlásenie pre používateľa user@example.com s heslom password bude vyzerať nasledovne:

<UsernameToken>
    <Username>user@example.com</Username>
    <Password Type="wsse:PasswordText">password</Password>
</UsernameToken>

Digest autentifikácia

Ďalším spôsobom prihlásenia je digest autentifikácia. Prihlásenie pre používateľa user@example.com s heslom password bude vyzerať nasledovne:

<UsernameToken xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <Username>user@example.com</Username>
    <Password Type="wsse:PasswordDigest">lBIOj3NfZdc8YMfE4oeT8u9DosY=</Password>
    <Nonce>sUjGpE2cxXrayVh/D2FE6g==</Nonce>
    <wsu:Created>2014-08-08T11:15:50.587Z</wsu:Created>
</UsernameToken>

Hodnotu elementu wsse:Nonce generuje klient. Pri každej požiadavke musí byť unikátna. Odporúčaná dĺžka hodnoty je 32 bajtov, ktoré sú následne base64-zakódované.

V elemente wsu:Created je čas vytvorenia požiadavky. Tento čas musí byť uvedený v UTC formáte, aby sa digest hodnota vypočítaná na serveri zhodovala s tou od klienta. Nemal by byť starší ako 5 minút.

Pozn.: Server aktuálne nekontroluje unikátnosť nonce hodnoty ani vek požiadavky.

Pri tomto type prihlásenia je rozdielom oproti štandardu to, že pri výpočte digest hodnoty je potrebné namiesto hesla použiť heslo transformované pomocou hešovacej funkcie SHA-1 zakódované v hexadecimálnom tvare.

digest = sha1(nonce + created + sha1(password))

Výpočet digest hodnoty v PHP vyzerá nasledovne:

$password = 'password';
$nonce = 'sUjGpE2cxXrayVh/D2FE6g==';
$created = '2014-08-08T11:15:50.587Z';

$digest = base64_encode(sha1(base64_decode($nonce) . $created . sha1($password), true));

Autentifikácia tokenom

Autentifikačný token je možné získať z prihlasovacej služby. Následne je možné pomocou neho autentifikovať ďalšie požiadavky.

<UsernameToken>
    <Username>user@example.com</Username>
    <Password Type="zp:AuthToken">24HEjXM9UqgbPLUmPlHK4AKZqDY=</Password>
</UsernameToken>

Zadanie prihlasovacieho mena je v tomto prípade voliteľné. Prihlásenie však nebude úspešné v prípade, že je zadané a nezhoduje sa s menom používateľa, ktorému token patrí.

Služby

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

Krajina URL
SK https://gateway.zelenaposta.sk/api/2/[service]
CZ https://gateway.zelenaposta.cz/api/2/[service]

Zoznam služieb