/api/2/sent

/api/2/sent

Táto služba umožňuje odosielať zásielky a získať informácie o odoslaných zásielkach.

sendMailings

Pre odosielanie zásielok je možné použiť metódu sendMailings webovej služby pre odosielanie zásielok. Väčšina parametrov pre odoslanie zásielky je voliteľná.

Odoslanie zásielky

V najjednoduchšom prípade stačí uviesť iba príjemcu a dokument, ktorý treba odoslať. Pri takomto odoslaní sa automaticky zvolí najlacnejší produkt, ktorý je možné použiť.

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
        <sendMailingsRequest xmlns="http://schemas.zelenaposta.sk/sent">
            <title>Testovacia dávka</title>
            <mailings>
                <mailing>
                    <documents>
                        <document>
                            <file>[base64Binary?]</file>
                        </document>
                    </documents>
                    <recipient>
                        <name>
                            Jane Doe
                            Zelená pošta
                        </name>
                        <street>Údernícka 15</street>
                        <city>Bratislava</city>
                        <zip>851 01</zip>
                        <country>sk</country>
                    </recipient>
                </mailing>
            </mailings>
            <onBehalfOf>[string?]</onBehalfOf>
            <testRun>[boolean?]</testRun>
            <checkUniqueCustomId>[boolean?]</checkUniqueCustomId>
        </sendMailingsRequest>
    </Body>
</Envelope>

Ako sa dá v príklade vidieť, požiadavka pre odoslanie zásielky sendMailingsRequest obsahuje zoznam zásielok mailings, pričom každá zásielka je vo svojom elemente mailing. Samotná zásielka pozostáva z jedného alebo viacerých dokumentov v elemente documents/document. Dokument obsahuje súbor file v PDF formáte, ktorý je zakódovaný pomocou base64.

Ak sa parameter testRun zadá ako true zásielka nebude reálne odoslaná a vykoná sa len testovacie volanie, ktoré v odpovedi vráti všetko okrem slotId. POZOR: Ak tento parameter nie je zadaný zásielka sa normálne odošle.

Ak sa parameter checkUniqueCustomId zadá ako true, zadané customId sa kontrolujú z pohľadu unikátnosti s už existujúcimi zásielkami. Ak zadaný vlastný identifikátor zásielky už existuje pri nejakej, daným používateľom, odoslanej zásielke tak sa vyhodí chyba. Pokiaľ zadáme hodnotu false alebo parameter nevyplníme, tak zadané ID nemusia byť unikátne.

(Poznámka: Častou chybou pri volaní API býva, že je súbor s dokumentom dvakrát base64-zakódovaný. To sa stáva najmä kvôli tomu, že pri použití knižnice pre volanie SOAP webových služieb sa takáto knižnica o zakódovanie postará sama automaticky. Vtedy stačí nastaviť do base64-kódovaného poľa priamo požadované bajty.)

V elemente recipient je uvedená korešpondenčná adresa príjemcu. Meno príjemcu v adrese v elemente name môže byť uvedené na viacerých riadkoch, maximálne však na troch. Krajinu v elemente country je možné uviesť buď 2-písmenovým ISO kódom krajiny (ISO 3166-1 alpha-2) alebo slovne, pričom služba rozpoznáva názov krajiny v slovenčine, angličtine a aj rôzne aliasy krajín.

Názov dávky v elemente title je voliteľný a vygeneruje sa automaticky v prípade, že nie je zadaný. Tento názov je viditeľný v odoslaných dávkach na portáli Zelenej pošty, preto by mal byť dostatočne výstižný.

V elemente onBehalfOf sa môže nachádzať manažérové číslo účtu, v mene ktorého chceme zásielku odoslať. V prípade ak máme takého manažéra a vzťahy sú korektne nastavené zásielka bude odoslaná v jeho mene, ako keby to spravil on. V nastaveniach na portáli v účte manažéra pod kolonkou Zdieľanie musí byť povolené právo na odosielanie pre používateľa, ktorý chce zásielku odoslať.

V prípade úspechu je v odpovedi slotId - identifikátoru slotu, pod ktorým bola daná dávka nahraná na server. Tento identifikátor je neskôr možné použiť na dopytovanie stavu zásielok v dávke.

V odpovedi sa taktiež nachádza cena celej dávky uvedená v totalPrice a jednotlivé samostatné zásielky. Pre každú odoslanú zásielku je tu uvedený názov použitého produktu v productName, počet strán zásielky - pageCount a cena za zásielku samostatne - priceWithVat.

V odpovedi je uvedené aj customId (ak bolo zadané v požiadavke) a aj zoznam customIds, ktorý obsahuje jednak samostatne zadané customId, ale aj ostatné identifikátory zadané v poli. V prípade ak bola v požiadavke zvolená možnosť zoskupenia zásielok pre jedného príjemcu a tieto samostatné zásielky mali uvedené vlastné customId, tak aj tieto identifikátory sa nachádzajú v zozname v odpovedi k výslednej spojenej zásielke.

<soap:Envelope
        xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:ns6="http://schemas.zelenaposta.sk/sent">
    <soap:Body>
        <ns6:sendMailingsResponse>
            <ns6:slotId>1613794916524892405112887901823714100840</ns6:slotId>
            <ns6:totalPrice>1.022000</ns6:totalPrice>
            <ns6:mailings>
                <ns6:mailing>
                    <ns6:productName>Z2TRA4SCBDOOC42_EDM</ns6:productName>
                    <ns6:pageCount>1</ns6:pageCount>
                    <ns6:priceWithVat>1.022000</ns6:priceWithVat>
                    <ns6:customId>vlastny identifikator 1</ns6:customId>
                    <ns6:customIds>
                        <ns6:customId>vlastny identifikator 2</ns6:customId>
                        <ns6:customId>vlastny identifikator 3</ns6:customId>
                        <ns6:customId>vlastny identifikator 1</ns6:customId>
                    </ns6:customIds>
                </ns6:mailing>
            </ns6:mailings>
        </ns6:sendMailingsResponse>
    </soap:Body>
</soap:Envelope>

Dokumenty v zásielke

Dokumentov v zásielke môže byť viacero. Typickým príkladom je odosielanie viacerých faktúr s rovnakou prílohou. Okrem PDF súboru v elemente file je pre daný dokument v zásielke možné určiť aj ďalšie parametre.

<document>
    <file>[base64Binary?]</file>
</document>

(Poznámka: V súčasnosti je možné odoslať iba PDF súbor. Do budúcna je plánovaná možnosť odosielania aj ľubovoľných binárnych súborov, ale len pri elektronických zásielkach.)

V prípade odosielania väčšieho množstva zásielok je vhodné odoslať jeden PDF dokument, ktorého časti tvoria jednotlivé dokumenty. Predíde sa tým rozdeľovaniu PDF, pričom vzniknú dokumenty, ktorých súhrnná veľkosť bude oveľa väčšia (kvôli duplikácii obrázkov, fontov a pod.). V takomto prípade je ale potrebné použiť MTOM (viď nižšie), inak takáto optimalizácia nie je možná.

(Poznámka: MTOM umožňuje odosielanie súborov vo forme príloh, pričom v tele požiadavky je možné odkazovať z viacerých miest na rovnakú prílohu. Do budúcna možno pribudne podpora multipart/form-data - potom už nebude MTOM jedinou možnosťou ako odosielať prílohy efektívne.)

Elementy startPage a pageCount definujú časť PDF dokumentu, ktorá tvorí dokument v danej zásielke. Začiatočné číslo strany v elemente startPage je číslované od 1. V elemente pageCount je počet strán dokumentu.

<document>
    <startPage>[int?]</startPage>
    <pageCount>[int?]</pageCount>
    …
</document>

V elemente paper je možné definovať typ papiera.

<document>
    <paper>[string?]</paper>
    …
</document>

(Poznámka: Podpora rôznych typov papiera závisí od tlačového poskytovateľa. Pred použitím treba konzultovať so Zelenou poštou.)

Platobné metadáta

V prípade, že produkt definuje prikladanie šekov k dokumentu, platobné metadáta sa definujú v elemente payment. Údaje na šeku musia spĺňať poštové podmienky pre poštový poukaz na účet.

Názov Popis
count Počet šekov.
amount Suma na šeku v eurách. Maximálna suma je 15 000 €.
variableSymbol Variabilný symbol. Maximálne 10 číslic.
specificSymbol Špecifický symbol. Maximálne 10 číslic.
constantSymbol Konštantný symbol. Maximálne 4 číslice.
bankAccount Číslo bankového účtu v IBAN formáte.
productCode Kód produktu poštovej poukážky. Povolené hodnoty sú 36, 37, 38, 39.
processingCode Kód spracovania poštovej poukážky. Povolené hodnoty sú 0, 1, 2, 3.
serviceCode Kód služby poštovej poukážky. Povolené hodnoty sú 0, 1, 2, 3, 4, 80, 81, 82, 83, 84, 90.
referenceNumber Referenčné číslo je povinný údaj pri kóde produktu 37. Maximálne 9 číslic.
messageForRecipient Správa pre príjemcu. Maximálne 24 znakov.
<document>
    <payment>
        <count>[int?]</count>
        <amount>[decimal?]</amount>
        <variableSymbol>[string?]</variableSymbol>
        <specificSymbol>[string?]</specificSymbol>
        <constantSymbol>[string?]</constantSymbol>
        <bankAccount>[string?]</bankAccount>
        <productCode>[int?]</productCode>
        <processingCode>[int?]</processingCode>
        <serviceCode>[int?]</serviceCode>
        <referenceNumber>[string?]</referenceNumber>
        <messageForRecipient>[string?]</messageForRecipient>
    </payment>
    …
</document>

Ďalšie metadáta dokumentu je možné definovať v elemente fieldValues.

<document>
    <fieldValues>
        <fieldValue>
            <name>[string?]</name>
            <value>[string?]</value>
            <page>[int?]</page>
        </fieldValue>
    </fieldValues>
    …
</document>

Voľba produktu

Produkt definuje to, či bude odoslaná zásielka čiernobiela/farebná, jednostranná/obojstranná, obyčajná/doporučená, SR/ČR/EÚ alebo svet, aká obálka sa použije a prípadne ďalšie vlastnosti zásielky. Pri odosielaní je možné explicitne v elemente product zvoliť, aký produkt sa má použiť:

<mailing>
    <product>Z2TRA4SCBDOOC4</product>
    <documents>…</documents>
    <recipient>…</recipient>
</mailing>

Zoznam produktov, ktoré je možné použiť, sa dá získať volaním metódy getProducts služby /api/2/product. Všetky parametre tejto metódy sú voliteľné, takže pre získanie všetkých dostupných produktov stačí túto metódu zavolať bez parametrov.

Ak sa v čase odosielania nedá presne určiť, ktorý produkt sa má použiť, je možné nastaviť filtračné kritériá. V takomto prípade sa automaticky zvolí najlacnejší možný produkt, ktorý vyhovuje filtračným kritériám. Produkty je možné filtrovať pomocou nasledujúcich elementov:

Názov Popis
duplex Filtruje produkty podľa toho, či používajú obojstrannú alebo jednostrannú tlač. Pre obojstrannú tlač treba použiť hodnotu true, pre jednostrannú hodnotu false. V prípade, že je hodnota nenastavená, znamená to, že sa môže použiť produkt aj s jednostrannou a aj s obojstrannou tlačou.
backpage Filtruje produkty podľa toho, či sa dopĺňa strana s adresou alebo nie. Pre produkty, v ktorých sa dopĺňa strana s adresou, treba použiť hodnotu true. Pre produkty bez strany s adresou hodnotu false. Bez zadania hodnoty sa pri voľbe produktu na dopĺňanie strany s adresou neprihliada.
correspondence Filtruje produkty podľa požadovanej poštovej služby. Možné hodnoty sú napr. 2ndClass pre obyčajnú zásielku, registered pre doporučenú a registeredWithAdvice pre doporučenú s doručenkou. Bez zadania hodnoty sa pri voľbe produktu na typ poštovej služby neprihliada. Všetky dostupé možnosti je možné získať volaním metódy getEnums v api/2/product.
paper Filtruje produkty podľa typu papiera. Bez zadania hodnoty sa pri voľbe produktu na papier neprihliada.
envelope Filtruje produkty podľa typu obálky. Možné hodnoty sú napr. c6c5 pre C6/C5 obálku, c4 pre obálku C4 alebo c5 pre obálku C5. Bez zadania hodnoty sa pri voľbe produktu na obálku neprihliada.
printing Filtruje produkty podľa typu tlače. Možné hodnoty sú blackWhite pre čiernobielu tlač a color pre farebnú tlač. Bez zadania hodnoty sa pri voľbe produktu na typ tlače neprihliada.
allowedProducts Filtruje produkty podľa ich kódov. Kódy sú uvedené v elemente allowedProducts/product. Tento filter je vhodné použiť, keď napr. nie je v čase odosielania možné určiť, či sa má použiť obálka C6/C5 alebo C4. Po zadaní povolených kódov produktov s obálkami C6/C5 a C4 zároveň sa automaticky zvolí najlacneší možný produkt (podľa počtu strán dokumentov).

Zásielky, ktoré sa majú odoslať obojstranne, farebne a doporučene, je možné definovať nasledovne:

<mailing>
    <duplex>true</duplex>
    <printing>color</printing>
    <correspondence>registered</correspondence>
    <documents>…</documents>
    <recipient>…</recipient>
</mailing>

(Poznámka: V súčasnosti je možné filtrovať len na úrovni zásielky. Keďže pri odosielaní dávky je väčšinou žiaduce použiť na produkty rovnaký filter, bude v budúcnosti možné uviesť tieto elementy aj na úrovni dávky. Pri uvedení filtračných elementov aj v dávke aj v zásielke sa produkty odfiltrujú postupne podľa oboch kritérií.)

Vlastný identifikátor zásielky

Pre neskoršie jednoduchšie vyhľadanie zásielky je možné priradiť zásielke vlastný identifikátor v elemente customId. Typicky ním môže byť napr. číslo faktúry alebo zmluvy. Ak chceme pre jednu zásielku viacero vlastných identifikátorov, je možné ich zadať v poli customIds. Všetky tieto identifikátory je následne možné použiť pre vyhľadávanie zásielky.

<mailing>
    <customId>…</customId>
    <customIds>
        <customId>…</customId>
        <customId>…</customId>
        …
    </customIds>
    …
</mailing>

Adresa odosielateľa

Predvolene sa ako adresa odosielateľa použije korešpondenčná adresa z profilu používateľa. Inú adresu odosielateľa je možné nastaviť pomocou elementu sender.

<mailing>
    …
    <sender>
        <name>Zelená pošta s.r.o.</name>
        <street>Údernícka 15</street>
        <city>Bratislava</city>
        <zip>85101</zip>customIds
        <country>sk</country>
    </sender>
</mailing>

Fakturačná adresa príjemcu

V prípade, že odosielateľ pozná fakturačnú adresu príjemcu, môže ju uviesť v elemente address.

<mailing>
    …
    <address>
        <name>Zelená pošta s.r.o.</name>
        <street>Údernícka 15</street>
        <city>Bratislava</city>
        <zip>85101</zip>
        <country>sk</country>
    </address>
</mailing>

Táto adresa bude predvyplnená do formulára pri registrácii príjemcu na portáli Zelenej pošty.

Konverzia príjemcu na elektronický príjem zásielok

Aby sa príjemca mohol registrovať na portáli Zelenej pošty pre elektronický odber zásielok, musí byť jednoznačne identifikovateľný v systéme odosielateľa pomocou UIZ - unikátneho identifikátora zákazníka. Tento identifikátor pozostáva z 2 častí: UIZ1 a UIZ2:

  • UIZ1 je primárny identifikátor zákazníka. V systéme odosielateľa je ním typicky IČO prípadne iný identifikátor klienta.

  • UIZ2 je doplnkový identifikátor zákazníka. Tento identifikátor je voliteľný. Typicky je to číslo konkrétnej zmluvy, číslo odberného miesta alebo iný identifikátor, ktorý logickým spôsobom rozdeľuje komunikáciu so zákazníkom. Vďaka druhému identifikátoru si môže zákazník definovať iné pravidlá pre príjem zásielok podľa takýchto logických skupín.

V takomto prípade je možné na fyzicky odoslaný dokument doplniť pečiatku UID (unikátny identifikátor dokumentu) s PIN-om, ktorá je spárovaná s identifikačnými údajmi zákazníka. Po zadaní UID/PIN sa tak môže príjemca zaregistrovať na portáli Zelenej pošty, prípadne si pridať registráciu do svojho existujúceho účtu. Hodnoty UID/PIN generuje Zelená pošta pri volaní metódy prepare služby /api/mailing.

(Poznámka: Metóda prepare zatiaľ nebola v API2 implementovaná. Je potrebné použiť API1 - viď kapitola Získanie hodnôt UID/PIN.)

<mailing>
    <uiz1>46529233</uiz1>
    <uid>Lbs1oJpaTm53</uid>
    <pin>1234</pin>
    …
</mailing>

Doplnkový identifikátor zákazníka môže logicky rozdeľovať komunikáciu s príjemcom do viacerých kanálov:

<mailing>
    <uiz1>46529233</uiz1>
    <uiz2>faktury</uiz2>
    …
</mailing>

Odosielanie elektronickej zásielky

Pri odoslaní elektronickej zásielky nie je potrebné zadávať adresu príjemcu ani odosielateľa. Stačí správne nastaviť identifikátor príjemcu a ako produkt zadať hodnotu EMAIL.

<mailing>
    <uiz1>46529233</uiz1>
    <product>EMAIL</product>
    <documents>
        <document>
            <file>…</file>
        </document>
    </documents>
</mailing>

Doporučené zásielky

Pre odoslanie doporučenej zásielky je potrebné použiť produkt s takýmto poštovým produktom. Podporované typy poštového doručenia sú doporučené zásielky, doporučené zásielky s doručenkou, doporučené zásielky s doručenkou do vlastných rúk a úradné zásielky.

Podacie číslo sa doporučeným zásielkam priraďuje v čase odoslania dávky do tlače. Preto ho je možné cez API zistiť až po odoslaní na tlač.

V prípade doporučených zásielok s doručenkou je na doručenku možné dotlačiť vlastný text. Ten sa definuje v elemente deliveryConfirmationText.

<mailing>
    <deliveryConfirmationText>…</deliveryConfirmationText>
    …
</mailing>

Dobierka

Dobierku je možné definovať v elemente cashOnDelivery:

  • amount - Suma dobierky v maximálnej výške 500 €.
  • bankAccount - Číslo bankového účtu v IBAN formáte.
  • variableSymbol - Variabilný symbol.
<mailing>
    <cashOnDelivery>
        <amount>…</amount>
        <bankAccount>…</bankAccount>
        <variableSymbol>…</variableSymbol>
    </cashOnDelivery>
    …
</mailing>

Odosielanie s použitím MTOM

Pri odosielaní veľkého množstva PDF odporúčame použiť rozšírenie MTOM (Message Transmission Optimization Mechanism) s XOP (XML-binary Optimized Packaging).

Vďaka použitiu MTOM je objem prenášaných dát menší, pretože nie je potrebné binárne dáta PDF dokumentu kódovať base64 kódovaním. Tiež je možné odkazovať z rôznych zásielok na jeden súbor, takže rovnakú prílohu stačí poslať cez sieť raz.

POST https://gateway.zelenaposta.sk/api/mailing/ HTTP/1.1
Accept-Encoding: gzip,deflate
SOAPAction: ""
Content-Type: multipart/related; type="application/xop+xml"; start="<rootpart@soapui.org>"; start-info="text/xml"; boundary="----=_Part_100_19064690.1407507003461"
MIME-Version: 1.0
Connection: Keep-Alive
Content-Length: 569492
Host: gateway.zelenaposta.sk


------=_Part_100_19064690.1407507003461
Content-Type: application/xop+xml; charset=UTF-8; type="text/xml"
Content-Transfer-Encoding: 8bit
Content-ID: <rootpart@soapui.org>

<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">
            <UsernameToken>
                <Username>demo@zelenaposta.sk</Username>
                <Password Type="wsse:PasswordText">demo123</Password>
            </UsernameToken>
        </Security>
    </Header>
    <Body>
        <sendRequest xmlns="http://schemas.zelenaposta.sk/api/mailing">
            <title>Faktúry 2014/08</title>
            <mailings>
                <mailing>
                    <product>Z2TRA4SCBDOOC4</product>
                    <documents>
                        <document>
                            <file><Include href="cid:faktura.pdf" xmlns="http://www.w3.org/2004/08/xop/include"/></file>
                        </document>
                    </documents>
                    <recipient>
                        <name>Jozef Mak</name>
                        <street>Makova 12</street>
                        <city>Makovo</city>
                        <zip>81000</zip>
                        <country>sk</country>
                    </recipient>
                </mailing>
            </mailings>
        </sendRequest>
    </Body>
</Envelope>
------=_Part_100_19064690.1407507003461
Content-Type: application/pdf; name=faktura.pdf
Content-Transfer-Encoding: binary
Content-ID: <faktura.pdf>
Content-Disposition: attachment; name="faktura.pdf"; filename="faktura.pdf"

%PDF-…
…

------=_Part_100_19064690.1407507003461--

getBundles

Získa zoznam odoslaných dávok podľa rôznych filtračných kritérií.

Názov Popis
slots/id Odfiltruje dávky podľa identifikátorov slotov. Identifikátor slotu je v odpovedi pri odoslaní dávky metódou sendMailings.
bundles/id Odfiltruje dávky podľa identifikátorov dávok.
title Odfiltruje dávky, ktorých názov obsahuje zadaný reťazec, pričom na veľkosti písmen nezáleží.
username Odfiltruje dávky, ktorých meno používateľa obsahuje zadaný reťazec, pričom na veľkosti písmen nezáleží. Meno používateľa je vyplnené Zelenou tlačiarňou podľa používateľského mena v operačnom systéme pri odoslaní dávky.
computerName Odfiltruje dávky, ktorých názov počítača obsahuje zadaný reťazec, pričom na veľkosti písmen nezáleží. Názov počítača je vyplnené Zelenou tlačiarňou podľa názvu počítača v operačnom systéme pri odoslaní dávky.
orderBy Usporiada dávky podľa zvoleného stĺpca. Možné hodnoty sú title, createdOn, username, computerName, price, priceWithVat. Predvolene sú dávky usporadané vzostupne. Pre zostupné zoradenie je potrebné pred názov stĺpca zadať mínus (znak -).
limit Obmedzuje počet výsledkov vo vrátenom zozname dávok. Predvolená hodnota je 100.
offset Určuje index začiatočnej položky vo výslednom zozname dávok. Čísluje sa od nuly.
createdSince Odfiltruje dávky, ktoré boli vytvorené od zadaného dátumu.
createdUntil Odfiltruje dávky, ktoré boli vytvorené do zadaného dátumu.
withStats Indikuje, či zahrnúť do výsledku aj súhrnné počty zásielok čakajúcich na spracovanie, spracovaných a zrušených. Predvolene true.
friends/friend Zadávajú sa jednotlivé čísla účtov priateľov (accountNumber). Ak sú zadané metóda vráti dávky týchto priateľov.
includeFriends Ak je hodnota true vráti sa aj zoznam priateľov.
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
        <getBundlesRequest xmlns="http://schemas.zelenaposta.sk/sent">
            <slots>
                <id>[string?]</id>
            </slots>
            <bundles>
                <id>[int?]</id>
            </bundles>
            <title>[string?]</title>
            <username>[string?]</username>
            <computerName>[string?]</computerName>
            <orderBy>[string?]</orderBy>
            <limit>[int]</limit>
            <offset>[int]</offset>
            <createdSince>[dateTime?]</createdSince>
            <createdUntil>[dateTime?]</createdUntil>
            <friends>
                <friend>[string?]</friend>
            </friends>
            <withStats>[boolean]</withStats>
            <includeFriends>[boolean]</includeFriends>
        </getBundlesRequest>
    </Body>
</Envelope>

Odpoveďou je zoznam dávok:

Názov Popis
totalCount Celkový počet dávok vo výslednom zozname.
bundles/bundle Odoslaná dávka.

Každá odoslaná dávka má nasledovné vlastnosti:

Názov Popis
id Identifikátor dávky.
name Automaticky vygenerované technické meno dávky.
title Názov dávky, ako bol zadaný pri jej odosielaní.
createdOn Čas vytvorenia dávky.
slotId Identifikátor slotu dávky, pod ktorým bola nahraná.
customId Vlastný identifikátor dávky. Musí byť unikátny.
price Cena dávky bez DPH.
priceWithVat Cena dávky s DPH.
pending Počet zásielok v dávke čakajúcich na spracovanie.
processed Počet spracovaných zásielok v dávke.
canceled Počet zrušených zásielok v dávke.
<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/sent">
    <soap:Body>
        <ns6:getBundlesResponse>
            <ns6:totalCount>1</ns6:totalCount>
            <ns6:bundles>
                <ns6:bundle>
                    <ns6:id>1</ns6:id>
                    <ns6:name>Bundle_123456789_20170101120000</ns6:name>
                    <ns6:title>Testovacia dávka</ns6:title>
                    <ns6:createdOn>2017-01-01T12:00:00.000+01:00</ns6:createdOn>
                    <ns6:slotId>1234567890123456789012345678901234567890</ns6:slotId>
                    <ns6:price>0.5262</ns6:price>
                    <ns6:priceWithVat>0.631440</ns6:priceWithVat>
                    <ns6:pending>0</ns6:pending>
                    <ns6:processed>1</ns6:processed>
                    <ns6:canceled>0</ns6:canceled>
                </ns6:bundle>
            </ns6:bundles>
        </ns6:getBundlesResponse>
    </soap:Body>
</soap:Envelope>

getMailings

Získa zoznam zásielok podľa rôznych filtračných kritérií.

Názov Popis
mailings/id Odfiltruje zásielky podľa ich identifikátorov.
bundles/id Odfiltruje zásielky podľa identifikátorov dávok.
recipientName Odfiltruje zásielky s menom príjemcu obsahujúcim zadaný reťazec, pričom na veľkosti písmen nezáleží.
uiz1 Odfiltruje zásielky podľa primárneho identifikátora príjemcu.
registeredPostId Odfiltruje zásielky, ktorých podacie číslo obsahuje zadaný reťazec, pričom na veľkosti písmen nezáleží.
statusId Odfiltruje zásielky podľa ich stavu.
processedSince Odfiltruje zásielky spracované od zadaného času.
processedUntil Odfiltruje zásielky spracované do zadaného času.
distributedSince Odfiltruje zásielky distribuované (podané na pošte) od zadaného času.
distributedUntil Odfiltruje zásielky distribuované (podané na pošte) do zadaného času.
orderBy Usporiada zásielky podľa zvoleného stĺpca. Možné hodnoty sú id, price, status, recipientName, uiz1, createdOn, processedOn, distributedOn, registeredPostId. Predvolene sú zásielky usporadané vzostupne. Pre zostupné zoradenie je potrebné pred názov stĺpca zadať mínus (znak -).
limit Obmedzuje počet výsledkov vo vrátenom zozname dávok. Predvolená hodnota je 100.
offset Určuje index začiatočnej položky vo výslednom zozname dávok. Čísluje sa od nuly.
bundlesCreatedBy Odfiltruje zásielky obsahujúce v mene používateľa zadaný reťazec, pričom na veľkosti písmen nezáleží. Meno používateľa vypĺňa Zelená tlačiareň z operačného systému, na ktorom beží.
bundleName Odfiltruje zásielky obsahujúce v názve zadaný reťazec, pričom na veľkosti písmen nezáleží.
bundlesCreatedSince Odfiltruje zásielky, ktorých dávky boli vytvorené od zadaného času.
bundlesCreatedUntil Odfiltruje zásielky, ktorých dávky boli vytvorené do zadaného času.
customIds Zoznam vlastných identifikátorov, zásielky obsahujúce aspoň jeden z nich budú vrátené.
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
        <getMailingsRequest xmlns="http://schemas.zelenaposta.sk/sent">
            <mailings>
                <id>[int?]</id>
            </mailings>
            <bundles>
                <id>[int?]</id>
            </bundles>
            <recipientName>[string?]</recipientName>
            <uiz1>[string?]</uiz1>
            <registeredPostId>[string?]</registeredPostId>
            <statusId>[int?]</statusId>
            <processedSince>[dateTime?]</processedSince>
            <processedUntil>[dateTime?]</processedUntil>
            <distributedSince>[dateTime?]</distributedSince>
            <distributedUntil>[dateTime?]</distributedUntil>
            <!--Possible values are id, price, status, recipientName, uiz1, createdOn, processedOn, distributedOn, registeredPostId. Use minus sign as prefix for descendant order.-->
            <orderBy>[string?]</orderBy>
            <limit>[int?]</limit>
            <offset>[int?]</offset>
            <bundlesCreatedBy>[string?]</bundlesCreatedBy>
            <bundleName>[string?]</bundleName>
            <bundlesCreatedSince>[dateTime?]</bundlesCreatedSince>
            <bundlesCreatedUntil>[dateTime?]</bundlesCreatedUntil>
            <customIds>
                <customId>[string?]</customId>
            </customIds>
        </getMailingsRequest>
    </Body>
</Envelope>

Odpoveďou je zoznam vyfiltrovaných zásielok.

Názov Popis
totalCount Celkový počet zásielok vo výslednom zozname.
bundles/bundle Odoslaná zásielka.

Každá odoslaná zásielka má nasledovné vlastnosti:

Názov Popis
id Identifikátor zásielky.
bundleId Identifikátor dávky.
bundleTitle Názov dávky.
createdOn Čas vytvorenia dávky.
createdBy Používateľ, ktorý vytvoril dávku, tvorený názvom počítača a menom používateľa podľa operačného systému, kde bola dávka vytvorená. Názov počítača a meno používateľa sú oddelené spätným lomítkom (znakom \). V prípade, že nie je názov počítača k dispozícii, obsahuje iba meno používateľa.
distributedOn Čas distribúcie (podaja na pošte) zásielky.
processedOn Čas spracovania zásielky.
senderName Meno odosielateľa.
senderStreet Ulica odosielateľa.
senderCity Mesto odosielateľa.
senderZip PSČ odosielateľa.
senderCountry Krajina odosielateľa.
recipientName Meno príjemcu.
recipientStreet Ulica príjemcu.
recipientCity Mesto príjemcu.
recipientZip PSČ príjemcu.
recipientCountry Krajina príjemcu.
electronic Indikuje, či je zásielka elektronická.
productTitle Názov produktu, ktorý bol použitý na odoslanie zásielky.
uiz1 Primárny identifikátor príjemcu.
uiz2 Doplnkový identifikátor príjemcu.
customId Vlastný identifikátor zásielky (napr. číslo faktúry alebo zmluvy).
pageCount Počet strán zásielky.
price Cena zásielky s DPH.
registeredPostId Podacie číslo zásielky. Je vyplnené v prípade doporučenej zásielky.
status Číselný kód stavu zásielky.
statusText Lokalizovaný text stavu zásielky.
statusDate Čas zmeny stavu zásielky.
postStatusCode Kód stavu zásielky v Slovenskej pošte. Vypĺňa sa iba v prípade doporučených zásielok.
postStatusText Text stavu zásielky v Slovenskej pošte. Vypĺňa sa iba v prípade doporučených zásielok.
customId Vlastný identifikátor zásielky.
customIds Zoznam vlastných identifikátorov zásielky (zásielka ich môže mať viac). Vo formáte JSON poľa.
<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/sent">
    <soap:Body>
        <ns6:getMailingsResponse>
            <ns6:totalCount>1</ns6:totalCount>
            <ns6:mailings>
                <ns6:mailing>
                    <ns6:id>1</ns6:id>
                    <ns6:bundleId>1</ns6:bundleId>
                    <ns6:bundleTitle>Testovacia dávka</ns6:bundleTitle>
                    <ns6:createdOn>2017-01-01T12:00:00.000+01:00</ns6:createdOn>
                    <ns6:processedOn>2017-01-01T15:30:00.000+01:00</ns6:processedOn>
                    <ns6:senderName>Zelená pošta</ns6:senderName>
                    <ns6:senderStreet>Údernícka 15</ns6:senderStreet>
                    <ns6:senderCity>Bratislava</ns6:senderCity>
                    <ns6:senderZip>851 01</ns6:senderZip>
                    <ns6:senderCountry>sk</ns6:senderCountry>
                    <ns6:recipientName>Jane Doe
Zelená pošta</ns6:recipientName>
                    <ns6:recipientStreet>Údernícka 15</ns6:recipientStreet>
                    <ns6:recipientCity>Bratislava</ns6:recipientCity>
                    <ns6:recipientZip>851 01</ns6:recipientZip>
                    <ns6:recipientCountry>sk</ns6:recipientCountry>
                    <ns6:electronic>false</ns6:electronic>
                    <ns6:productTitle>Obyčajný list</ns6:productTitle>
                    <ns6:uiz1></ns6:uiz1>
                    <ns6:uiz2></ns6:uiz2>
                    <ns6:pageCount>1</ns6:pageCount>
                    <ns6:price>0.631440</ns6:price>
                    <ns6:status>10</ns6:status>
                    <ns6:statusText>Vytlačená</ns6:statusText>
                    <ns6:statusDate>2017-01-01T16:00:00.000+01:00</ns6:statusDate>
                    <ns6:customId>vlastny identifikator 1</ns6:customId>
                    <ns6:customIds>[ "vlastny identifikator 2","vlastny identifikator 3","vlastny identifikator 1" ]</ns6:customIds>
                </ns6:mailing>
            </ns6:mailings>
        </ns6:getMailingsResponse>
    </soap:Body>
</soap:Envelope>

Stavy zásielok sú nasledovné:

ID Popis
1 Zásielka bola vytvorená.
4 Spracovanie zásielky zlyhalo.
5 Zásielka bola zrušená.
6 Spracovanie zásielky bolo manuálne pozdržané.
7 Zásielka je ignorovaná.
8 Zásielka bola odoslaná na tlač.
9 Zásielka bola prijatá u tlačového poskytovateľa
10 Zásielka bola vytlačená.
11 Zásielka bola podaná na pošte.
12 Zásielka bola opätovne podaná na pošte.
13 Zásielka bola doručená.

cancelMailings

Zruší odoslané zásielky. Zásielky je možné zrušiť, len ak ešte neboli odoslané na tlač a len ak existujú.

Názov Popis
mailingIds/id Identifikátory zásielok, ktoré majú byť zrušené.
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
        <cancelMailingsRequest xmlns="http://schemas.zelenaposta.sk/sent">
            <mailingIds>
                <id>[int?]</id>
            </mailingIds>
        </cancelMailingsRequest>
    </Body>
</Envelope>

cancelBundles

Zruší odoslané zásielky v zadaných dávkach. Zásielky je možné zrušiť, len ak ešte neboli odoslané na tlač a len ak existujú.

Názov Popis
bundleIds/id Identifikátory dávok, ktorých zásielky majú byť zrušené.
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
        <cancelBundlesRequest xmlns="http://schemas.zelenaposta.sk/sent">
            <bundleIds>
                <id>[int?]</id>
            </bundleIds>
        </cancelBundlesRequest>
    </Body>
</Envelope>

sendPostcards

Jedná sa o zjednodušenú verziu metódy sendMailings umožňujúcu jednoduchšie posielanie pohľadníc. Je nutné zadať aspoň jeden element postcard.

Názov Popis
title Názov dávky je voliteľný a vygeneruje sa automaticky v prípade, že nie je zadaný. Tento názov je viditeľný v odoslaných dávkach na portáli Zelenej pošty, preto by mal byť dostatočne výstižný.
product Označenie produktu, ktorý bude použitý na odoslanie pohľadnice. Produkt musí byť určený pre odosielanie pohľadníc. Povinná položka.
postcards/frontPage Súbor obrázku prednej strany pohľadnice alebo PDF súbor zakódovaný v Base64. Povinná položka.
postcards/backPage Súbor obrázku zadnej strany pohľadnice alebo PDF súbor zakódovaný v Base64. Ak sa použije tlačí sa len takáto zadná strana a už žiadne dodatočné informácie o príjemcovi.
postcards/text Text pohľadnice. Povinná položka ak nebol pridaný obrázok zadnej strany.
postcards/recipient Súhrnný wrapper adresy príjimateľa. Povinná položka.
postcards/recipient/name Meno príjemcu pohľadnice.
postcards/recipient/street Ulica príjemcu pohľadnice.
postcards/recipient/city Miesto bydliska príjemcu pohľadnice.
postcards/recipient/zip Poštové smerovacie číslo na príjemcu pohľadnice.
postcards/recipient/country Krajina príjemcu pohľadnice.
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
        <sendPostcardsRequest xmlns="http://schemas.zelenaposta.sk/sent">
            <title>Testovacia pohľadnica</title>
            <product>POSTCARD_PRODUCT</product>
            <postcards>
                <postcard>
                    <frontPage>[base64Binary?]</frontPage>
                    <backPage>[base64Binary?]</backPage>
                    <text>[string?]</text>
                    <recipient>
                        <name>
                            Jane Doe
                            Zelená pošta
                        </name>
                        <street>Údernícka 15</street>
                        <city>Bratislava</city>
                        <zip>851 01</zip>
                        <country>sk</country>
                    </recipient>
                </postcard>
            </postcards>
        </sendPostcardsRequest>
    </Body>
</Envelope>

getBundlesStats

Metóda, ktorá vráti štatistiku čakajúcich, spracovaných a zrušených zásielok v dávke.

Názov Popis
bundleIds/id Identifikátory dávok, pre ktoré chceme zobraziť štatistiky.
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
        <getBundlesStatsRequest xmlns="http://schemas.zelenaposta.sk/sent">
            <bundleIds>
                <id>[int?]</id>
            </bundleIds>
        </getBundlesStatsRequest>
    </Body>
</Envelope>

Odpoveď obsahuje zoznam dávok a k nim náležiace štatistiky.

Názov Popis
bundleId Identifikátor dávky.
pending Počet zásielok z dávky, ktoré čakajú na spracovanie.
processed Počet zásielok z dávky, ktoré boli spracované.
canceled Počet zásielok z dávky, ktoré boli zrušené.
<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/sent">
    <soap:Body>
        <ns6:getBundlesStatsResponse>
            <ns6:bundlesStats>
                <ns6:bundle>
                    <ns6:bundleId>8897</ns6:bundleId>
                    <ns6:pending>0</ns6:pending>
                    <ns6:processed>2</ns6:processed>
                    <ns6:canceled>0</ns6:canceled>
                </ns6:bundle>
                <ns6:bundle>
                    <ns6:bundleId>8898</ns6:bundleId>
                    <ns6:pending>1</ns6:pending>
                    <ns6:processed>0</ns6:processed>
                    <ns6:canceled>0</ns6:canceled>
                </ns6:bundle>
            </ns6:bundlesStats>
        </ns6:getBundlesStatsResponse>
    </soap:Body>
</soap:Envelope>

getMailingPostStatuses

Metóda dokáže vrátiť všetky v histórii evidované poštové statusy (napr. že bola podaná na pošte) pre konkrétnu zásielku. Táto metódá funguje rovnako aj pre zásielky odosielané kuriérom prostredníctvom spoločnosti Remax.

Názov Popis
mailingId Číselný identifikátor konkrétnej zásielky, pre ktorú chceme získať poštové statusy.
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
        <getMailingPostStatusesRequest xmlns="http://schemas.zelenaposta.sk/sent">
            <mailingId>[int]</mailingId>
        </getMailingPostStatusesRequest>
    </Body>
</Envelope>

Odpoveď obsahuje zoznam jednotlivých statusov. Každý status má nasledovné atribúty:

Názov Popis
mailingId Číselný identifikátor konkrétnej zásielky, ktorej sa týkajú poštové statusy.
status Slovný kód statusu. Jedná sa o jednu z hodnôt received, transit, notified, delivered, returned alebo returning.
description Slovný popis statusu.
createdOn Dátum kedy status vznikol.
<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/sent">
    <soap:Body>
        <ns6:getMailingPostStatusesResponse>
            <ns6:postStatuses>
                <ns6:postStatus>
                    <ns6:mailingId>241504</ns6:mailingId>
                    <ns6:status>received</ns6:status>
                    <ns6:description>Zásielka podaná na pošte Bratislava 12</ns6:description>
                    <ns6:createdOn>2018-11-12T17:05:05+01:00</ns6:createdOn>
                </ns6:postStatus>
                <ns6:postStatus>
                    <ns6:mailingId>241504</ns6:mailingId>
                    <ns6:status>transit</ns6:status>
                    <ns6:description>Zásielka v preprave</ns6:description>
                    <ns6:createdOn>2018-11-12T19:13:13+01:00</ns6:createdOn>
                </ns6:postStatus>
            </ns6:postStatuses>
        </ns6:getMailingPostStatusesResponse>
    </soap:Body>
</soap:Envelope>