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:
<soubor type="string">test.pdf <pocetstranek type="integer">1 20090601050001 <podacicislo type="string">51000 2009-06-01 <podaciposta type="string">370 20 14 0 67 0 Při chybovém stavu:
16 <popis type="string"> Chyba při kopírování souboru
Chybové stavy, které mohou nastat: Kód 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
Chyba Proměnná user neexistuje Proměnná user je prázdná Proměnná passwd neexistuje Proměnná passwd je prázdná Proměnná barva neexistuje Proměnná barva je prázdná Proměnná typvyplatneho neexistuje Proměnná typvyplatneho je prázdná Proměnná typuhrady neexistuje Proměnná typuhrady je prázdná Proměnná soubor neexistuje Proměnná soubor je prázdná Typ úhrady není povolen, nebo neexistuje Typ výplatného je mimo rozsah Špatně zadaná barva Chyba při kopírování souboru Chyba při kontrole PDF souboru Překročení počtu stánek v dokumentu Není ve formátu A4, dokument je šifrován
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
Nepodařilo se založit zakázku č Přihlášení pomocí uživatelského jména se nepovedlo Tento typ zakázky zatím nepodporujeme Proměnná odsosloveni neexistuje Proměnná odsfirma neexistuje Proměnná odsfirma je prázdná Proměnná odsosoba neexistuje Proměnná odsulice neexistuje Proměnná odsulice je prázdná Proměnná odsobec neexistuje Proměnná odsobec je prázdná Proměnná odspsc neexistuje Proměnná odspsc je prázdná Proměnná adrosloveni neexistuje Proměnná adrfirma neexistuje Proměnná adrfirma je prázdná Proměnná adrosoba neexistuje Proměnná adrulice neexistuje Proměnná adrulice je prázdná Proměnná adrobec neexistuje Proměnná adrobec je prázdná Proměnná adrpsc neexistuje Proměnná adrpsc je prázdná Překročen limit souběžných připojení 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: 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 chr(9)
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í. <dopisonline>
<podacicislo type="string">neni <pocetstranek type="integer">1 2010-05-05 22:17:06 12.60 0 0 66 50 <stav type="integer">0 Zpracovaná zásilka. <dopisonline>
<podacicislo type="string">neni <pocetstranek type="integer">1 2010-05-04 04:05:11 12.60 0 0 66 20 <stav type="integer">1 2010-05-04 18:15:50 Tisk A4 (B&W) <doba type="time">0:02 2010-05-04 19:35:00 Kompletace Uzavření papírové obálky <doba type="time">0:33 2010-05-04 19:35:00 Kompletace Vlož. 1 listu adr. dokumentu A4 <doba type="time">0:33 2010-05-04 20:17:41 Expedice Expedice zakázky <doba type="time">0:01
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:
0 <popis type="string"> Přístup je povolen pouze přes HTTPS protokol
Chybové stavy, které mohou nastat:
Kód 0 1 2 3 4 5 6 7 8 9 10
Chyba Přístup je povolen pouze přes HTTPS protokol Proměnná user neexistuje Proměnná user je prázdná Proměnná passwd neexistuje Proměnná passwd je prázdná Proměnná zasilka neexistuje Proměnná datum neexistuje Proměnné zasilka a datum jsou prázdné Nesprávné přihlašovací údaje Zakázka č. 20090713050001' neexistuje 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. 2. 3. 4.
user – přihlašovací jméno (povinný údaj) passwd – přihlašovací heslo (povinný údaj) podcislo – Podací číslo zásilky (povinný údaj) 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:
0 <popis type="string"> Přístup je povolen pouze přes HTTPS protokol
Chybové stavy, které mohou nastat: Kód 0 1 2 3 4 5 6 7 8 9 10
Chyba Přístup je povolen pouze přes HTTPS protokol Proměnná user neexistuje Proměnná user je prázdná Proměnná passwd neexistuje Proměnná passwd je prázdná Proměnná podcislo neexistuje Proměnná podcislo je prázdná Nepodařilo se ověřit uživatele Podací číslo nebylo nalazeno Soubor k zakázce již neexistuje. Soubory se archivují 1 rok Nelze vygenerovat náhled