Dokumentácia SOAP-like volaní API2

Dokumentácia SOAP-like volaní API2

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

Okrem HTTP autentifikácie podporujú SOAPové služby aj nasledovné druhy autentifikácie.

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.
zp:AccessToken Autentifikácia prístupovým tokenom. Token sa dá získať prostredníctvom služby api/2/oauth. Proces získania tohto tokenu je opísaný detailne na úvodnej stránke v sekcii OAuth 2.0 autentifikácia

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



Otázky:

info@zelenaposta.sk

Služby API2