Odběratelské a dodavatelské smlouvy slouží k automatické fakturaci v pravidelných, popř. i nepravidelných intervalech na základě využívání nebo poskytování služeb.
Smlouvy je možné pomocí REST API generovat či také valorizovat. V tomto návodu se podíváme jak smlouvy pomocí REST API tvořit. Pomocí REST API lze tvořit odběratelské id dodavatelské smlouvy.
Způsob volání
Tvorbu smlouvy je možné zajistit HTTP metodu: PUT nebo POST.
Jsou podporovány výstupní formáty: XML nebo JSON.
Evidence je dostupná na adresách:
/c/{firma}/smlouva/properties - pro odběratelské smlouvy
/c/{firma}/dodavatelska-smlouva/properties pro dodavatelské smlouvy, kde {firma} je databázový identifikátor firmy.
Příklad endpointů na demo firmě:
https://demo.flexibee.eu/c/demo/smlouva.xml
https://demo.flexibee.eu/c/demo/dodavatelska-smlouva.json
Existují další doprovodné evidence, které slouží pro sledování nebo import doprovodných informací:
slouží k definici typu smlouvy, jedná se o předpis smlouvy obdobně jako typ dokladu, který využijeme pro tvorbu reálné smlouvy.
slouží pro evidenci vlastních stavů smluv, například pokud je potřeba na první pohled rozlišit dle nějakého příznaku.
každá smlouva, aby došlo k vygenerování faktury musí mít nadefinovanou položku, který se má generovat do faktury a další specifika týkající se frekvence a data generování faktury. Upozornění: tato evidence je společná pro položky dodavatelských i odběratelských smluv. Položky nelze importovat samostatně bez uvedení hlavičky smlouvy.
slouží pro sledování historie generování faktur ze smluv. Obsahuje informace o uživateli, datu generace, způsobu (manuální/automatická), počty generovaných faktur a případné chyby.
Tělo požadavku
V těle požadavku je nutné uvést hlavičku smlouvy povinné vlastnosti a případně položky smlouvy. Položky smlouvy je možné importovat posléze aktualizací dané smlouvy. Povinná pole při tvorbě hlavičky smlouvy jsou:
kod- číslo smlouvy, max. 20 znakůnazev- název smlouvy, max. 255 znakůsmlouvaOd- zahájení platnosti smlouvy , ve formátu dle dokumentace (obecně nastává okamžikem podpisu smlouvy), platnost v položce smlouvy má přednost.typSml- odkaz na definovaný typ smlouvyfirma- odkaz na adresář firem, firma, ke které se smlouva váže.
Pro úplnost is uvedeme povinné pole položek smluv:
kod- označení položky smlouvy, max. 20 znakůnazev- název položky smlouvy, max. 255 znaků
Upozornění: Další vlastnosti nejsou povinné, nicméně pro správné generování faktur je nutné pole nastavit dle specifik, jak je potřeba faktury generovat. Více informací o nastavení a příkladech generování zjistíte v dokumentaci Odběratelské a dodavatelské smlouvy v praxi.
Výsledek
V případě úspěšné tvorby smlouvy lze kontrolovat HTTP status odpovědi nebo vlastnost success v získaném dokumentu je na hodnotě true.
V případě úspěšného vykonání služby je vracen HTTP status 201 Created a dokument odpovídající standardnímu formátu, viz. návratové hodnoty.
V případě neúspěchu je vracen status 4xx/5xx a zpráva o důvodu neúspěchu.
Ukázky volání
1. volání 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 případě tohoto volání dojde k vytvoření odběratelské smlouvy "Internet na rok výhodně" s předem definovaným typem SMLOUVA pro firmu ABRA, která je platná od 1. 3. 2023.
2. volání 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 případě dojde k tvorbě dodavatelské smlouvy se dvěma položkami "Internet na rok výhodně" s předem definovaným typem SMLOUVA pro firmu ABRA, která je platná od 1. 3. 2023. Faktury se budou generovat s typem dokladu FAKTURA, frekvence fakturace je nastavena 12 měsíců, obrátkový den a měsíc je 31/1, fakturováno dopředu. Položka KONZULTACE je řešena pomocí ceníkové položky, na kterou je odkázáno jejím kódem, odkud jsou automaticky přebrány povinné pole kód a název. Položka INTERNET2023 je vytvořena bez vazby na ceník.
Neúspěšné requesty
1. V případě, že chybí typ smlouvy dojde k chybě 400 Bad Request
<message>Pole 'Typ smlouvy' musí být vyplněno. </message>
2. POZOR: Flexi nijak nehlídá hodnoty v nepovinných vlastnostech jako jsou frekvence fakturace, obrátkový den a měsíc apod. Požadavek projde a výsledkem jsou pak nesmyslné hodnoty, které zabrání generaci:
"frekFakt": 121,
"den": 311,
"mesic": 13
3. V případě, že je zapsán špatně číselníkový údaj, například způsob fakturace dojde k chybě 400 Bad Request:
"message": "zpusobFakt.doprdu není platný kód lokalizovaného číselníku zpusobFakt. [INTERE23]",
FAQ
Příklady zadání smluv
Odběratelské smlouvy v praxi
Jak najít vygenerovanou fakturu ze smlouvy?
Vazba mezi fakturou a smlouvou nevzniká. Z faktury je možné danou smlouvu dohledat pouze podle pole cisSml.
Potřebujete poradit?
V případě dotazů k aplikaci nás kontaktujte na podporaflexi@abra.eu případně prostřednictvím chat okna v pravém dolním rohu.