/api/2/address

/api/2/address

Táto služba umožňuje získať informácie o adresách - krajiny, psč a pod.

getCountries

Vráti zoznam krajín spolu s ISO kódom, názvom a regulérnym výrazom pre PSČ v danej krajine.

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
        <getCountriesRequest xmlns="http://schemas.zelenaposta.sk/address"/>
    </Body>
</Envelope>

Odpoveď obsahuje zoznam krajín. Položka code je ISO kód danej krajiny, name je názov krajiny celými slovami, zipRegex je regulérny výraz používaný na validáciu PSČ z danej krajiny, zipUsed je pravdivostná hodnota vyjadrujúca, či sa v danej krajine používa PSČ.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3="http://schemas.zelenaposta.sk/core" xmlns:ns4="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:ns5="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:ns6="http://schemas.zelenaposta.sk/address">
    <soap:Body>
        <ns6:getCountriesResponse>
            <ns6:countries>
                <ns6:country>
                    <ns6:code>af</ns6:code>
                    <ns6:name>Afghanistan</ns6:name>
                    <ns6:zipUsed>false</ns6:zipUsed>
                    <ns6:zipPositionAfter>false</ns6:zipPositionAfter>
                </ns6:country>
                <ns6:country>
                    <ns6:code>ax</ns6:code>
                    <ns6:name>Åland Islands</ns6:name>
                    <ns6:zipRegex>22\d3</ns6:zipRegex>
                    <ns6:zipUsed>true</ns6:zipUsed>
                    <ns6:zipPositionAfter>false</ns6:zipPositionAfter>
                </ns6:country>
                <ns6:country>
                    <ns6:code>dz</ns6:code>
                    <ns6:name>Algeria</ns6:name>
                    <ns6:zipRegex>\d5</ns6:zipRegex>
                    <ns6:zipUsed>true</ns6:zipUsed>
                    <ns6:zipPositionAfter>false</ns6:zipPositionAfter>
                </ns6:country>
            </ns6:countries>
        </ns6:getCountriesResponse>
    </soap:Body>
</soap:Envelope>
Názov Popis
code ISO kód krajiny.
name Celoslovný názov krajiny.
zipRegex Regulérny výraz používaný na validáciu PSČ danej krajiny.
zipUsed Pravdivostná hodnota vyjadrujúca, či sa v danej krajine používa PSČ.

recognizeAddresses

Metóda rozoznávajúca adresu z dodaného textového reťazca. Rozbije adresu do samostatných elementov meno, ulica, PSČ a ISO kód štátu. Vracia aj validáciu ak rozoznanie neprebehlo v poriadku. Požiadavka obsahuje zoznam addresses s položkami address, čo sú textové reťazce s adresou na rozoznanie.

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
        <recognizeAddressesRequest xmlns="http://schemas.zelenaposta.sk/address">
            <addresses>
                <address>Vážený pán
                Juraj Tester
                Hlavná ulica č. 879/A
                927 01 Šaľa
                </address>
                <address>Duslo, a.s.
                Administratívna budova, ev. č. 1236
                927 03 Šaľa
                Slovenská republika
                </address>
            </addresses>
        </recognizeAddressesRequest>
    </Body>
</Envelope>

Odpoveďou tejto metódy je zoznam rozoznaných adries aj s prípadnou validačnou chybou.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3="http://schemas.zelenaposta.sk/core" xmlns:ns4="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:ns5="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:ns6="http://schemas.zelenaposta.sk/address">
    <soap:Body>
        <ns6:recognizeAddressesResponse>
            <ns6:addresses>
                <ns6:address>
                    <ns6:name>Vážený pán
Juraj Tester</ns6:name>
                    <ns6:street>Hlavná ulica č. 879/A</ns6:street>
                    <ns6:city>Šaľa</ns6:city>
                    <ns6:zip>927 01</ns6:zip>
                    <ns6:country>SLOVENSKO</ns6:country>
                    <ns6:countryCode>sk</ns6:countryCode>
                    <ns6:validations/>
                </ns6:address>
                <ns6:address>
                    <ns6:name>Duslo, a.s.</ns6:name>
                    <ns6:street>Administratívna budova, ev. č. 1236</ns6:street>
                    <ns6:city>Šaľa</ns6:city>
                    <ns6:zip>927 03</ns6:zip>
                    <ns6:country>SLOVENSKO</ns6:country>
                    <ns6:countryCode>sk</ns6:countryCode>
                    <ns6:validations>
                        <ns6:validation>
                            <ns3:name>address</ns3:name>
                            <ns3:code>addressWithInvalidZip</ns3:code>
                            <ns3:message>Adresa má nesprávne PSČ (kandidáti: 927 01, 927 05).</ns3:message>
                        </ns6:validation>
                    </ns6:validations>
                </ns6:address>
            </ns6:addresses>
        </ns6:recognizeAddressesResponse>
    </soap:Body>
</soap:Envelope>
Názov Popis
name Meno adresáta.
street Ulica aj s číslom domu.
city Mesto.
zip PSČ.
country Celoslovný názov adresátovej krajiny.
countryCode ISO kód adresátovej krajiny.
validations Zoznam validačných chýb (ak nejaké nastali).

Samotná validácia obsahuje nasledovné údaje:

Názov Popis
name Názov prvku, v ktorom nastala chyba.
code Krátky jednoslovný kód chyby, čo nastala.
message Detailná hláška popisujúca chybu.

suggestAddress

Metóda ponúka adresy k zadaným údajom. Napr. zadaním iba ulice nám ponúkne mestá, v ktorých takáto ulica je. Jedná sa len o informačnú metódu a nie je garantovaná úplnosť výstupu. Požiadavka obsahuje textové reťazce s ulicou, PSČ a mestom, nemusia byť úplne (teda stačí len začiatok názvu ulice a pod.). Povinný je aspoň jeden z nich.

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
        <suggestAddressRequest xmlns="http://schemas.zelenaposta.sk/address">
            <street>Hlav</street>
            <city>Šaľa</city>
            <zip>92701</zip>
        </suggestAddressRequest>
    </Body>
</Envelope>
Názov Popis
street Ulica bez čísla doma.
city Mesto.
zip PSČ.

Odpoveďou tejto metódy je zoznam potencionálnych adries.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3="http://schemas.zelenaposta.sk/core" xmlns:ns4="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:ns5="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:ns6="http://schemas.zelenaposta.sk/address">
    <soap:Body>
        <ns6:suggestAddressResponse>
            <ns6:addresses>
                <ns6:address>
                    <ns6:street>Hlavná</ns6:street>
                    <ns6:city>Šaľa</ns6:city>
                    <ns6:zip>92701</ns6:zip>
                </ns6:address>
            </ns6:addresses>
        </ns6:suggestAddressResponse>
    </soap:Body>
</soap:Envelope>
Názov Popis
street Ulica bez čísla doma.
city Mesto.
zip PSČ.

validateAddresses

Metóda zvaliduje adresu (najmä prítomnosť všetkých hodnôt).

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
        <validateAddressesRequest xmlns="http://schemas.zelenaposta.sk/address">
            <addresses>
                <address>
                    <name>Juraj Tester</name>
                    <street>Hlavná</street>
                    <city>Šaľa</city>
                    <zip>927 01</zip>
                    <country>Česko</country>
                    <countryCode>cz</countryCode>
                </address>
            </addresses>
        </validateAddressesRequest>
    </Body>
</Envelope>
Názov Popis
name Adresátove meno.
street Ulica bez čísla doma.
city Mesto.
zip PSČ.
country Celý názov krajiny.
countryCode ISO kód krajiny.

Odpoveďou tejto metódy je zoznam adries s validačnými hláškami(ak nastali chyby).

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3="http://schemas.zelenaposta.sk/core" xmlns:ns4="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:ns5="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:ns6="http://schemas.zelenaposta.sk/address">
    <soap:Body>
        <ns6:validateAddressesResponse>
            <ns6:addresses>
                <ns6:address>
                    <ns6:name>Juraj Tester</ns6:name>
                    <ns6:street>Hlavná</ns6:street>
                    <ns6:city>Šaľa</ns6:city>
                    <ns6:zip>927 01</ns6:zip>
                    <ns6:country>CZECH REPUBLIC</ns6:country>
                    <ns6:countryCode>cz</ns6:countryCode>
                    <ns6:validations>
                        <ns6:validation>
                            <ns3:name>address</ns3:name>
                            <ns3:code>error:addressWithInvalidZip</ns3:code>
                            <ns3:message>Adresa má nesprávne PSČ.</ns3:message>
                        </ns6:validation>
                    </ns6:validations>
                </ns6:address>
            </ns6:addresses>
        </ns6:validateAddressesResponse>
    </soap:Body>
</soap:Envelope>

Validácia obsahuje:

Názov Popis
name Názov prvku, v ktorom nastala chyba.
code Krátky jednoslovný kód chyby, čo nastala.
message Detailná hláška popisujúca chybu.

validateZip

Metóda na validáciu PSČ. Ako vstup zadáme PSČ a ISO kód krajiny, následne metóda dodá informáciu o správnosti daného PSČ podľa regulérneho výrazu pre danú krajinu.

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
        <validateZipRequest xmlns="http://schemas.zelenaposta.sk/address">
            <zip>92A01</zip>
            <country>sk</country>
        </validateZipRequest>
    </Body>
</Envelope>
Názov Popis
zip PSČ.
country ISO kód krajiny.

Odpoveďou tejto metódy je pravdivostná hodnota ohľadom validnosti PSČ a dôvod na prípadnú nevalidnosť.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3="http://schemas.zelenaposta.sk/core" xmlns:ns4="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:ns5="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:ns6="http://schemas.zelenaposta.sk/address">
    <soap:Body>
        <ns6:validateZipResponse>
            <ns6:zipIsValid>false</ns6:zipIsValid>
            <ns6:reason>ZIP code is not in selected country format</ns6:reason>
        </ns6:validateZipResponse>
    </soap:Body>
</soap:Envelope>

Validácia obsahuje:

Názov Popis
zipIsValid Pravdivostná hodnota vyjadrujúca, či zadané PSČ je validné.
reason Hláška popisujúca nevalidnosť PSČ.


Dotazy:

info@zelenaposta.cz

Služby API2