Trynx ERP - Import zakázek z e-shopu (2HCS 3.0)

Dokumentace pro implementaci API endpointu na straně e-shopu, ze kterého Trynx ERP stahuje objednávky.

Princip fungování

1. Trynx volá e-shop — periodicky nebo na pokyn uživatele stáhne XML se seznamem nových objednávek
2. Import dat — Trynx zpracuje XML, vytvoří zakázky, partnery a položky ceníku
3. Potvrzení — po úspěšném importu Trynx volá potvrzovací endpoint, aby e-shop označil objednávky jako odeslané

Autentizace

Trynx se autentizuje tokenem v URL. Token je nakonfigurován v nastavení e-shopu v Trynx.

Formát URL:

GET {base_url}/{token}{import_script}

Příklad:

GET https://eshop.example.com/a1b2c3d4e5/api/orders/new

• base_url = https://eshop.example.com
• token = a1b2c3d4e5
• import_script = /api/orders/new

Endpoint pro stažení objednávek

Request

GET {base_url}/{token}{import_script}

Response

• Content-Type: application/xml nebo text/xml
• Encoding: UTF-8
• Kořenový element: <zakazky>

Endpoint musí vracet pouze nové, dosud neodeslané objednávky. Po potvrzení (viz níže) by je již neměl vracet.

XML formát objednávek

Minimální příklad

<?xml version="1.0" encoding="UTF-8"?>
<zakazky>
    <zakazka>
        <cis_obj>OBJ-2026-001</cis_obj>
        <dat_vyt>2026-03-29</dat_vyt>
        <cas_vyt>14:30:00</cas_vyt>
        <z_pcena>1000.00</z_pcena>
        <z_pcenas>1210.00</z_pcenas>
        <mena>CZK</mena>
        <platba>Dobírka</platba>
        <preprava>PPL</preprava>

        <nazev>Jan Novák</nazev>
        <ulice>Hlavní 123</ulice>
        <psc>11000</psc>
        <mesto>Praha</mesto>
        <stat>CZ</stat>
        <email>jan@novak.cz</email>
        <telefon>+420123456789</telefon>

        <tbl_zakobs>
            <tbl_zakob>
                <ident_ci>PROD-001</ident_ci>
                <nazev>Widget A</nazev>
                <pocet_mj>2</pocet_mj>
                <pcena_mj>500.00</pcena_mj>
                <pscena_mj>605.00</pscena_mj>
                <sazba>21</sazba>
            </tbl_zakob>
        </tbl_zakobs>
    </zakazka>
</zakazky>

Prázdná odpověď (žádné nové objednávky)

<?xml version="1.0" encoding="UTF-8"?>
<zakazky>
</zakazky>

Kompletní struktura

Hlavička objednávky <zakazka>

* Alespoň jedno z cis_obj, cis_zak, cis_zint musí být vyplněno.

Fakturační adresa (v rámci <zakazka>)

Doručovací adresa (v rámci <zakazka>, pokud se liší od fakturační)

Položky objednávky <tbl_zakobs> → <tbl_zakob>

Endpoint pro potvrzení importu

Po úspěšném importu Trynx volá potvrzovací endpoint pro každou importovanou objednávku. E-shop by měl objednávku po potvrzení označit jako odeslanou, aby ji příště nevracel.

Request

GET {base_url}/{token}{confirm_script}

V confirm_script se placeholder id_val nahrazuje číslem objednávky (cis_obj).

Příklad konfigurace:

confirm_script = /api/orders/confirm?order_id=id_val

Výsledné volání pro objednávku OBJ-2026-001:

GET https://eshop.example.com/a1b2c3d4e5/api/orders/confirm?order_id=OBJ-2026-001

Očekávaná odpověď

Trynx nevaliduje odpověď potvrzovacího endpointu. Doporučujeme vracet HTTP 200 s libovolným tělem.

Pravidla zpracování dat

Identifikace zákazníka

Trynx hledá existujícího partnera v adresáři podle:

1. IČO (<ico>) — pokud je vyplněno, hledá přesnou shodu
2. Název firmy (<nazev2> nebo <nazev>) — pokud IČO chybí

Pokud partner neexistuje, automaticky se vytvoří nový záznam v adresáři.

Párování platební a dopravní metody

Pro přesné párování platebních a dopravních metod použijte <platba_id> a <preprava_id>. Tyto hodnoty se párují s polem external_id v konfiguraci Trynx.

Priorita párování:

1. external_id (pokud je <platba_id> / <preprava_id> vyplněno)
2. Název (<platba> / <preprava>)
3. Výchozí hodnota ze systémového nastavení

Měna

Element <mena> se páruje s kódem nebo názvem měny v Trynx (tabulka cl_currencies, pole currency_name nebo currency_code). Pokud měna neexistuje, použije se výchozí měna firmy.

Ceník

Produkty se párují podle <ident_ci> (SKU). Pokud produkt v ceníku neexistuje, automaticky se vytvoří. Ceny se při importu aktualizují (lze vypnout v konfiguraci e-shopu).

ParcelShop

Pokud název dopravy obsahuje "ParcelShop - ParcelShop (ID)", Trynx automaticky extrahuje ID výdejního místa z textu v závorce a uloží ho do pole u_dbranch na zakázce.

Příklad: Kompletní objednávka se všemi poli

<?xml version="1.0" encoding="UTF-8"?>
<zakazky>
    <zakazka>
        <!-- Identifikace -->
        <cis_obj>OBJ-2026-042</cis_obj>
        <dat_vyt>2026-03-29</dat_vyt>
        <cas_vyt>09:15:30</cas_vyt>

        <!-- Ceny -->
        <z_pcena>2450.00</z_pcena>
        <z_pcenas>2964.50</z_pcenas>
        <zakl_txt3>Urgentní objednávka - doručit do pátku</zakl_txt3>

        <!-- Platba a doprava -->
        <mena>CZK</mena>
        <platba>Převodem</platba>
        <platba_id>BANK_TRANSFER</platba_id>
        <preprava>PPL</preprava>
        <preprava_id>PPL_STANDARD</preprava_id>

        <!-- Fakturační adresa -->
        <nazev>Jan Novák</nazev>
        <nazev2>Novák s.r.o.</nazev2>
        <ulice>Průmyslová 456</ulice>
        <psc>10200</psc>
        <mesto>Praha 10</mesto>
        <stat>CZ</stat>
        <ico>12345678</ico>
        <dic>CZ12345678</dic>
        <email>objednavky@novak-sro.cz</email>
        <telefon>+420 777 888 999</telefon>
        <osoba>Jan Novák</osoba>
        <ref_num>POB-01</ref_num>

        <!-- Doručovací adresa -->
        <k_nazev>Jan Novák</k_nazev>
        <k_nazev2>Novák s.r.o. - sklad</k_nazev2>
        <k_ulice>Skladová 789</k_ulice>
        <k_psc>25001</k_psc>
        <k_mesto>Brandýs nad Labem</k_mesto>

        <!-- Položky -->
        <tbl_zakobs>
            <tbl_zakob>
                <ident_ci>WIDGET-A100</ident_ci>
                <nazev>Widget A - základní</nazev>
                <pocet_mj>5</pocet_mj>
                <pcena_mj>200.00</pcena_mj>
                <pscena_mj>242.00</pscena_mj>
                <sazba>21</sazba>
            </tbl_zakob>
            <tbl_zakob>
                <ident_ci>WIDGET-B200</ident_ci>
                <nazev>Widget B - prémiový</nazev>
                <pocet_mj>3</pocet_mj>
                <pcena_mj>450.00</pcena_mj>
                <pscena_mj>544.50</pscena_mj>
                <sazba>21</sazba>
            </tbl_zakob>
            <tbl_zakob>
                <ident_ci>SLUZBA-MONTAZ</ident_ci>
                <nazev>Montáž</nazev>
                <pocet_mj>1</pocet_mj>
                <pcena_mj>100.00</pcena_mj>
                <pscena_mj>121.00</pscena_mj>
                <sazba>21</sazba>
            </tbl_zakob>
        </tbl_zakobs>
    </zakazka>
</zakazky>

Poznámky k implementaci

• Endpoint musí vracet pouze nové objednávky, které ještě nebyly potvrzeny
• Trynx detekuje duplicity podle čísla objednávky (cis_obj) — pokud zakázka se stejným číslem již existuje, import ji přeskočí
• Doprava a platba se v Trynx mohou automaticky přidat jako položky zakázky (pokud mají přiřazenou položku ceníku)
• Desetinná čísla používají tečku jako oddělovač (ne čárku)
• Všechny textové hodnoty mohou být obaleny v CDATA sekcích