/api/2/received

/api/2/received

Táto služba umožňuje získať informácie o prijatých zásielkách.

getDocuments

Pre získanie prijatých zásielok je možné použiť metódu getDocuments tejto webovej služby. Parametre tejto metódy sú voliteľné a ak nie sú uvedené služba vracia 100 posledne prijatých zásielok. Nižšie môžete vidieť XML požiadavku so všetkými parametrami. Tieto parametre sú opísané nižšie.

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
        <getDocumentsRequest xmlns="http://schemas.zelenaposta.sk/received">
            <id>[int?]</id>
            <receivedSince>[dateTime?]</receivedSince>
            <receivedUntil>[dateTime?]</receivedUntil>
            <flag>[string?]</flag>
            <registrationId>[int?]</registrationId>
            <paid>[boolean?]</paid>
            <senderDisplayName>[string?]</senderDisplayName>
            <customDocument>[boolean?]</customDocument>
            <friends>
                <friend>[string?]</friend>
            </friends>
            <orderBy>[string?]</orderBy>
            <limit>[int?]</limit>
            <offset>[int?]</offset>
            <pastDue>[boolean?]</pastDue>
            <includeFriends>[boolean?]</includeFriends>
        </getDocumentsRequest>
    </Body>
</Envelope>
Názov parametru Popis
id Číselný identifikátor prijatej zásielky, ak je zadaný vráti sa iba zásielka s týmto ID (ak nejaká existuje)
receivedSince Dátum od ktorého budú získané zásielky (teda budú vrátené len zásielky s parametrom createdOn väčším ako zadaná hodnota). Môže byť zadaný len dátum tj. napríklad 2018-01-01 alebo aj konkrétny čas napr. 2018-01-01T16:34:54.011+01:00.
receivedUntil Podobný parameter ako receivedSince, ale budú vrátené len zásielky s parametrom createdOn menším ako zadaná hodnota
flag Ak je zadaný tento parameter budú vrátené len zásielky s daným označením. Používajú sa označenia blue, green, orange a red, vyjadrujú dôležitosť zásielky, predvolene zásielka nemá žiadne označenie.
registrationId Číselný identifikátor registrácie na prijímanie zásielok v systéme Zelenej pošty. Budú vrátene len zásielky viažúce sa na konkrétnu registráciu, napr. pre BVS.
paid Ak je zadaná hodnota true budú vrátené len zaplatené prijaté faktúry, ak false tak iba nezaplatené. Ak nie je parameter uvedený na stav zaplatenia sa nepozerá. Tento parameter sa nezohľadňuje ak bol uvedený parameter pastDue s hodnotu true, pretože vtedy sa vracajú len zásielky po lehote splatnosti a nezáleží na tom či boli zaplatené.
senderDisplayName Budú vrátené len zásielky od konkrétneho odosielateľa, napr. Bratislavská vodárenská spoločnosť, a. s.
customDocument Ak je zadaná hodnota true budú vrátené len samostatne pridané dokumenty, ktoré neboli doručené priamo od nejakého odosielateľa. Ak false tak budú vrátené iba zásielky tradične prijaté od odosielateľa. Ak nie je parameter uvedený budú vrátené akékoľvek zásielky.
friends Parameter môže obsahovať viacero aliasov alebo čísiel účtov priateľov uvedených v tagoch friend. Ak sú zadané budú vrátené aj zásielky pre daných priateľov.
orderBy Parameter vyjadrujúci podľa čoho majú byť vrátené zásielky zoradené. Môže obsahovať viacero názvov parametrov oddelených čiarkami, taktiež môže byť pridaná informácia, či sa má zoraďovať zostupne alebo vzostupne. Napr. flag asc, id desc bude zoraďovať zásielky podľa označenia vzostupne a pre rovnaké označenia ešte zásielky zoradí aj podľa ID zostupne. Povolené hodnoty názvov parametrov sú pastDue, id, flag, registrationId, paid, createdOn, amount, paid, senderDisplayName a customDocument. Pre označenie či sa má zoraďovať zostupne alebo vzostupne sa používajú označenia desc a asc za označením parametru, prípadne znaky - a + pred názvom parametru (teda napr. -createdOn pre zostupné zoradenie podľa dátumu prijatia zásielky), ak nebudú uvedené zoraďuje sa predvolene vzostupne.
limit Počet zásielok, ktoré majú byť vrátené. Ak nie je uvedená žiadna hodnota vracia sa maximálne 100 zásielok.
offset Počet preskočených zásielok, v prípade hodnoty 10 sa preskočí prvých 10 zásielok a vrátia sa až ďalšie. Možné kombinovať s parametrom limit pre zabezpečenie stránkovania.
pastDue Ak je zadaná hodnota true budú vrátené len zásielky po lehote splatnosti, ak false tak iba pred touto lehotou. Ak nie je parameter uvedený na stav zaplatenia sa nepozerá. Tento parameter sa zohľadňuje prednostne pred parametrom paid, ak sa majú vracať zásielky po lehote splatnosti nezáleží na tom, či boli zaplatené.
includeFriends Ak je zadaná hodnota true bude vrátený aj zoznam priateľov, v ktorom bude uvedený email, číslo účtu a meno jednotlivých priateľov.

Nižšie môžete vidieť ukážkovú odpoveď metódy na získanie prijatých zásielok a popis jednotlivých parametrov. Odpoveď obsahuje element documents, ktorý môže obsahovať viacero elementov document, ktoré vyjadrujú jednotlivé prijaté zásielky.

<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/received">
    <soap:Body>
        <ns6:getDocumentsResponse>
            <ns6:totalCount>1</ns6:totalCount>
            <ns6:documents>
                <ns6:document>
                    <ns6:id>58678</ns6:id>
                    <ns6:filename>1130000026.pdf</ns6:filename>
                    <ns6:registrationId>37341</ns6:registrationId>
                    <ns6:templateId>55</ns6:templateId>
                    <ns6:templateName>Zásielka</ns6:templateName>
                    <ns6:amount>0.01</ns6:amount>
                    <ns6:paid>false</ns6:paid>
                    <ns6:alwaysPaid>false</ns6:alwaysPaid>
                    <ns6:isPayable>true</ns6:isPayable>
                    <ns6:paymentId>100000640938472549163746bdoe</ns6:paymentId>
                    <ns6:dueOn>2013-08-16T00:00:00+02:00</ns6:dueOn>
                    <ns6:issuedOn>2013-08-07T00:00:00+02:00</ns6:issuedOn>
                    <ns6:variableSymbol>1130000026</ns6:variableSymbol>
                    <ns6:constantSymbol>0308</ns6:constantSymbol>
                    <ns6:specificSymbol>9876</ns6:specificSymbol>
                    <ns6:iban>SK6802000000350001004062</ns6:iban>
                    <ns6:senderId>15838</ns6:senderId>
                    <ns6:senderAlias>BVS</ns6:senderAlias>
                    <ns6:senderAccountNumber>100174203</ns6:senderAccountNumber>
                    <ns6:senderDisplayName>Bratislavská vodárenská spoločnosť, a. s.</ns6:senderDisplayName>
                    <ns6:senderAvatar>16203.png</ns6:senderAvatar>
                    <ns6:senderBankAccount>SK6802000000350001004062</ns6:senderBankAccount>
                    <ns6:recipientAccountNumber>100000640</ns6:recipientAccountNumber>
                    <ns6:recipientDisplayName>accalio</ns6:recipientDisplayName>
                    <ns6:noteText>faktúra zaplatená dňa 07.05.2014</ns6:noteText>
                    <ns6:notificationId>77</ns6:notificationId>
                    <ns6:notificationRemindOn>2018-05-10T00:00:00+02:00</ns6:notificationRemindOn>
                    <ns6:notificationMessage>Reminder</ns6:notificationMessage>
                    <ns6:customDocument>false</ns6:customDocument>
                    <ns6:ocrStateId>3</ns6:ocrStateId>
                    <ns6:createdOn>2013-08-07T09:26:22.442+02:00</ns6:createdOn>
                    <ns6:seenOn>2018-08-02T10:12:10.417+02:00</ns6:seenOn>
                    <ns6:edCanAuthorize>true</ns6:edCanAuthorize>
                    <ns6:edAuthorizedOn>2018-08-02T10:12:10.417+02:00</ns6:edAuthorizedOn>
                    <ns6:edMessageId>489489</ns6:edMessageId>
                    <ns6:tid>1375860382351</ns6:tid>
                    <ns6:publicToken>a6a7e8a079ac6f4c1b81551d632b2257</ns6:publicToken>
                </ns6:document>
            </ns6:documents>
            <ns6:friends>
                <ns6:friend>
                    <ns6:username>tester@zelenaposta.sk</ns6:username>
                    <ns6:accountNumber>123456789</ns6:accountNumber>
                    <ns6:text>John Doe</ns6:text>
                </ns6:friend>
            </ns6:friends>
        </ns6:getDocumentsResponse>
    </soap:Body>
</soap:Envelope>
Názov Popis
totalCount Celkový počet vrátených zásielok bez zohľadnenia offsetu. Podľa tejto hodnoty možno určiť stránkovanie.
id Číselný unikátny identifikátor zásielky.
filename Názov súboru dokumentu zásielky.
registrationId Číselný identifikátor registrácie, v rámci ktorej bola zásielka prijatá.
templateId Číselný identifikátor šablóny danej zásielky.
templateName Názov šablóny danej zásielky.
amount Suma na úhradu, môže byť uvedené ak je zásielka prijatou faktúrou.
paid Pravdivostná hodnota vyjadrujúca či faktúra už bola zaplatená.
alwaysPaid Pravdivostná hodnota vyjadrujúca či je faktúra neustále označená ako zaplatená.
isPayable Pravdivostná hodnota vyjadrujúca či je zásielka označená ako platiteľná.
paymentId Číselný identifikátor platby prijatej faktúry.
dueOn Dátum splatnosti prijatej faktúry.
issuedOn Dátum vystavenia prijatej faktúry.
variableSymbol Variabilný symbol prijatej faktúry.
constantSymbol Konštantný symbol prijatej faktúry.
specificSymbol Špecifický symbol prijatej faktúry.
iban IBAN určený pre zaplatenie faktúry.
senderId Číselný identifikátor odosielateľa prijatej zásielky.
senderAlias Textový alias odosielateľa prijatej zásielky.
senderAccountNumber Číslo účtu (v systéme Zelenej pošty) odosielateľa prijatej zásielky.
senderDisplayName Názov odosielateľa prijatej zásielky.
senderAvatar Názov súboru loga odosielateľa prijatej zásielky.
senderBankAccount Číslo účtu IBAN odosielateľa prijatej zásielky.
recipientAccountNumber Číslo účtu (v systéme Zelenej pošty) príjemcu prijatej zásielky.
recipientDisplayName Názov príjemcu prijatej zásielky.
noteText Text poznámky k prijatej zásielke.
notificationId Číselný identifikátor notifikácie viažúcej sa k zásielke.
notificationRemindOn Dátum a čas označujúci kedy bolo nazásielku upozornené prostredníctvom notifikácie.
notificationMessage Text notifikácie viažúcej sa k prijatej zásielke.
customDocument Pravdivostná hodnota vyjadrujúca či je prijatá zásielka pridaná samostatne.
ocrStateId Stav rozpoznania textu v zásielke. Možné hodnoty sú: 1 - zahájené rozpoznávanie, 2 - čakajúce rozpoznávanie, 3 - úspešné rozpoznané, 4 - rozpoznanie zlyhalo
createdOn Dátum prijatia zásielky.
seenOn Dátum zobrazenia prijatej zásielky.
edCanAuthorize Ak sa jedná o prijatú zásielku zo štátnej schránky s doručenkou, ktorá ešte nebola potvrdená (a je ju možné potvrdiť) bude mať tento parameter hodnotu true. Potvrdenie je možné realizovať prostredníctvom služby /api/2/upvs.
edAuthorizedOn Ak sa jedná o prijatú zásielku zo štátnej schránky s doručenkou, ktorá už bola potvrdená je tu uvedený dátum tohto potvrdenia.
edMessageId Ak sa jedná o prijatú zásielku zo štátnej schránky nachádza sa v tomto parametri číselný identifikátor tejto zásielky. Na základe tohto ID je možné napríklad potvrdzovať doručenky.
tid Dátum prijatia zásielky v milisekundách. Nemusí byť uvedený vždy.
publicToken Verejný token slúžiaci na stiahnutie prijatej zásielky.

V prípade ak bol zadaný parameter includeFriends s hodnotou true sa v odpovedi nachádza aj zoznam priateľov uvedený v elemente friends, v ňom sa môžu nachádzať viaceré elementy friend reprezentujúce jednotlivých priateľov:

Názov Popis
username Email priateľa.
accountNumber Číslo účtu priateľa v systéme Zelenej pošty.
text Meno priateľa (môže sa jednať o meno osoby alebo názov firmy).

getDocumentRaw

Pre stiahnutie prijatej zásielky je možné použiť metódu getDocumentRaw tejto webovej služby. Zásielku je možné stiahnuť na základe jej ID alebo na základe verejného tokenu (tieto údaje je možné získať prostredníctvom metódy getDocuments). Nižšie môžete vidieť XML požiadavku so všetkými parametrami. Tieto parametre sú opísané nižšie.

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
        <getDocumentRawRequest xmlns="http://schemas.zelenaposta.sk/received">
            <documentId>[int?]</documentId>
            <publicLinkToken>[string?]</publicLinkToken>
        </getDocumentRawRequest>
    </Body>
</Envelope>
Názov parametru Popis
id Číselný identifikátor prijatej zásielky, ktorá sa má stiahnuť. Povinný parameter v prípade ak nebol zadaný token.
publicLinkToken Verejný token slúžiaci na stiahnutie zásielky. Povinný parameter ak nebolo zadané ID, v prípade ak bolo zadané aj ID na stiahnutie sa použije token a nie ID.

Odpoveďou tejto metódy (v prípade ak sa konkrétna zásielka našla) je priamo samotný dokument zásielky (teda PDF).



Dotazy:

info@zelenaposta.cz

Služby API2