FlexiBee API - položky dokladů

Chcete přes REST API FlexiBee změnit nějakou položku dokladu nebo ji smazat? Práce s položkami je odlišná od ostatních evidencí. Jak tedy na to?

Založení dokladu s položkami

Na vytvoření nového dokladu přes FlexiBee API není nic složitého. Je nutné zapsat nový záznam do patřičné dokladové evidence. Jeho součástí pak bude kolekce položek, které se mají na doklad přidat.

XML příklad pro novou fakturu vydanou

<winstrom>
    <faktura-vydana>
        <id>ext:FAKTURA-VYDANA:1</id> <!-- identifikátor hlavičky -->
        <!-- pro založení nového dokladu postačí vyplnit typ dokladu -->
        <typDokl>code:FAKTURA</typDokl>
        <bezPolozek>false</bezPolozek>
        <polozkyDokladu>
            <faktura-vydana-polozka>
                <id>ext:FAKTURA-VYDANA:1-1</id> <!-- identifikátor položky -->
                <nazev>Název první položky</nazev>
                <mnozMj>1</mnozMj>
                <cenaMj>100</cenaMj>
            </faktura-vydana-polozka>
            <faktura-vydana-polozka>
                <id>ext:FAKTURA-VYDANA:1-2</id> <!-- identifikátor položky -->
                <nazev>Název druhé položky</nazev>
                <mnozMj>1</mnozMj>
                <cenaMj>200</cenaMj>
            </faktura-vydana-polozka>
        </polozkyDokladu>
    </faktura-vydana>
</winstrom>


JSON příklad pro novou fakturu vydanou

{
    "winstrom": {
        "faktura-vydana":[
            {
                "id": "ext:FAKTURA-VYDANA:1",
                "typDokl": "code:FAKTURA",
                "bezPolozek" : "false",
                "polozkyDokladu": [
                    {
                        "id": "ext:FAKTURA-VYDANA:1-1",
                        "nazev": "Název první položky",
                        "mnozMj": 1,
                        "cenaMj": 100
                    },
                    {
                        "id": "ext:FAKTURA-VYDANA:1-2",
                        "nazev": "Název druhé položky",
                        "mnozMj": 1,
                        "cenaMj": 200
                    }
                ]
            }
        ]
    }
}


Kájovo tip
Kompletní seznam vlastností naleznete v evidence-listu. Např. vlastnosti položek vydané faktury

Na co si dávat pozor?

1. vždycky u všeho uvádějte ID! Nejlépe externí identifikátor. Jak u hlavičky dokladu tak u jeho položek. Pokud ID neuvedete bude FlexiBee záznamy při opakovaném importu duplikovat. A to většinou nechcete 🙂.

2. vždy uvádějte minimální potřebnou množinu vlastností. Jak u nového dokladu tak u jeho položek. Ono totiž FlexiBee umí za vás spoustu věcí domyslet a vy tak nemusíte řešit spoustu účetních záležitostí.

Přidání položky do existujícího dokladu

Přidání položky do dokladu provedete tak, že do API pošlete hlavičku dokladu s ID (proto je dobré ho tam zadávat při vytvoření dokladu) a kolekcí položek obsahující právě tu, kterou chcete přidat.

XML příklad přidání nové položky do faktury vydané

<winstrom>
    <faktura-vydana>
        <id>ext:FAKTURA-VYDANA:1</id>
        <polozkyDokladu>
            <faktura-vydana-polozka>
                <id>ext:FAKTURA-VYDANA:1-3</id>
                <nazev>Název třetí položky</nazev>
                <mnozMj>1</mnozMj>
                <cenaMj>300</cenaMj>
            </faktura-vydana-polozka>
        </polozkyDokladu>
    </faktura-vydana>
</winstrom>


JSON příklad přidání nové položky do faktury vydané

{
    "winstrom": {
        "faktura-vydana": [
            {
                "id": "ext:FAKTURA-VYDANA:1",
                "polozkyDokladu": [
                    {
                        "id": "ext:FAKTURA-VYDANA:1-3",
                        "nazev": "Název třetí položky",
                        "mnozMj": 1,
                        "cenaMj": 300
                    }
                ]
            }
        ]
    }
}


Změna konkrétní položky

Pro změnu konkrétní položky na dokladu je potřeba do API poslat hlavičku dokladu s identifikátorem ID, kolekcí položek obsahující jen měněnou položku opět identifikovanou pomocí ID a vlastnosti, které chceme změnit.

XML příklad změny konkrétní položky faktury vydané

<winstrom>
    <faktura-vydana>
        <id>ext:FAKTURA-VYDANA:1</id>
        <polozkyDokladu>
            <faktura-vydana-polozka>
                <id>ext:FAKTURA-VYDANA:1-3</id>
                <nazev>Změněný název třetí položky</nazev>
            </faktura-vydana-polozka>
        </polozkyDokladu>
    </faktura-vydana>
</winstrom>


JSON příklad změny konkrétní položky faktury vydané

{
    "winstrom": {
        "faktura-vydana": [
            {
                "id": "ext:FAKTURA-VYDANA:1",
                "polozkyDokladu": [
                    {
                        "id": "ext:FAKTURA-VYDANA:1-3",
                        "nazev": "Změněný název třetí položky"
                    }
                ]
            }
        ]
    }
}


Smazání konkrétní položky na dokladu

Tady pozor! Běžně se záznamy z evidencí mažou například pomocí parametru action="delete". U položek a obecně u všech vnořených kolekcí se maže tak, že se pošle hlavička dokladu s kolekcí všech položek, které mají na dokladu zůstat. Navíc se doplní atribut removeAll="true", který zajistí, že všechny neuvedené položky budou odstraněny.

XML příklad smazání položky faktury vydané

<winstrom>
    <faktura-vydana>
        <id>ext:FAKTURA-VYDANA:1</id>
        <polozkyDokladu removeAll="true">
            <faktura-vydana-polozka>
                <id>ext:FAKTURA-VYDANA:1-1</id>
            </faktura-vydana-polozka>
            <faktura-vydana-polozka>
                <id>ext:FAKTURA-VYDANA:1-3</id>
            </faktura-vydana-polozka>
        </polozkyDokladu>
    </faktura-vydana>
</winstrom>


JSON příklad smazání položky faktury vydané

{
    "winstrom": {
        "faktura-vydana": [
            {
                "id": "ext:FAKTURA-VYDANA:1",
                "polozkyDokladu@removeAll": "true",
                "polozkyDokladu": [
                    {
                        "id": "ext:FAKTURA-VYDANA:1-1"
                    },
                    {
                        "id": "ext:FAKTURA-VYDANA:1-3"
                    }
                ]
            }
        ]
    }
}


Na co si dávat pozor?

Pokud použijete atribut removeAll a na položkách nebudete mít ID, tak na první pohled vše projde správně. Na druhý už ale NE! Dojde totiž k tomu, že se všechny položky smažou a vytvoří se zcela nové. To ale způsobuje problémy. Například na objednávkách se vám zarezervuje všechno zboží znovu a vynulují se již realizovaná množství!

Závěr

Kájovo tip
Sazba DPH na položkách dokladů se určuje vlastností typSzbDphK a ne szbDph 😉.

Pokud jste zkoušeli všechny příklady, tak výsledný doklad bude mít dvě položky s názvy "Název první položky" a "Změněný název třetí položky". Protože druhá byla odstraněna.

Ostatní dokladové evidence jsou úplně stejné. Liší se jen názvy používaných evidencí. Pokud tedy např. chcete pracovat s přijatou fakturou a jejími položkami, jsou správné názvy evidencí faktura-prijata (v příkladech nahraďte výskyty faktura-vydana) a faktura-prijata-polozka (místo faktura-vydana-polozka).

Umíme tedy vytvořit doklad s položkami, přidat položku, změnit položku a také smazat konkrétní položku. Co víc? Myslím, že už nic víc není.

Ale pokud vám něco chybí, tak mi dejte vědět 🙂. Třeba do komentářů 👇.

REST API, FlexiBee API

- (16. 3. 2019)

Jsem programátor, horolezec a tak trochu FlexiBee fanatik :-).
Na CharlieBlogu sepisuji své nápady a poznatky už od roku 2006.

Powered by CharlieBlog Engine v2.1