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>

Element Typ Povinný Popis
<cis_obj> string **Ano*** Číslo objednávky (primární identifikátor)
<cis_zak> string Ne Alternativní číslo zakázky (fallback pokud chybí cis_obj)
<cis_zint> string Ne Interní číslo (fallback pokud chybí cis_obj i cis_zak)
<dat_vyt> date Ano Datum vytvoření objednávky, formát YYYY-MM-DD
<cas_vyt> time Ne Čas vytvoření, formát HH:MM:SS
<z_pcena> decimal Ano Celková cena bez DPH
<z_pcenas> decimal Ano Celková cena s DPH
<zakl_txt3> string Ne Poznámka / popis objednávky
<mena> string Ano Kód měny (CZK, EUR, USD apod.)
<platba> string Ne Název způsobu platby (např. "Dobírka", "Převodem")
<platba_id> string Ne Externí ID platební metody (pro přesné párování)
<preprava> string Ne Název způsobu dopravy (např. "PPL", "Česká pošta")
<preprava_id> string Ne Externí ID dopravce (pro přesné párování)

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

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

Element Typ Povinný Popis
<nazev> string Ano Jméno osoby nebo název firmy
<nazev2> string Ne Název firmy (pokud vyplněno, nazev se bere jako jméno kontaktní osoby)
<ulice> string Ano Ulice a číslo popisné
<psc> string Ano PSČ
<mesto> string Ano Město
<stat> string Ano Kód státu (CZ, SK, DE, AT apod.) nebo název státu
<ico> string Ne IČO firmy (použito pro vyhledání existujícího partnera)
<dic> string Ne DIČ firmy
<email> string Ne E-mailová adresa
<telefon> string Ne Telefon
<osoba> string Ne Jméno kontaktní osoby
<ref_num> string Ne Referenční číslo / kód pobočky

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

Element Typ Povinný Popis
<k_nazev> string Ne Jméno příjemce
<k_nazev2> string Ne Název firmy příjemce
<k_ulice> string Ne Ulice doručení
<k_psc> string Ne PSČ doručení
<k_mesto> string Ne Město doručení

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

Element Typ Povinný Popis
<ident_ci> string Ano SKU / katalogové číslo produktu
<nazev> string Ano Název produktu
<pocet_mj> decimal Ano Množství
<pcena_mj> decimal Ano Jednotková cena bez DPH
<pscena_mj> decimal Ano Jednotková cena s DPH
<sazba> integer Ano Sazba DPH v procentech (0, 12, 21)

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