/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>