Trynx ERP - Export stavů skladu na e-shop (Simple Store)

Dokumentace pro implementaci API endpointu na straně e-shopu, který přijímá aktuální stavy skladu z Trynx ERP.

Princip fungování

1. Trynx odesílá data na e-shop — periodicky nebo na pokyn uživatele odešle XML se stavy skladu všech aktivních produktů
2. E-shop přijme a zpracuje — aktualizuje dostupnost produktů podle přijatých dat
3. E-shop potvrdí přijetí — vrátí odpověď začínající <OK>

Komunikace je jednosměrná (Trynx → e-shop). Trynx odesílá kompletní stav skladu v jednom HTTP requestu.

Autentizace

Trynx se autentizuje tokenem v URL.

Formát URL:

POST {base_url}/{token}{import_script}

Příklad:

POST https://eshop.example.com/a1b2c3d4e5/api/stock/sync

Endpoint pro příjem stavů skladu

Request

POST {base_url}/{token}{import_script}
Content-Type: application/x-www-form-urlencoded

Parametry requestu

Data jsou odesílána jako POST parametr cXML obsahující XML řetězec.

cXML=<?xml version="1.0" ...?>...

Získání XML na straně serveru (příklady):

// PHP
$xml = $_POST['cXML'];

// Node.js (Express)
const xml = req.body.cXML;

// Python (Flask)
xml = request.form['cXML']

Očekávaná odpověď

• HTTP Status: 200
• Tělo odpovědi musí začínat řetězcem <OK>

Příklad úspěšné odpovědi:

<OK>Stock updated successfully</OK>

Příklad chybové odpovědi:

<ERROR>Invalid XML format</ERROR>

Pokud odpověď nezačíná <OK>, Trynx to vyhodnotí jako chybu a zobrazí uživateli hlášení.

XML formát stavů skladu

Struktura

<?xml version="1.0" encoding="windows-1250" standalone="yes"?>
<VFPDataSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <tbl_cenik>
        <ident_ci>PROD-001</ident_ci>
        <mj_astav>150.00</mj_astav>
        <mj_bstav>12.00</mj_bstav>
        <store>
            <store_id>Hlavní sklad</store_id>
            <quantity>120.00</quantity>
        </store>
        <store>
            <store_id>Sklad Praha</store_id>
            <quantity>30.00</quantity>
        </store>
    </tbl_cenik>
    <tbl_cenik>
        <ident_ci>PROD-002</ident_ci>
        <mj_astav>0.00</mj_astav>
        <mj_bstav>0.00</mj_bstav>
    </tbl_cenik>
</VFPDataSet>

Popis elementů

Kořenový element

Produkt <tbl_cenik> (opakuje se pro každý aktivní produkt)

Sklad <store> (0 až N opakování v rámci <tbl_cenik>)

Výpočet množství

Aktuální stav (mj_astav)

Součet všech příjmů minus součet všech výdejů za celou historii skladových pohybů produktu:

mj_astav = SUM(příjmy) - SUM(výdeje)

Z výpočtu jsou vyloučeny nedokončené importy (rozpracované příjemky).

Blokované množství (mj_bstav)

Součet množství na položkách zakázek, které:

• ještě nebyly expedovány (nemají přiřazený skladový pohyb)
• nejsou stornované
• nejsou dokončené/finalizované

Pokud firma nemá zapnuté blokování skladu v nastavení, mj_bstav je vždy 0.00.

Skutečně dostupné množství pro e-shop

E-shop by měl pro zobrazení dostupnosti zákazníkům vypočítat:

dostupné = mj_astav - mj_bstav

Příklad: Kompletní XML

<?xml version="1.0" encoding="windows-1250" standalone="yes"?>
<VFPDataSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <tbl_cenik>
        <ident_ci>WIDGET-A100</ident_ci>
        <mj_astav>250.00</mj_astav>
        <mj_bstav>35.00</mj_bstav>
        <store>
            <store_id>Hlavní sklad</store_id>
            <quantity>200.00</quantity>
        </store>
        <store>
            <store_id>Sklad Praha</store_id>
            <quantity>50.00</quantity>
        </store>
    </tbl_cenik>
    <tbl_cenik>
        <ident_ci>WIDGET-B200</ident_ci>
        <mj_astav>0.00</mj_astav>
        <mj_bstav>0.00</mj_bstav>
    </tbl_cenik>
    <tbl_cenik>
        <ident_ci>SLUZBA-MONTAZ</ident_ci>
        <mj_astav>1000.00</mj_astav>
        <mj_bstav>0.00</mj_bstav>
        <store>
            <store_id>Hlavní sklad</store_id>
            <quantity>1000.00</quantity>
        </store>
    </tbl_cenik>
</VFPDataSet>

Interpretace e-shopem:

Poznámky k implementaci

• Všechny aktivní produkty jsou odesílány v každém požadavku — e-shop by měl při zpracování aktualizovat všechny přijaté produkty najednou
• Produkty, které nejsou v XML, nebyly změněny nebo jsou neaktivní — e-shop by je neměl mazat, pouze ignorovat
• Kódování: XML deklaruje windows-1250, doporučujeme zpracovávat s podporou tohoto kódování (nebo konvertovat na UTF-8)
• Desetinná čísla používají tečku jako oddělovač
• Frekvence synchronizace závisí na nastavení v Trynx — může být manuální (tlačítko), při přihlášení uživatele, nebo automatická
• Element <store> nemusí být přítomen u produktů bez skladových pohybů — součet quantities ve <store> elementech nemusí odpovídat <mj_astav> (kvůli vyloučeným nedokončeným importům)
• Párování produktů probíhá výhradně přes <ident_ci> — tato hodnota musí odpovídat SKU/katalogovému číslu produktu v e-shopu