vasdoklad.cz
Bře 19 2020
Off

1 Úvod

HTTP REST API služby VášDoklad.cz je založeno na výměně JSON dokumentu mezi klientem a serverem, s výjimkou operací uploadu souborů obrázků, certifikátů a klíčů. Server na základě takto předaných dat poskytuje odpověď. Pro testování lze použít nástroj stejnojmenné knihovny: curl.

2 Uživatel

Operace spojené s uživatelským účtem řeší samostatná specifikace REST API služby https://cloud.4smart.cz. Uživatelský účet entita sdílená mezi službami VášDoklad.cz a cloud.4smart.cz spolu s veškerým nastavením.

HTTP REST API služby cloud.4smart.cz:

https://cloud.4smart.cz/specifikace_rest_api.pdf

Pro generování dokladů v e-shopu nebo jiné online službě není třeba odkazovaný dokument studovat. Postačí vytvoření účtu s pomocí aplikace.vasdoklad.cz a následně implementace vybraných níže uvedených funkcí podle tohoto dokumentu.

2.1 Získání informací o aktuálním tarifu uživatele

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/tariff-get.json

Metoda: POST

Odesílaný dotaz v JSON:

 {
     "login": "uzivatelsky-login",
     "password": "uzivatelske-heslo"
  }

Příklad odpovědi:

{„tariff“: 3}

2.2 Přepnutí tarifu

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/tariff-switch.json

Metoda: POST

Odesílaný dotaz v JSON:

 {
     "login": "uzivatelsky-login",
     "password": "uzivatelske-heslo",
     „tariff“: „3“
  }

Odpověď serveru: stavový kód 200 při úspěchu, nebo jiný.

3 Operace s adresářem Dodavatele / Provozovny

O tom, zda jde o provozovnu nebo dodavatele rozhoduje kontext ukládaných dat.

3.1 Získání seznamu dodavatelů / provozoven

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/list-suppliers.json

Metoda: POST

Odesílaný dotaz v JSON:

 {
     "login": "uzivatelsky-login",
     "password": "uzivatelske-heslo",
     "id": "50"
  }

Pozn.: Pokud není uveden atribut id spolu s hodnotou, je vrácen seznam všech provozoven / dodavatelů. Je-li uvedeno id, jsou vráceny pouze informace o konkrétní provozovně / dodavateli reprezentované tímto interním číslem.

Příklad odpovědi:

 {
 "50": {
 "logo": true,  
 "advertisement": true,  
 "company": "Spolecnost s.r.o.",  
 "addr_1": "Novákova 12",  
 "addr_2": "Vy\u0161kov",  
 "postal": "123 45",  
 "ic": "01234567",  
 "dic": "CZ01234567",  
 "phone": "+420 910 111 426",  
 "web": "https://it-techcz.com",  
 "email": "kontakt@it-techcz.com",  
 "bank_name": "Komer\u010dn\u00ed banka a.s.",  
 "bank_account": "115-3474420297/0100",  
 "bank_iban": "CZ90 0100 0001 1534 7442 0297",  
 "bank_swift": "KOMBCZPP",  
 "tax_payer": 0,  
 "additional_comment_1": "Spolecnost s.r.o. 
 se s\u00eddlem Novákova 12, 123 45 Pustim\u011b\u0159, je zaps\u00e1na v obchodn\u00edm rejst\u0159\u00edku, veden\u00e9m u Krajsk\u00e9ho soudu v Brn\u011b, odd\u00
 edl C, vlo\u017eka 95878.",  
 "additional_comment_2": "Dovolujeme si V\u00e1s upozornit, \u017ee v p\u0159\u00edpad\u011b nedodr\u017een\u00ed data splatnosti uveden\u
 00e9ho na faktu\u0159e V\u00e1m budeme \u00fa\u010dtovat \u00farok z prodlen\u00ed v dohodnut\u00e9, resp. z\u00e1konn\u00e9 v\u00fd\u0161i",  
 "additional_comment_3": "a smluvn\u00ed pokutu (byla-li ujedn\u00e1na)"
 }
 }

3.2 Odstranění dodavatele / provozovny

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/remove-supplier.json

Metoda: POST

Odesílaný dotaz v JSON:

 {
     "login": "uzivatelsky-login",
     "password": "uzivatelske-heslo",
     "id": "50"
  }

Pozn.: Parametr id je povinný.

Odpověď serveru: stavový kód 200 při úspěchu, nebo jiný.

3.3 Import dodavatele / provozovny

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/import-supplier.json

Metoda: POST

Odesílaný dotaz v JSON:

{ 
     "login": "uzivatelsky-login", 
     "password": "uzivatelske-heslo", 
     "supplier": { 
         "company": "Spolecnost s.r.o.", 
         "addr_1": "Novákova 12", 
         "addr_2": "Vyškov", 
         "postal": "123 45", 
         "ic": "01234567", 
         "dic": "CZ1212121218", 
         "phone": "+420 910 111 426", 
         "web": "https://it-techcz.com", 
         "email": "kontakt@it-techcz.com", 
         "bank_name": "Komerční banka Kč", 
         "bank_account": "115-3474420297/0100",  
         "bank_iban": "cz90 0100 0001 1534 7442 0297", 
         "bank_swift": "KOMBCZPP", 
         "tax_payer": false, 
         "additional_comment_1": "Spolecnost s.r.o. se sídlem Novákova 12, 123 45 Pustiměř, je zapsána v obchodním rejstříku, vedeném u Krajského soudu v Brně, oddíl C
  , vložka 95878.", 
         "additional_comment_2": "Dovolujeme si Vás upozornit, že v případě nedodržení data splatnosti uvedeného na faktuře Vám budeme účtovat úrok z prodlení v dohod
  nuté, resp. zákonné výši", 
         "additional_comment_3": "a smluvní pokutu (byla-li ujednána)." 
     } 
  }

Odpověď serveru: stavový kód 200 při úspěchu, nebo jiný.

Povinné položky: login, password, supplier, company, addr_1, addr_2, postal, ic, dic, tax_payer.

3.4 Aktualizace existujícího dodavatele / provozovny

Aktualizace položky dodavatele / provozovny v adresáři se provádí stejným postupem jako její vytvoření. V JSON dokumentu, který klient odesílá na server musí být navíc uveden atribut id aktualizované položky.

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/import-supplier.json

Metoda: POST

Odesílaný dotaz v JSON:

 { 
    "login": "uzivatelsky-login", 
    "password": "uzivatelské-heslo", 
    „ id“: „50“,
    "supplier": {  
             …
     }
 }

Odpověď serveru: stavový kód 200 nebo jiný při neúspěchu.

Povinné položky: login, password, supplier, company, addr_1, addr_2, postal, ic, dic, tax_payer.

3.5 Upload souboru loga dodavatele / provozovny

Velikost souboru je omezena na 2MB. Doporučené rozměry obrázku jsou 547×240 px. Povolený formát obrázku je png, jpg. Kromě binárních dat obrázku se neodesílá žádný JSON dokument.

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/upload-logo.json

Metoda: PUT

Povinné parametry: login, heslo, id (provozovny).

Příklad akce:

curl -F’login=uzivatelsky-login’ -F’password=uzivatelske-heslo’ -F’id=50′ -F’file=@./soubor.png’ -X PUT https://aplikace.vasdoklad.cz/v1/vasdoklad.cz/upload-logo.json


3.6 Upload reklamního banneru dodavatele / provozovny

Velikost souboru je omezena na 2MB. Doporučené rozměry obrázku jsou 420×120 px. Povolený formát obrázku je png, jpg. Kromě binárních dat se neodesílá žádný JSON dokument.

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/upload-ad.json

Metoda: PUT

Povinné parametry: login, heslo, id (provozovny).

Příklad akce:

curl -F’login=uzivatelsky-login’ -F’password=uzivatelske-heslo’ -F’id=50′ -F’file=@./soubor.png’ -X PUT https://aplikace.vasdoklad.cz/v1/vasdoklad.cz/upload-ad.json

4 Operace s adresářem Pokladen

Platí, že dodavatel / provozovna může disponovat 0 – n pokladnami (podle platného tarifu).

4.1 Získání seznamu pokladen

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/list-cashdesks.json

Metoda: POST

Odesílaný dotaz v JSON:

 {
     "login": "uzivatelsky-login",
     "password": "uzivatelske-heslo",
     "id": "50",
     „cdid“: „58“
 }

Pozn.: Atribut id reprezentuje provozovnu/dodavatele. Atribut cdid reprezentuje pokladnu. Pokud není uveden atribut cdid spolu s hodnotou, je vrácen seznam všech pokladen dodavatele/provozovny. Je-li uvedeno cdid, jsou vráceny pouze informace o konkrétní pokladně reprezentované tímto interním číslem.

Příklad odpovědi:

 {
 "58": {
   "est_id": 50,  
   "eet_do": 0,  
   "eet_cert_path": "defined",  
   "eet_cert_pass": "defined",  
   "eet_provozovna": 14,  
   "eet_pokladna": "Vasdoklad.cz",  
   "eet_playground": 1,
   "signing_cert_path": "defined",  
   "signing_key_path": "defined",  
   "signing_passwd": "defined"
   } 
 }

4.2 Odstranění pokladny

Odstraněním pokladny dochází ke smazání všech přiřazených souborů.

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/remove-cashdesk.json

Metoda: POST

Odesílaný dotaz v JSON:

 {
     "login": "uzivatelsky-login",
     "password": "uzivatelske-heslo",
     "id": "58"
 }

Atribut id reprezentuje interní číslo pokladny.

Odpověď serveru: stavový kód 200 při úspěchu, nebo jiný.

4.3 Vytvoření nové pokladny

Operace vytvoření pokladny vytváří novou neinicializovanou entitu.

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/import-cashdesk.json

Metoda: POST

Odesílaný dotaz v JSON:

 {
     "login": "uzivatelsky-login",
     "password": "uzivatelske-heslo",
     "id": "50"
 }

Atribut id reprezentuje interní číslo provozovny / dodavatele ve které má být nová pokladna vytvořena.

Odpověď serveru: stavový kód 200 při úspěchu, nebo jiný.

4.4 Změna nastavení existující pokladny

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/update-cashdesk.json

Metoda: POST

Odesílaný dotaz v JSON:

{ 
     "login": "uzivatelsky-login", 
     "password": "uzivatelske-heslo", 
     "id": "58", 
     "cashdesk":{ 
        "eet_cert_pass": "heslo-certifikatu-eet", 
        "eet_provozovna": "14", 
        "eet_pokladna": "vasdoklad.cz", 
        "eet_playground": true, 
        "eet_do": false, 
        "signing_passwd": "heslo-kvalifikovaneho-certifikatu" 
     } 
  }

Atribut id reprezentuje interní číslo pokladny.

Odpověď serveru: stavový kód 200 při úspěchu, nebo jiný.

4.5 Upload EET certifikátu pokladny

Touto akcí dojde k nahrání certifikátu pro elektronickou evidenci tržeb do nastavení existující pokladny. Velikost souboru je omezena na 2MB. Povolený formát souboru je p12. Kromě binárních dat se neodesílá žádný JSON dokument.

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/upload-eetcert.json

Metoda: PUT

Povinné parametry: login, heslo, id (pokladny).

Příklad akce:

curl -F’login=uzivatelsky-login’ -F’password=uzivatelske-heslo’ -F’id=58′ -F’file=@./soubor.p12′ -X PUT https://aplikace.vasdoklad.cz/v1/vasdoklad.cz/upload-eetcert.json

4.6 Odstranění EET certifikátu pokladny

Touto akcí dojde ke smazání souboru s certifikátem, který je přiřazen k existující pokladně.

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/remove-eetcert.json

Metoda: POST

Odesílaný dotaz v JSON:

 {
     "login": "uzivatelsky-login",
     "password": "uzivatelske-heslo",
     "id": "58"
 }

Atribut id reprezentuje interní číslo pokladny.

Odpověď serveru: stavový kód 200 při úspěchu, nebo jiný.

4.7 Upload kvalifikovaného certifikátu pokladny

Kvalifikovaný certifikát slouží k elektronickému podepisování vystavovaných dokladů. Touto akcí dojde k nahrání certifikátu do nastavení existující pokladny. Velikost souboru je omezena na 2MB. Povolený formát souboru je pem. Kromě binárních dat se neodesílá žádný JSON dokument.

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/upload-qcert.json

Metoda: PUT

Povinné parametry: login, heslo, id (pokladny).

Příklad akce:

curl -F’login=uzivatelsky-login’ -F’password=uzivatelske-heslo’ -F’id=58′ -F’file=@./soubor.pem’ -X PUT https://aplikace.vasdoklad.cz/v1/vasdoklad.cz/upload-qcert.json

4.8 Odstranění kvalifikovaného certifikátu pokladny

Touto akcí dojde ke smazání souboru s certifikátem, který je přiřazen k existující pokladně.

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/remove-qcert.json

Metoda: POST

Odesílaný dotaz v JSON:

 {
     "login": "uzivatelsky-login",
     "password": "uzivatelske-heslo",
     "id": "58"
 }

Atribut id reprezentuje interní číslo pokladny.

Odpověď serveru: stavový kód 200 při úspěchu, nebo jiný.

4.9 Upload klíče kvalifikovaného certifikátu pokladny

Klíč ke kvalifikovanému certifikátu slouží k elektronickému podepisování vystavovaných dokladů. Touto akcí dojde k nahrání klíče do nastavení existující pokladny. Velikost souboru je omezena na 2MB. Povolený formát souboru je pem. Kromě binárních dat se neodesílá žádný JSON dokument.

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/upload-qkey.json

Metoda: PUT

Povinné parametry: login, heslo, id (pokladny).

Příklad akce:

curl -F’login=uzivatelsky-login’ -F’password=uzivatelske-heslo’ -F’id=58′ -F’file=@./soubor.pem’ -X PUT https://aplikace.vasdoklad.cz/v1/vasdoklad.cz/upload-qkey.json

4.10 Odstranění klíče kvalifikovaného certifikátu pokladny

Touto akcí dojde ke smazání souboru s klíčem, který je přiřazen k existující pokladně.

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/remove-qkey.json

Metoda: POST

Odesílaný dotaz v JSON:

 {
     "login": "uzivatelsky-login",
     "password": "uzivatelske-heslo",
     "id": "58"
 }

Atribut id reprezentuje interní číslo pokladny.

Odpověď serveru: stavový kód 200 při úspěchu, nebo jiný.

5 Operace s adresářem Odběratelů

5.1 Získání seznamu odběratelů

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/list-customers.json

Metoda: POST

Odesílaný dotaz v JSON:

 {
     "login": "uzivatelsky-login",
     "password": "uzivatelske-heslo",
     "id": "50"
 }

Pozn.: Pokud není uveden atribut id spolu s hodnotou, je vrácen seznam všech odběratelů. Je-li uvedeno id, jsou vráceny pouze informace o konkrétním odběrateli, kterého reprezentuje toto interní číslo.

Příklad odpovědi:

 {
   "50": {
   "company": "Spolecnost s.r.o.",  
   "addr_1": "Novákova 12", "addr_2": "Vy\u0161kov", 
   "country": "\u010cesk\u00e1 Republika",  
   "postal": "123 45",  
   "ic": "01234567", 
   "dic": "CZ1212121218", 
   "phone": "+420 910 111 426",  
   "email": "kontakt@it-techcz.com"
   }
 }

5.2 Odstranění odběratele

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/remove-customer.json

Metoda: POST

Odesílaný dotaz v JSON:

 {
     "login": "uzivatelsky-login",
     "password": "uzivatelske-heslo",
     "id": "50"
 }

Pozn.: Parametr id je povinný.

Odpověď serveru: stavový kód 200 při úspěchu, nebo jiný.

5.3 Vytvoření odběratele

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/import-customer.json

Metoda: POST

Odesílaný dotaz v JSON:

{ 
     "login": "uzivatelsky-login", 
     "password": "uzivatelske-heslo", 
     "customer": { 
         "company": "Spolecnost s.r.o.", 
         "addr_1": "Novákova 12", 
         "addr_2": "Vyškov", 
         "postal": "123 45", 
         "ic": "01234567", 
         "dic": "CZ1212121218", 
         "phone": "+420 910 111 426", 
         "email": "kontakt@it-techcz.com", 
         "country":"Česká Republika" 
     } 
  }

Odpověď serveru: stavový kód 200 při úspěchu, nebo jiný.

5.4 Aktualizace položky odběratele

Odběratele lze v adresáři aktualizovat stejným přístupem, jako je postup pro jeho vytvoření. Navíc je nutné uvádět v odesílaném JSON dokumentu atribut id, čímž se operace odliší od vytvoření nové položky v adresáři.

Url: https://aplikace.vasdoklad.cz/v1/basdoklad.cz/import-customer.json

Metoda: POST

Odesílaný dotaz v JSON:

 { 
    "login": "uzivatelsky-login", 
    "password": "uzivatelske-heslo", 
    „id“: „50“,
    "customer": { 
       ...
    } 
 }

Odpověď serveru: stavový kód 200 při úspěchu, nebo jiný.

6 Generování dokumentu dokladu

Při generování dokladu lze volitelně uplatnit adresáře dodavatelů / provozoven, pokladen a odběratelů. Použití adresáře dodavatelů/provozoven umožňuje uplatnit vlastní logo nebo reklamu. Použití adresáře pokladen dovoluje provádět elektronickou evidenci tržeb a podepisování dokladů kvalifikovaným certifikátem.

6.1 Ukázka generování dokladu bez použití adresářů

Tento přístup nedovoluje vkládat do generovaného dokladu grafické logo, reklamu, podepisovat doklad kvalifikovaným certifikátem a provádět EET.

{ 
     "login": "uzivatelsky-login", 
     "password": "uzivatelske-heslo", 
     "archive": true, 
     "explicitHeader": "", 
     "invoice_id": "0200100021", 
     "varsymbol": "358857018", 
     "konstsymbol": "0308", 
     "ordernum": "", 
     "orderdate": "", 
     "date_issue": "20.1.2020", 
     "date_maturity": "20.1.2020", 
     "date_payment_realisation_tax": "20.1.2020", 
     "date_payment_received": "", 
     "paymethod": "Hotovost", 
     "revcharge": false, 
     "currency": "CZK", 
     "course": "", 
     "payed": false, 
     "overview": false, 
     "sign_by_certificate": "", 
     "eet": "", 
     "supplier": { 
         "company": "Spolecnost s.r.o.", 
         "addr_1": "Novákova 12", 
         "addr_2": "Vyškov", 
         "postal": "123 45", 
         "ic": "01234567", 
         "dic": "CZ1212121218", 
         "phone": "+420 910 111 426", 
         "web": "https://it-techcz.com", 
         "email": "kontakt@it-techcz.com", 
         "bank_name": "", 
         "bank_account": "",  
         "bank_iban": "", 
         "bank_swift": "", 
         "tax_payer": false 
     }, 
     "customer_login": "kontakt@it-techcz.com", 
     "customer": { 
         "company": "Fiktivní společnost a.s.",  
         "addr_1": "Na Tyršovce 13/30",  
         "addr_2": "Brno",  
         "postal": "533 51",  
         "country": "Czech Republic",  
         "ic": "05577987",  
         "dic": "CZ05522452",  
         "phone": "776351196",  
         "email": "" 
     }, 
     "invoice_comment": "Fakturujeme Vám níže uvedené služby za období 01/2020 dle smlouvy číslo 099/16-2016 (identifikace fakturace 157101):", 
     "additional_comment_1": "Spolecnost s.r.o. se sídlem Novákova 12, 123 45 Pustiměř, je zapsána v obchodním rejstříku, vedeném u Krajského soudu v Brně, oddíl C, vl
  ožka 95878.", 
     "additional_comment_2": "Dovolujeme si Vás upozornit, že v případě nedodržení data splatnosti uvedeného na faktuře Vám budeme účtovat úrok z prodlení v dohodnuté
  , resp. zákonné výši", 
     "additional_comment_3": "a smluvní pokutu (byla-li ujednána).", 
     "items": [ 
         {"subject": "Doučování českého jazyka, 1 hodina", "amount": "1", "unit_price": "300", "tax_percent": "21"}, 
         {"subject": "Doučování českého jazyka, 1 hodina", "amount": "1", "unit_price": "200", "tax_percent": "15"} 
      ] 
  }

6.2 Ukázka generování dokladu s použitím všech adresářů

Pro vystavení dokladu budou použit dodavatel id 50 z adresáře dodavatelů / provozoven a případně jeho grafické logo a reklama, dále pokladna id 8 a odběratel id 13. Je-li v adresáři pokladen u položky id 8 uvedeno platné nastavení pro EET nebo podepisování dokladů, bude použito při vystavení dokladu.

{ 
     "login": "uzivatelsky-login", 
     "password": "uzivatelske-heslo", 
     "archive": true, 
     "explicitHeader": "", 
     "invoice_id": "0200100021", 
     "varsymbol": "358857018", 
     "konstsymbol": "0308", 
     "ordernum": "", 
     "orderdate": "", 
     "date_issue": "20.1.2020", 
     "date_maturity": "20.1.2020", 
     "date_payment_realisation_tax": "20.1.2020", 
     "date_payment_received": "", 
     "paymethod": "Hotovost", 
     "revcharge": false, 
     "currency": "CZK", 
     "course": "", 
     "payed": false, 
     "overview": false, 
     "sign_by_certificate": "8", 
     "eet": "8", 
     "supplier": „50“,
     "customer_login": "kontakt@it-techcz.com", 
     "customer": „13“,
     "invoice_comment": "Fakturujeme Vám níže uvedené služby za období 01/2020 dle smlouvy číslo 099/16-2016 (identifikace fakturace 157101):", 
     "items": [ 
         {"subject": "Doučování českého jazyka, 1 hodina", "amount": "1", "unit_price": "300", "tax_percent": "21"}, 
         {"subject": "Doučování českého jazyka, 1 hodina", "amount": "1", "unit_price": "200", "tax_percent": "15"} 
      ] 
  }

7 Technická podpora

Ve věci implementace služby VášDoklad.cz do Vašich systémů (e-shopů a online služeb) jsme připraveni Vám poskytnout technický support. Kontaktujte nás na email kontakt@it-techcz.com nebo na telefonním čísle 910 111 426.

Publikováno vČlánky Novinky VášDoklad.cz