Odberateľské a dodávateľské zmluvy slúžia na automatickú fakturáciu v pravidelných, prípadne aj nepravidelných intervaloch na základe využívania alebo poskytovania služieb.

Zo zmlúv je možné cez REST API generovať faktúry a zmluvy je možné aj valorizovať. V tomto návode sa pozrieme na to, ako zmluvy — odberateľské aj dodávateľské — cez REST API vytvárať.

Spôsob volania

Zmluvu vytvoríte HTTP metódou PUT alebo POST; podporované výstupné formáty sú XML a JSON.

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

Evidencia smlouva nesie odberateľské zmluvy, evidencia dodavatelska-smlouva dodávateľské. Segment {firma} v adrese je databázový identifikátor firmy.

Sprievodné evidencie

Okolo zmlúv existujú ďalšie evidencie, ktoré slúžia na sledovanie alebo import sprievodných informácií:

Evidencia	Na čo slúži
typ-smlouvy, dodavatelsky-typ-smlouvy	Definícia typu zmluvy — predpis, z ktorého reálna zmluva vychádza, obdobne ako typ dokladu.
stav-smlouvy	Evidencia vlastných stavov zmlúv — napríklad keď potrebujete zmluvy na prvý pohľad rozlíšiť podľa nejakého príznaku.
smlouva-polozka	Položky zmlúv. Aby sa zo zmluvy vygenerovala faktúra, musí mať zmluva aspoň jednu položku s tým, čo sa má fakturovať, a so špecifikami frekvencie a dátumu generovania.
smlouva-zurnal	História generovania faktúr zo zmlúv — používateľ, dátum generovania, spôsob (manuálny či automatický), počty vygenerovaných faktúr a prípadné chyby.

⚠️ Evidencia smlouva-polozka je spoločná pre položky odberateľských aj dodávateľských zmlúv a nie je možné do nej importovať samostatne — bez hlavičky zmluvy vracia požiadavka 400 s kódom importNotAllowed a hlásením Import není povolen. Položky preto posielajte vnorené do zmluvy, či už pri jej vytvorení, alebo neskoršej aktualizácii.

Telo požiadavky

V tele požiadavky uveďte hlavičku zmluvy s povinnými vlastnosťami a prípadne jej položky:

Vlastnosť	Význam
`kod`	Číslo zmluvy, max. 20 znakov.
`nazev`	Názov zmluvy, max. 255 znakov.
`smlouvaOd`	Začiatok platnosti zmluvy vo formáte dátumu — vo všeobecnosti nastáva okamihom podpisu zmluvy. Platnosť uvedená na položke zmluvy má prednosť.
`typSml`	Odkaz na definovaný typ zmluvy.
`firma`	Odkaz do adresára — firma, ku ktorej sa zmluva viaže.

Pri položkách zmluvy sú povinné kod (označenie, max. 20 znakov) a nazev (max. 255 znakov). Ak položku odkážete na cenníkovú položku elementom cenik, prevezme sa kód aj názov z cenníka a uvádzať ich nemusíte.

⚠️ Ostatné vlastnosti povinné nie sú, pre správne generovanie faktúr je ale nutné ich nastaviť podľa toho, ako potrebujete fakturovať. Viac o nastavení a príkladoch nájdete v článku Odberateľské zmluvy v praxi.

Výsledok

Úspech spoznáte z HTTP statusu alebo z vlastnosti success v odpovedi. Pri úspešnom vytvorení je vracaný status 201 Created a dokument v štandardnom formáte, pozri návratové hodnoty. Pri neúspechu je vracaný status 4xx alebo 5xx a správa o dôvode.

Ukážky volania

Odberateľská zmluva 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 volaním vznikne odberateľská zmluva „Internet na rok výhodne" s vopred definovaným typom SMLOUVA pre firmu ABRA, platná od 1. 3. 2023.

Dodávateľská zmluva 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"
                    }
                ]
            }
        }
    }
}

Tu vznikne dodávateľská zmluva s dvoma položkami. Faktúry sa budú generovať s typom dokladu FAKTURA, frekvencia fakturácie je 12 mesiacov, obratový deň a mesiac 31/1 a fakturuje sa dopredu. Položka KONZULTACE je riešená odkazom na cenníkovú položku, odkiaľ sa automaticky prevezmú povinný kód a názov; položka INTERNET2023 je vytvorená bez väzby na cenník.

Vlastnosť zpusFaktK prijíma hodnoty zpusobFakt.dopredu (Fakturovať dopredu) a zpusobFakt.zpetne (Fakturovať spätne).

Neúspešné požiadavky

Situácia	Odpoveď
Chýba typ zmluvy	`400`, `validace.notNull` — Pole 'Typ smlouvy' musí být vyplněno.
Položka bez väzby na cenník a bez názvu	`400`, `validace.notNull` — Pole 'Název' musí být vyplněno.
Nesprávne zapísaný číselníkový údaj, napríklad spôsob fakturácie	`400`, `importXmlNeplatnyCiselnik` — zpusobFakt.doprdu není platný kód lokalizovaného číselníku zpusobFakt.
Import samostatnej položky bez hlavičky zmluvy	`400`, `importNotAllowed` — Import není povolen.

🚨 Nepovinné vlastnosti ako frekvencia fakturácie alebo obratový deň a mesiac Flexi nijako nekontroluje. Požiadavka s hodnotami "frekFakt": 121, "den": 311 alebo "mesic": 13 prejde bez chyby, ale výsledkom sú nezmyselné hodnoty, ktoré potom zabránia generovaniu faktúr.

FAQ

Ako nájdem faktúru vygenerovanú zo zmluvy?

Vygenerovaná faktúra nesie číslo zmluvy v textovej vlastnosti cisSml aj väzbu smlouva, takže faktúry danej zmluvy je možné priamo vyfiltrovať:

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

Kde nájdem príklady zadania zmlúv?

Videotutoriál a príklady zadania nájdete v článku Odberateľské a dodávateľské zmluvy, širšie súvislosti potom v sérii Odberateľské zmluvy v praxi.

Ako zistím, či a kedy sa zo zmluvy generovalo?

Históriu nájdete v evidencii smlouva-zurnal — obsahuje používateľa, dátum, spôsob generovania, počty faktúr aj prípadné chyby.

Súvisiace

Sorodni članki

API Zmluvy