Odberateľské a dodávateľské zmluvy slúžia na automatickú fakturáciu v pravidelných, príp. aj nepravidelných intervaloch na základe využívania alebo poskytovania služieb.
Zmluvy je možné pomocou REST API generovať alebo aj valorizovať. V tomto návode sa pozrieme, ako zmluvy pomocou REST API vytvárať. Pomocou REST API je možné vytvárať odberateľské aj dodávateľské zmluvy.
Spôsob volania
Tvorbu zmluvy je možné zabezpečiť HTTP metódou: PUT alebo POST.
Sú podporované výstupné formáty: XML alebo JSON.
Evidencia je dostupná na adresách:
/c/{firma}/smlouva/properties - pre odberateľské zmluvy
/c/{firma}/dodavatelska-smlouva/properties pre dodávateľské zmluvy, kde {firma} je databázový identifikátor firmy.
Príklad endpointov na demo firme:
Existujú ďalšie sprievodné evidencie, ktoré slúžia na sledovanie alebo import sprievodných informácií:
slúži na definíciu typu zmluvy, ide o predpis zmluvy obdobne ako typ dokladu, ktorý využijeme na tvorbu reálnej zmluvy.
slúži na evidenciu vlastných stavov zmlúv, napríklad ak je potrebné na prvý pohľad rozlíšiť podľa nejakého príznaku.
každá zmluva, aby došlo k vygenerovaniu faktúry, musí mať nadefinovanú položku, ktorá sa má generovať do faktúry, a ďalšie špecifiká týkajúce sa frekvencie a dátumu generovania faktúry. Upozornenie: táto evidencia je spoločná pre položky dodávateľských aj odberateľských zmlúv. Položky nie je možné importovať samostatne bez uvedenia hlavičky zmluvy.
slúži na sledovanie histórie generovania faktúr zo zmlúv. Obsahuje informácie o používateľovi, dátume generácie, spôsobe (manuálna/automatická), počtoch generovaných faktúr a prípadných chybách.
Telo požiadavky
V tele požiadavky je nutné uviesť hlavičku zmluvy, povinné vlastnosti a prípadne položky zmluvy. Položky zmluvy je možné importovať následne aktualizáciou danej zmluvy. Povinné polia pri tvorbe hlavičky zmluvy sú:
kod- číslo zmluvy, max. 20 znakovnazev- názov zmluvy, max. 255 znakovsmlouvaOd- začiatok platnosti zmluvy, vo formáte podľa dokumentácie (všeobecne nastáva okamihom podpisu zmluvy), platnosť v položke zmluvy má prednosť.typSml- odkaz na definovaný typ zmluvyfirma- odkaz na adresár firiem, firma, ku ktorej sa zmluva viaže.
Pre úplnosť uvádzame aj povinné polia položiek zmlúv:
kod- označenie položky zmluvy, max. 20 znakovnazev- názov položky zmluvy, max. 255 znakov
Upozornenie: Ďalšie vlastnosti nie sú povinné, avšak pre správne generovanie faktúr je nutné polia nastaviť podľa špecifík, ako je potrebné faktúry generovať. Viac informácií o nastavení a príkladoch generovania nájdete v dokumentácii Odberateľské a dodávateľské zmluvy v praxi.
Výsledok
V prípade úspešnej tvorby zmluvy je možné skontrolovať HTTP status odpovede alebo vlastnosť success v získanom dokumente, ktorá má hodnotu true.
V prípade úspešného vykonania služby je vrátený HTTP status 201 Created a dokument zodpovedajúci štandardnému formátu, viď návratové hodnoty.
V prípade neúspechu je vrátený status 4xx/5xx a správa o dôvode neúspechu.
Ukážky volania
1. volanie v XML
POST https://demo.flexibee.eu/c/demo/smlouva.xml
Tělo:
<winstrom>
<smlouva>
<kod>INTERNETROK23</kod>
<nazev>Internet na rok výhodně</nazev>
<smlouvaOd>2023-03-01</smlouvaOd>
<typSml>code:SMLOUVA</typSml>
<firma>code:ABRA</firma>
</smlouva>
</winstrom>
V prípade tohto volania dôjde k vytvoreniu odberateľskej zmluvy „Internet na rok výhodne" s vopred definovaným typom SMLOUVA pre firmu ABRA, ktorá je platná od 1. 3. 2023.
2. volanie v JSON:
PUT https://demo.flexibee.eu/c/demo/dodavatelska-smlouva.json
Tělo:
{
"winstrom": {
"dodavatelska-smlouva": {
"kod": "INTERNETROK23",
"nazev": "Internet na rok výhodně",
"smlouvaOd": "2023-03-01",
"typSml": "code:SMLOUVA",
"firma": "code:ABRA",
"frekFakt": 12,
"den": 31,
"mesic": 1,
"zpusFaktK": "zpusobFakt.dopredu",
"typDoklFak": "code:FAKTURA",
"polozkySmlouvy": {
"smlouva-polozka": [
{
"kod": "INTERNET2023",
"nazev": "Internet výhodně 2023"
},
{
"cenik": "code:KONZULTACE"
}
]
}
}
}
}
V tomto prípade dôjde k tvorbe dodávateľskej zmluvy s dvoma položkami „Internet na rok výhodne" s vopred definovaným typom SMLOUVA pre firmu ABRA, ktorá je platná od 1. 3. 2023. Faktúry sa budú generovať s typom dokladu FAKTURA, frekvencia fakturácie je nastavená na 12 mesiacov, obrátkový deň a mesiac je 31/1, fakturované vopred. Položka KONZULTACE je riešená pomocou cenníkovej položky, na ktorú je odkazované jej kódom, odkiaľ sú automaticky prevzaté povinné polia kód a názov. Položka INTERNET2023 je vytvorená bez väzby na cenník.
Neúspešné requesty
1. V prípade, že chýba typ zmluvy, dôjde k chybe 400 Bad Request
<message>Pole 'Typ smlouvy' musí být vyplněno. </message>
2. POZOR: Flexi nijako nekontroluje hodnoty v nepovinných vlastnostiach, ako sú frekvencia fakturácie, obrátkový deň a mesiac a pod. Požiadavka prejde a výsledkom sú potom nezmyselné hodnoty, ktoré zabrania generácii:
"frekFakt": 121,
"den": 311,
"mesic": 13
3. V prípade, že je nesprávne zadaný číselníkový údaj, napríklad spôsob fakturácie, dôjde k chybe 400 Bad Request:
"message": "zpusobFakt.doprdu není platný kód lokalizovaného číselníku zpusobFakt. [INTERE23]",
FAQ
Príklady zadania zmlúv
Odberateľské zmluvy v praxi
Ako nájsť vygenerovanú faktúru zo zmluvy?
Väzba medzi faktúrou a zmluvou nevzniká. Z faktúry je možné danú zmluvu dohľadať iba podľa poľa cisSml.
Potrebujete poradiť?
V prípade otázok k aplikácii nás kontaktujte na podporaflexi@abra.eu prípadne prostredníctvom okna chatu v pravom dolnom rohu.