API ve Vyfakturuj.cz a SimpleShopu

Pokud chcete, aby si s Vyfakturuj.cz nebo SimpleShopem rozuměly i aplikace, pro které nemáme přímé napojení, nebo váš interní systém, můžete vyzkoušet propojení pomocí API. Váš programátor vám takové propojení může vytvořit přímo na míru právě pomocí rozhraní API.

POZN.: Dostupnost API ve vašem tarifu si ověříte v ceníku Vyfakturuj.cz. V SimpleShopu je API dostupné bez omezení.

Co je to API?

API je zkratka pro Application Programming Interface neboli česky rozhraní pro programování aplikací. Jde o rozhraní, pomocí kterého mohou různé aplikace komunikovat mezi sebou a vyměňovat si navzájem data.

API můžete použít pro propojení Vyfakturuj.cz s vaším e-shopem nebo také pro propojení obou našich systémů s platformou Make. Dále pak pro propojení s aplikacemi, na které nemáme přímé napojení (jako jsou např. různé interní systémy). API umožňuje vytvoření napojení na jakoukoliv jinou aplikaci, která má také své API rozhraní.

POZN.: Propojení Vyfakturuj.cz nebo SimpleShopu s nějakou další aplikací pomocí API vám vytvoří váš programátor. Nemáte-li k dispozici svého programátora, můžete využít některého z námi prověřených kontaktů.

Propojovací údaje

K ověření přístupu do vašeho účtu Vyfakturuj.cz nebo SimpleShopu se při zaslání jakéhokoliv požadavku přes API provádí ověření propojovacích údajů. Technicky jde o standardní Basic access authentication, nicméně další podrobnosti uvádí naše dokumentace.

Jako přihlašovací jméno je použit přihlašovací e-mail uživatele. Jako heslo použijte API klíč, který najdete ve svém účtu v sekci Nastavení → Napojení → API.

Dokumentace API

Každé rozhraní API je definováno dokumentací, která popisuje, co vše Vyfakturuj.cz a SimpleShop ve spojení s dalšími aplikacemi umí. Dokumentace naleznete na následujících odkazech.

• Dokumentace API Vyfakturuj.cz
• Dokumentace API SimpleShop

V dokumentaci najdete přehled dostupných akcí, seznam používaných proměnných i konkrétní příklady práce s našimi aplikacemi pomocí API.

Deprecated funkce a parametry

Nedílnou součástí dokumentace je také sekce označená jako Deprecated. Jde o zastaralé funkce a parametry, jejichž podpora bude v budoucnu ukončena. Sekce obsahuje vždy zastaralou variantu i její správný ekvivalent.

Newsletter s novinkami ohledně API

Pro všechny vývojáře a developery využívající naše API je k dispozici nepravidelná rozesílka novinek v našem API. V těchto newsletterech informujeme o změnách v API a významnějších nových funkcích. Stejně tak v případě, že dochází k ukončení podpory nějaké zastaralé funkce nebo parametru.

K rozesílce se přihlásíte na následujících odkazech.

• Registrace k odběru novinek API Vyfakturuj.cz
• Registrace k odběru novinek API SimpleShop

Nejčastější dotazy

Níže blíže rozvádíme konkrétní parametry nebo funkce, na které se nás často ptáte.

Proměnná flags

Parametr flags je bitovým součtem – skládá se z mocnin dvou. V programování je bitový součet běžným konstruktem. Výsledná hodnota flagu (štítku) je dána součtem všech mocnin dvojky, které se v čísle nachází při rozkladu na součet.

PŘÍKLAD: Číslo 15 můžeme rozložit jako 2³ +  2² + 2¹ + 2⁰ = 8 + 4 + 2 + 1.

Každá z mocnin má své vysvětlení. V dokumentaci jsou uvedeny jen ty potřebné pro práci s doklady přes API. Chybějící mocniny používá náš systém interně a slouží pro usnadnění práce našim vývojářům.

PŘÍKLAD: Pokud má doklad proměnnou flags rovnou 7, jedná se o doklad, který obsahuje DPH (2⁰ = 1) + je uhrazený (2¹ = 2) + byl odeslán zákazníkovi (2² = 4).

Export objednávek Kdo koupil (pouze SimpleShop)

Pro každý produkt v SimpleShopu je možné stáhnout seznam všech objednávek v exportu Kdo koupil. Tato možnost se nabízí i přes API.

Export je ve formátu JSON, ve kterém je zabalen CSV soubor. Data jsou vždy kódována v UTF-8 (znaková sada Unicode (UTF-8)).

Příklad práce s exportem najdete v naší dokumentaci.

Odesílání volitelné přílohy e-mailem

Společně s fakturou je možné přes API odeslat také volitelnou přílohu e-mailem. Jedná se o proměnnou additionalAttachments, která je k dispozici pro akci odeslání faktury e-mailem.

Proměnná je typu pole a obsahuje dva parametry (typu string):

• parametr filename – obsahuje informaci o tom, jaký název má mít soubor v zaslaném e-mailu (včetně koncovky)
• parametr data – obsahuje již přímo odesílaný soubor o max. velikosti 5 MB zakódovaný do base64 

Odeslání e-mailu s fakturou včetně volitelné přílohy může vypadat například následovně:

{
  "type": 1,
  "to": "demo@vyfakturuj.cz",
  "pdfAttachment": true,
  "additionalAttachments": [
    {
      "filename": "muj-soubor.doc",
      "data": "UG96ZHJhdg=="
    }
  ]
}