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.

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á taktéž má své API rozhraní.

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 → Nastavení (sekce 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 5MB 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=="
    }
  ]
}