Dokumentace k nevizuálnímu rozhraní aplikace DopisOnline Rozhraní slouží k automatizovanému podání listovních zásilek elektronickou cestou z aplikací třetích stran. Veškerá komunikace s naším serverem probíhá přes zabezpečený protokol HTTPS s autorizací uživ. jménem a heslem. Parametry a obsah zásilky se předávají metodou POST. URL skriptu, který přijímá zásilky: https://online.postservis.cz/cmdedopis/dopisonline.php URL formuláře z prohlížeče: https://online.postservis.cz/cmdedopis/form.html Slepá testovací verze skriptu, která veškerá data po přenosu stornuje: https://online3.postservis.cz/cmdedopis/dopisonline.php Maximální počet souběžných připojení na jedno uživatelské jméno je omezeno na tři. Při překročení tohoto počtu nebude zásilka přijata a přenos bude ukončen s chybou č. 43. Skriptu se předává celkem 19 parametrů. 1. user přihlašovací jméno (povinný) 2. passwd přihlašovací heslo (povinný) 3. barvatisku požadovaná barva tisku (povinný) 4. typvyplatneho druh zásilky (povinný) 5. typuhrady jak se bude platit dopis (povinný) 6. typvystupu určuje formát, v jakém se budou vracet informace o založení zakázky, nebo chybové stavy txt hodnoty jsou oddělené tabulátorem chr(9) a řádky znaky CRLF csv hodnoty jsou oddělené středníkem - chr(59) a řádky znaky CRLF xml viz struktura níže bez parametru vypisuje se do konzole, hodnoty jsou oddělené tabulátorem - chr(9) 7. soubor soubor PDF (povinný) Následující položky jsou povinné pro zásilky s dodejkou. Pokud jsou předávány skriptu u ostatních typů zásilek, je nutné je naplnit prázdným řetězcem. 8. odsosloveni Odesílatel oslovení (char 25) 9. odsfirma Odesílatel firma (char 100) 10. odsosoba Odesílatel osoba (char 100) 11. odsulice Odesílatel ulice (char 100) 12. odsobec Odesílatel obec (char 100) 13. odspsc Odesílatel PSČ (char 5) 14. adrosloveni Adresát oslovení (char 25) 15. adrfirma Adresát firma (char 100) 16. adrosoba Adresát osoba (char 100) 17. adrulice Adresát ulice (char 100) 18. adrobec Adresát obec (char 100) 19. adrpsc Adresát PSČ (char 5)
Po zpracování a ověření předaných parametrů a PDF souboru se generuje odpověď v požadovaném formátu viz. parametr typvystupu. Součástí odpovědi je souhrn podacích parametrů viz. výstup XML: Při řádném založení zakázky: <?xml version="1.0" encoding=" windows-1250 "?> <zakazka> <soubor type="string">test.pdf</soubor> <pocetstranek type="integer">1</pocetstranek> <kodobjednavky type="string">20090601050001</kodobjednavky> <podacicislo type="string">51000</podacicislo> <datumpodani type="date">2009-06-01</datumpodani> <podaciposta type="string">370 20</podaciposta> <cena mena="czk" type="decimal">14</cena> <barvatisku type="integer">0</barvatisku> <typvyplatneho type="integer">67</typvyplatneho> <varovani type= integer >0</varovani> </zakazka> Při chybovém stavu: <?xml version="1.0" encoding=" windows-1250 "?> <chyba> <kod type="integer">16</kod> <popis type="string"> Chyba při kopírování souboru </popis> </chyba> Chybové stavy, které mohou nastat: Kód Chyba 1 Proměnná user neexistuje 2 Proměnná user je prázdná 3 Proměnná passwd neexistuje 4 Proměnná passwd je prázdná 5 Proměnná barva neexistuje 6 Proměnná barva je prázdná 7 Proměnná typvyplatneho neexistuje 8 Proměnná typvyplatneho je prázdná 9 Proměnná typuhrady neexistuje 10 Proměnná typuhrady je prázdná 11 Proměnná soubor neexistuje 12 Proměnná soubor je prázdná 13 Typ úhrady není povolen, nebo neexistuje 14 Typ výplatného je mimo rozsah 15 Špatně zadaná barva 16 Chyba při kopírování souboru 17 Chyba při kontrole PDF souboru 18 Překročení počtu stánek v dokumentu 19 Není ve formátu A4, dokument je šifrován
20 Nepodařilo se založit zakázku č 21 Přihlášení pomocí uživatelského jména se nepovedlo 22 Tento typ zakázky zatím nepodporujeme 23 Proměnná odsosloveni neexistuje 24 Proměnná odsfirma neexistuje 25 Proměnná odsfirma je prázdná 26 Proměnná odsosoba neexistuje 27 Proměnná odsulice neexistuje 28 Proměnná odsulice je prázdná 29 Proměnná odsobec neexistuje 30 Proměnná odsobec je prázdná 31 Proměnná odspsc neexistuje 32 Proměnná odspsc je prázdná 33 Proměnná adrosloveni neexistuje 34 Proměnná adrfirma neexistuje 35 Proměnná adrfirma je prázdná 36 Proměnná adrosoba neexistuje 37 Proměnná adrulice neexistuje 38 Proměnná adrulice je prázdná 39 Proměnná adrobec neexistuje 40 Proměnná adrobec je prázdná 41 Proměnná adrpsc neexistuje 42 Proměnná adrpsc je prázdná 43 Překročen limit souběžných připojení 44 Soubor neobsahuje vložené fonty Při návrhu vlastních aplikací je nutné počítat s možnou změnou a rozšířením typů výplatného, úhrad, výstupů a druhů tisků. Obsahy platných číselníků je proto nutné vždy ověřit POST dotazem na URL adrese: https://online.postservis.cz/cmdedopis/vratciselnik.php Odpovědí je vždy seznam dostupných hodnot obsahující kód a název odpovídající typu číselníku. Skriptu je nutné předat jako parametry dvě hodnoty - název číselníku a také typ výstupního souboru: chr(9) typciselniku určuje typ číselníku, který bude vrácen ve výstupu barvatisku seznam dostupných barev tisků typvyplatneho seznam možností výplatného typuhrady seznam možných typů úhrad typvystupu určuje formát, v jakém se budou vracet výpis číselníků txt hodnoty jsou oddělené tabulátorem - chr(9) csv hodnoty jsou oddělené středníkem - chr(59) xml viz struktura níže bez parametru vypisuje se do konzole, hodnoty jsou oddělené tabulátorem - Pro demonstrační účely je možné ověřit generování číselníku na tomto odkazu: https://online.postservis.cz/cmdedopis/formcis.html
Upozornění: Prosím věnujte pozornost umístění adresy příjemce, odesílatele a technologické zóně, které musí odpovídat vzoru: https://online.postservis.cz/download/dopisonline/sablona.pdf Veškeré další informace naleznete na stránkách Postservisu: https://online.postservis.cz/ Zde se můžete zaregistrovat (přihlašovací údaje obdržíte dop. zásilkou do vlastních rukou) a začít posílat zásilky bez nutnosti chodit na poštu. Dokumentace k nevizuálnímu rozhraní aplikace DopisOnline přehled zásilek Rozhraní slouží k automatizovanému přehledu zásilek z aplikací třetích stran. Veškerá komunikace s naším serverem probíhá přes zabezpečený protokol HTTPS s autorizací uživ. jménem a heslem. Parametry se předávají metodou POST. URL skriptu, který přijímá zásilky: https://online.postservis.cz/cmdedopis/eprehledzak.php URL formuláře pro vyzkoušení z prohlížeče https://online.postservis.cz/cmdedopis/test.html Skriptu se předává celkem 5 parametrů. 1. user přihlašovací jméno (povinný údaj) 2. passwd přihlašovací heslo (povinný údaj) 3. typvystupu - určuje formát, v jakém se budou vracet informace o zásilce, nebo chybové stavy txt - hodnoty jsou oddělené tabulátorem - chr(9) csv - hodnoty jsou oddělené středníkem - chr(59) xml - viz. struktura níže bez parametru - vypisuje se do konzole, hodnoty jsou oddělené tabulátorem - chr(9) 4. zasilka číslo zásilky (povinný údaj, pokud nezadáte datum) 5. datum datum ve formátu yyyymmdd 20090713 (povinný údaj, pokud nezadáte zásilku) Pokud bude vyplněna zásilka, tak se vygeneruje přehled pro zadanou zásilku. Pokud bude vyplněn datum, budou vygenerované zásilky v daném datumu. Jestli bude vyplněna zásilka i datum, tak se vždy bude generovat výstup podle zásilky. Po zpracování a ověření předaných parametrů se generuje odpověď v požadovaném formátu viz. parametr typvystupu. Součástí odpovědi je souhrn podacích parametrů a stavu zpracování zásilky viz. výstup XML: Zásilka, která čeká na zpracování. <?xml version="1.0" encoding="windows-1250"?> <dopisonline> <zakazka id="20100505069395">
<podacicislo type="string">neni</podacicislo> <pocetstranek type="integer">1</pocetstranek> <datumpodani type="datetime">2010-05-05 22:17:06</datumpodani> <cena mena="czk" type="decimal">12.60</cena> <barvatisku type="integer">0</barvatisku> <platba type="integer">0</platba> <typvyplatneho type="integer">66</typvyplatneho> <zpracovani type="integer">50</zpracovani> <stav type="integer">0</stav> </zakazka> </dopisonline> Zpracovaná zásilka. <?xml version="1.0" encoding="windows-1250"?> <dopisonline> <zakazka id="20100504068880"> <podacicislo type="string">neni</podacicislo> <pocetstranek type="integer">1</pocetstranek> <datumpodani type="datetime">2010-05-04 04:05:11</datumpodani> <cena mena="czk" type="decimal">12.60</cena> <barvatisku type="integer">0</barvatisku> <platba type="integer">0</platba> <typvyplatneho type="integer">66</typvyplatneho> <zpracovani type="integer">20</zpracovani> <stav type="integer">1</stav> <operace id="0"> <datumzpracovani type="datetime">2010-05-04 18:15:50</datumzpracovani> <typsluzby type="string">tisk</typsluzby> <nazevsluzby type="string">a4 (B&W)</nazevsluzby> <doba type="time">0:02</doba> </operace> <operace id="1"> <datumzpracovani type="datetime">2010-05-04 19:35:00</datumzpracovani> <typsluzby type="string">kompletace</typsluzby> <nazevsluzby type="string">uzavření papírové obálky</nazevsluzby> <doba type="time">0:33</doba> </operace> <operace id="2"> <datumzpracovani type="datetime">2010-05-04 19:35:00</datumzpracovani> <typsluzby type="string">kompletace</typsluzby> <nazevsluzby type="string">vlož. 1 listu adr. dokumentu A4</nazevsluzby> <doba type="time">0:33</doba> </operace> <operace id="3"> <datumzpracovani type="datetime">2010-05-04 20:17:41</datumzpracovani> <typsluzby type="string">expedice</typsluzby> <nazevsluzby type="string">expedice zakázky</nazevsluzby> <doba type="time">0:01</doba> </operace>
</zakazka> </dopisonline> Pořadí polí v případě výpisu do CSV (oddělovač středník) nebo TXT (oddělovač tabelátor) je následující: Kód podzakázky - unikátní identifikátor v celém systému pokud se budete dotazovat na nějaké informace o zpracování pracovníků zakázky Postservisu vždy uvádějte tento údaj podací číslo - ekvivalent klasickému podacímu číslu, toto číslo uvádějte při reklamacích na poštách počet stran počet stran v zaslaném PDF datum podání datum elektronického podání zásilky cena kalkulovaná cena zásilky druh tisku kód provedení tisku (dle platného číselníku) platba kód způsobu úhrady za zpracování zásilky (dle platného číselníku) typ výplatného - kód způsobu doručení (dle platného číselníku) zpracování kód některých stavů zpracování zakázky 20 Zakázka je aktivní v systému a probíhá její zpracování. 46 Zakázka byla stornována. 40 Zakázka čeká na zaplacení (jen u platby pomocí PremiumSMS). 50 Zakázka čeká na zpracování. stav status finálního dokončení zakázky 0-zakázka ještě není finálně zpracována (není předána k fakturaci) a v jednotlivých operacích můžou nastat změny 1-zakázka je předána na účtárnu a proběhly kontrolní operace zpracování zakázky je ukončeno datum zpracování datum začátku provedené operace se zakázkou doba doba zpracování typ služby název typu zpracování název služby konkrétní provedená operace Ukázka výstupu do CSV: 20100506069408;55312;1;2010-05-06 08:20:13;33.00;0;1;119;20;1;2010-05-06 18:56:39;0:02;Tisk;*** A4 (B&W) a odřádkováno CRLF Při chybovém stavu: <?xml version="1.0" encoding=" windows-1250 "?> <chyba> <kod type="integer">0</kod> <popis type="string"> Přístup je povolen pouze přes HTTPS protokol </popis> </chyba> Chybové stavy, které mohou nastat:
Kód Chyba 0 Přístup je povolen pouze přes HTTPS protokol 1 Proměnná user neexistuje 2 Proměnná user je prázdná 3 Proměnná passwd neexistuje 4 Proměnná passwd je prázdná 5 Proměnná zasilka neexistuje 6 Proměnná datum neexistuje 7 Proměnné zasilka a datum jsou prázdné 8 Nesprávné přihlašovací údaje 9 Zakázka č. 20090713050001' neexistuje 10 K datu 20090713 neexistuje žádný záznam Dokumentace k nevizuálnímu rozhraní aplikace DopisOnline podací lístek Rozhraní slouží k automatizovanému generování podacích lístků z aplikací třetích stran. Veškerá komunikace s naším serverem probíhá přes zabezpečený protokol HTTPS s autorizací uživ. jménem a heslem. Parametry se předávají metodou POST. URL skriptu, který přijímá zásilky: https://online.postservis.cz/cmdedopis/podlist.php URL formuláře pro vyzkoušení z prohlížeče https://online.postservis.cz/cmdedopis/podlist.html Skriptu se předává celkem 5 parametrů. 1. user přihlašovací jméno (povinný údaj) 2. passwd přihlašovací heslo (povinný údaj) 3. podcislo Podací číslo zásilky (povinný údaj) 4. typvystupu určuje, jak se bude vracet PDF soubor. Výchozí hodnota je nastavena na D. D vrátí PDF soubor ke stáhnutí (download file) I vrátí PDF soubor do prohlížeče (browser) S vrátí string 5. typlog určuje formát, v jakém se budou chybové stavy txt - hodnoty jsou oddělené tabulátorem - chr(9) csv - hodnoty jsou oddělené středníkem - chr(59) xml - viz. struktura níže bez parametru - vypisuje se do konzole, hodnoty jsou oddělené tabulátorem - chr(9)
Po zpracování a ověření předaných parametrů se generuje PDF soubor. Pokud dojde při zpracování k chybě, generuje se chybová odpověď dle zvoleného typu (txt, csv, xml, konzole). Výstup XML: <?xml version="1.0" encoding=" utf-8 "?> <chyba> <kod type="integer">0</kod> <popis type="string"> Přístup je povolen pouze přes HTTPS protokol </popis> </chyba> Chybové stavy, které mohou nastat: Kód Chyba 0 Přístup je povolen pouze přes HTTPS protokol 1 Proměnná user neexistuje 2 Proměnná user je prázdná 3 Proměnná passwd neexistuje 4 Proměnná passwd je prázdná 5 Proměnná podcislo neexistuje 6 Proměnná podcislo je prázdná 7 Nepodařilo se ověřit uživatele 8 Podací číslo nebylo nalazeno 9 Soubor k zakázce již neexistuje. Soubory se archivují 1 rok 10 Nelze vygenerovat náhled