Odběratelské a dodavatelské smlouvy slouží k automatické fakturaci v pravidelných, případně i nepravidelných intervalech na základě využívání nebo poskytování služeb.

Ze smluv lze přes REST API generovat faktury a smlouvy lze také valorizovat. V tomto návodu se podíváme na to, jak smlouvy — odběratelské i dodavatelské — přes REST API tvořit.

Způsob volání

Smlouvu vytvoříte HTTP metodou PUT nebo POST; podporované výstupní formáty jsou XML a JSON.

POST https://demo.flexibee.eu/c/demo/smlouva.xml
POST https://demo.flexibee.eu/c/demo/dodavatelska-smlouva.json

Evidence smlouva nese odběratelské smlouvy, evidence dodavatelska-smlouva dodavatelské. Segment {firma} v adrese je databázový identifikátor firmy.

Doprovodné evidence

Kolem smluv existují další evidence, které slouží pro sledování nebo import doprovodných informací:

Evidence	K čemu slouží
typ-smlouvy, dodavatelsky-typ-smlouvy	Definice typu smlouvy — předpis, ze kterého reálná smlouva vychází, obdobně jako typ dokladu.
stav-smlouvy	Evidence vlastních stavů smluv — například když potřebujete smlouvy na první pohled rozlišit podle nějakého příznaku.
smlouva-polozka	Položky smluv. Aby se ze smlouvy vygenerovala faktura, musí mít smlouva alespoň jednu položku s tím, co se má fakturovat, a se specifiky frekvence a data generování.
smlouva-zurnal	Historie generování faktur ze smluv — uživatel, datum generace, způsob (manuální či automatický), počty vygenerovaných faktur a případné chyby.

⚠️ Evidence smlouva-polozka je společná pro položky odběratelských i dodavatelských smluv a nelze do ní importovat samostatně — bez hlavičky smlouvy vrací požadavek 400 s kódem importNotAllowed a hlášením Import není povolen. Položky proto posílejte vnořené do smlouvy, ať už při jejím vytvoření, nebo pozdější aktualizací.

Tělo požadavku

V těle požadavku uveďte hlavičku smlouvy s povinnými vlastnostmi a případně její položky:

Vlastnost	Význam
`kod`	Číslo smlouvy, max. 20 znaků.
`nazev`	Název smlouvy, max. 255 znaků.
`smlouvaOd`	Zahájení platnosti smlouvy ve formátu data — obecně nastává okamžikem podpisu smlouvy. Platnost uvedená na položce smlouvy má přednost.
`typSml`	Odkaz na definovaný typ smlouvy.
`firma`	Odkaz do adresáře — firma, ke které se smlouva váže.

U položek smlouvy jsou povinné kod (označení, max. 20 znaků) a nazev (max. 255 znaků). Odkážete-li položku na ceníkovou položku elementem cenik, přebere se kód i název z ceníku a uvádět je nemusíte.

⚠️ Ostatní vlastnosti povinné nejsou, pro správné generování faktur je ale nutné je nastavit podle toho, jak potřebujete fakturovat. Více o nastavení a příkladech najdete v článku Odběratelské smlouvy v praxi.

Výsledek

Úspěch poznáte z HTTP statusu nebo z vlastnosti success v odpovědi. Při úspěšném vytvoření je vracen status 201 Created a dokument ve standardním formátu, viz návratové hodnoty. Při neúspěchu je vracen status 4xx nebo 5xx a zpráva o důvodu.

Ukázky volání

Odběratelská smlouva v XML

POST https://demo.flexibee.eu/c/demo/smlouva.xml

<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>

Tímto voláním vznikne odběratelská smlouva „Internet na rok výhodně" s předem definovaným typem SMLOUVA pro firmu ABRA, platná od 1. 3. 2023.

Dodavatelská smlouva s položkami v JSON

PUT https://demo.flexibee.eu/c/demo/dodavatelska-smlouva.json

{
    "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"
                    }
                ]
            }
        }
    }
}

Zde vznikne dodavatelská smlouva se dvěma položkami. Faktury se budou generovat s typem dokladu FAKTURA, frekvence fakturace je 12 měsíců, obrátkový den a měsíc 31/1 a fakturuje se dopředu. Položka KONZULTACE je řešena odkazem na ceníkovou položku, odkud se automaticky přeberou povinné kód a název; položka INTERNET2023 je vytvořena bez vazby na ceník.

Vlastnost zpusFaktK přijímá hodnoty zpusobFakt.dopredu (Fakturovat dopředu) a zpusobFakt.zpetne (Fakturovat zpětně).

Neúspěšné požadavky

Situace	Odpověď
Chybí typ smlouvy	`400`, `validace.notNull` — Pole 'Typ smlouvy' musí být vyplněno.
Položka bez vazby na ceník a bez názvu	`400`, `validace.notNull` — Pole 'Název' musí být vyplněno.
Špatně zapsaný číselníkový údaj, například způsob fakturace	`400`, `importXmlNeplatnyCiselnik` — zpusobFakt.doprdu není platný kód lokalizovaného číselníku zpusobFakt.
Import samostatné položky bez hlavičky smlouvy	`400`, `importNotAllowed` — Import není povolen.

🚨 Nepovinné vlastnosti jako frekvence fakturace nebo obrátkový den a měsíc Flexi nijak nehlídá. Požadavek s hodnotami "frekFakt": 121, "den": 311 nebo "mesic": 13 projde bez chyby, ale výsledkem jsou nesmyslné hodnoty, které pak zabrání generování faktur.

FAQ

Jak najdu fakturu vygenerovanou ze smlouvy?

Vygenerovaná faktura nese číslo smlouvy v textové vlastnosti cisSml i vazbu smlouva, takže faktury dané smlouvy lze přímo vyfiltrovat:

GET https://demo.flexibee.eu/c/demo/faktura-vydana/(smlouva='code:45644').json

Kde najdu příklady zadání smluv?

Videotutoriál a příklady zadání najdete v článku Odběratelské a dodavatelské smlouvy, širší souvislosti pak v sérii Odběratelské smlouvy v praxi.

Jak zjistím, zda a kdy se ze smlouvy generovalo?

Historii najdete v evidenci smlouva-zurnal — obsahuje uživatele, datum, způsob generování, počty faktur i případné chyby.

Související

Související články

Smlouvy v API