Zelená pošta pre Android

Zelená pošta pre Android

Inštalovať
Zelená pošta pre Android

Zelená pošta pre iPhone/iPad

Inštalovať

API pre odosielanie zásielok

Pre odosielanie zásielok je možné použiť metódu send webovej služby pre odosielanie zásielok.

Pre zabezpečenie konverzie príjemcov z fyzického odberu na elektronický je potrebné poskytnúť hodnoty UID/PIN, ktoré budú použité na pečiatke v zásielke. Hodnoty UID/PIN sa generujú pri volaní metódy prepare.

Pre získanie zoznamu dostupných produktov slúži metóda getProducts.

Názov Hodnota
WSDL https://gateway.zelenaposta.sk/api/mailing?wsdl

Pre použitie tejto služby je potrebná autentifikácia odosielateľa.

Odoslanie zásielky

Najjednoduchším prípadom je odoslanie dávky s jednou listovou zásielkou pomocou volania metódy send:


  <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>…</file>
  </document>
  </documents>
  <recipient>
  <name>Zelená pošta s.r.o.</name>
  <street>Galvániho 17/B</street>
  <city>Bratislava</city>
  <zip>82104</zip>
  <country>sk</country>
  </recipient>
  </mailing>
  </mailings>
  </sendRequest>
  </Body>
  </Envelope>

  

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ý.

Produkt pre zásielku je určený v elemente product.

V elemente documents je zoznam elementov document, ktoré reprezentujú dokumenty v danej zásielke. Dokument má v sebe element file s base64-zakódovaným PDF dokumentom.

Pozn.: Toto API aktuálne nepodporuje viacero dokumentov v jednej zásielke.

V elemente recipient je korešpondenčná adresa príjemcu.

Návratové hodnoty

V prípade úspechu je odpoveďou:


  <SOAP-ENV: Envelope xmlns: SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV: Header/>
  <SOAP-ENV: Body>
  <ns2: sendResponse xmlns: ns2="http://schemas.zelenaposta.sk/api/mailing">
  <ns2: slotId>504633805229137987812380290710369292658</ns2: slotId>
  </ns2: sendResponse>
  </SOAP-ENV: Body>
  </SOAP-ENV:Envelope>

V elemente slotId je identifikátor, pomocou ktorého je možné identifikovať odoslanú dávku pri prípadnej ďalšej komunikácii so Zelenou poštou.

Získanie zoznamu produktov

Pre získanie zoznamu dostupných produktov pre daného odosielateľa je potrebné zavolať metódu getProducts.


  <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>
  <getProductsRequest xmlns="http://schemas.zelenaposta.sk/api/mailing"/>
  </Body>
  </Envelope>

  

Odpoveďou je zoznam produktov:


  <SOAP-ENV: Envelope xmlns: SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV: Header/>
  <SOAP-ENV: Body>
  <ns2: getProductsResponse xmlns: ns2="http://schemas.zelenaposta.sk/api/mailing">
  <ns2: products>
  <ns2: product>
  <ns2: name>Z2TRA4SCBDOODL</ns2: name>
  <ns2: title>Zásielka 2. triedy,  A4 jednostranná ČB tlač, dvojokienková obálka DL</ns2: title>
  <ns2: description>Tlač UID/PIN, odosielateľa, adresáta na druhú stranu prvého listu.</ns2: description>
  <ns2: pagesPerMailing>7</ns2: pagesPerMailing>
  <ns2: duplex>false</ns2: duplex>
  </ns2: product>
  …
  </ns2: products>
  </ns2:getProductsResponse>
  </SOAP-ENV: Body>
  </SOAP-ENV: Envelope>

  

Určenie adresy 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>Galvániho 17/B</street>
  <city>Bratislava</city>
  <zip>82104</zip>
  <country>sk</country>
  </sender>
  </mailing>

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 UIZ1/UIZ2. V takomto prípade je možné na fyzicky odoslaný dokument doplniť pečiatku UID/PIN, 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.


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

Identifikácia príjemcu pomocou UIZ1/UIZ2

Na identifikáciu príjemcu slúži identifikátor UIZ (unikátny identifikátor 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. 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.


  <mailing>
  <uiz1>46529233</uiz1>
  <uiz2>faktury</uiz2>
  …
  </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>Galvániho 17/B</street>
  <city>Bratislava</city>
  <zip>82104</zip>
  <country>sk</country>
  </address>
  </mailing>

Táto adresa bude predvyplnená pri registrácii používateľa na portáli Zelenej pošty.

Registrácia príjemcu prostredníctvom UID/PIN

Príjemca môže na registráciu na portáli Zelenej pošty použiť hodnoty UID/PIN, ktoré sú spárované s jeho identifikačnými údajmi. Tieto hodnoty generuje Zelená pošta.


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

Získanie hodnôt UID/PIN

Pre získanie hodnôt UID/PIN je potrebné pred samotným odoslaním zavolať metódu prepare:


  <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>
  <prepareRequest xmlns="http://schemas.zelenaposta.sk/api/mailing">
  <mailings>
  <mailing>
  <uiz1>46529233</uiz1>
  <address>
  <name>Zelená pošta s.r.o.</name>
  <street>Galvániho 17/B</street>
  <city>Bratislava</city>
  <zip>82104</zip>
  <country>sk</country>
  </address>
  </mailing>
  </mailings>
  </prepareRequest>
  </Body>
  </Envelope>

  

Odpoveď bude vyzerať nasledovne:


  <SOAP-ENV: Envelope xmlns: SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV: Header/>
  <SOAP-ENV: Body>
  <ns2: prepareResponse xmlns: ns2="http://schemas.zelenaposta.sk/api/mailing">
  <ns2: mailings>
  <ns2: mailing>
  <ns2: uid>Ikfj6h9jC8OS</ns2: uid>
  <ns2: pin>1234</ns2:pin>
  <ns2: acceptsEmails>false</ns2: acceptsEmails>
  </ns2: mailing>
  </ns2: mailings>
  </ns2:prepareResponse>
  </SOAP-ENV: Body>
  </SOAP-ENV: Envelope>

Odosielatelia, ktorí si tlačia zásielky vo vlastnej réžii, musia nastaviť indikátor printed na true, aby sa token v databáze Zelenej pošty UID/PIN označil ako vytlačený.


  <prepareRequest xmlns="http://schemas.zelenaposta.sk/api/mailing">
  <printed>true</printed>
  <mailings>
  …
  </mailings>
  </prepareRequest>

Odosielanie elektronickej zásielky

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


  <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>
  <uiz1>46529233</uiz1>
  <product>EMAIL</product>
  <documents>
  <document>
  <file>…</file>
  </document>
  </documents>
  </mailing>
  </mailings>
  </sendRequest>
  </Body>
  </Envelope>

  

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.


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