Technické požiadavky na synchronizáciu internetového obchodu s Torgsoftom

1. Nahrávanie tovarov na webovú stránku

Zoznam toho, čo by mal vedieť internetový obchod pre úspešné prepojenie.

Váš internetový obchod by mal vedieť načítať cenník zo súboru:

• vo formáte *.csv s oddeľovačom ;  a názvom TSGoods.trs,

• alebo súbor vo formáte *.yml.  

V súbore nemusia byť prítomné všetky polia, ktoré polia sa exportujú a ich poradie — to sa nastavuje:

Cenník a objednávky sa nachádzajú v ľubovoľnom adresári na ftp-serveri, fotografie — v inom adresári a majú názov zodpovedajúci GoodID, pričom prípony súborov fotografií zodpovedajú ich typu.

Od verzie databázy 452, do adresára s fotografiami sa presúvajú aj ďalšie fotografie tovaru s nasledujúcim formátom názvu: kód fotografie (ID tovaru), spodná pomlčka, číslo ďalšej fotografie (nemusí byť po poradí), bodka, prípona súboru.

Nezáleží na tom, ako nazvete polia vo svojej databáze internetového obchodu, či ich budete všetky používať alebo nie — to je tiež jedno.

Ďalšie možnosti

Nastavenie poradia polí vo súbore *.csv a možnosť vylúčiť nepotrebné polia pre internetový obchod zo súboru.

Formovať názvy stĺpcov vo súbore *.csv. Môžu byť formované automaticky alebo ručne používateľom.

Pri exporte do súboru YML je zoznam rezervovaných značiek (ak takto nazveme exportované pole, bude exportované práve ako značka s týmto názvom, a nie cez značku param — značka ďalších vlastností tovaru):

• name — názov tovaru,

• model — názov modelu tovaru,

• vendor — výrobca tovaru,

• vendorCode — číslo artiklu,

• price — cena so zľavou,

• oldprice — maloobchodná cena,

• price_old — maloobchodná cena,

• categoryId — ID typu tovaru/kategórie,

• description — popis tovaru,

• country — krajina výrobcu,

• group_id — ID modelu tovaru,

• stock_quantity — množstvo tovaru,

• barcode — čiarový kód tovaru,

• url — URL stránky tovaru na webovej stránke obchodu,

• enable_auto_discounts — automatický výpočet a zobrazenie zliav pre ponuku,

• vat — sadzba DPH,

• delivery —  true|false — možnosť kuriérskej dodávky,

• delivery-options — podmienky kuriérskej dodávky tovaru podľa regiónu obchodu: druhy dodávky, lehoty, cena,

• option — podmienky kuriérskej dodávky tovaru podľa regiónu obchodu: druhy dodávky, lehoty, cena,

• cost — cena dodávky,

• days — lehota dodávky v pracovných dňoch,

• order-before — čas, do ktorého je potrebné urobiť objednávku, aby ju bolo možné doručiť v tejto lehote,

• pickup — true|false— možnosť osobného odberu z odberných miest vo všetkých regiónoch, do ktorých obchod dodáva,

• store — true|false — možnosť kúpiť tovar bez predchádzajúcej objednávky,

• sales_notes — povinný prvok, ak máte obmedzenia pri kúpe, napríklad minimálne množstvo tovaru alebo potrebu predplatiť. Môžete tiež uviesť možnosti platby, akcie a výpredaje, v tomto prípade je použitie prvku nepovinné.

• min-quantity — minimálne množstvo rovnakého tovaru v objednávke pre prípady, keď je možné tovar kúpiť len v sade, a nie po kuse.

• manufacturer_warranty — true|false — oficiálna záruka výrobcu,

• adult — true|false — tovar súvisí so sexuálnymi potrebami, alebo inak využíva záujem o sex,

• expiry — dátum spotreby, dátum použitia alebo dátum skončenia platnosti,

• weight — hmotnosť tovaru v kilogramoch vrátane balenia,

• dimensions — rozmery tovaru v balení: dĺžka, šírka, výška. Rozmery uveďte v centimetroch.

• age — veková kategória tovaru,

• typePrefix — typ/kategória, 

• country_of_origin — krajina pôvodu,

• partType — platba na splátky,

• partCount — počet splátok v splátkovej platbe,

• sale — tovar je k dispozícii v programe «Teplé kredity», za podmienky povinného uvedenia bloku «Platba na splátky», musí byť hodnota hc,

• partPrice — suma splátky.

2. Spracovanie objednávok v programe

Tiež Torgsoft môže vytvárať súbor *.csv (oddeľovač ;) s klientskou databázou TSClients.trs, ktorá sa odosiela do rovnakého adresára ako TSGoods.trs. Či tento súbor vytvárať — rozhoduje používateľ príslušným nastavením.

Súbor obsahuje polia :

1. Meno a priezvisko — Textové/String (100) 

2. e-mail — Textové/String (50)

3. Telefónne číslo, mobilné — Textové/String (100)

4. Zľava klienta — Desatinné/Float

5. Mesto telefon — Textové/String (255)

6. Číslo karty (čiarový kód klienta) — Textové/String (16)

7. PSČ — Textové/String (15)

8. Krajina — Textové/String (50)

9. Kraj — Textové/String (100)

10. Mesto — Textové/String (50)

11. Adresa — Textové/String (255)

12. Dodatočné informácie — Textové/String pole neurčené (maximálna dĺžka neurčená)

13. Suma na výpo čet zľavy — Desatinné/Float

14. Suma nazbieraných bonusov — Desatinné/Float

3. Typ vytvárania objednávky do súborov

• Textový súbor s príponou sal — kódovanie súboru: Win-1251 alebo UTF-8, od verzie 428 databázy, podľa nastavenia objektu synchronizácie.

• Súbor vo formáte XML — kódovanie súboru: UTF-8, od verzie 493 databázy.

• Súbor vo formáte JSON — kódovanie súboru: UTF-8, od verzie 493 databázy.

Názov súboru objednávky musí byť zložený z ASCII znakov — latinské písmená, číslice a oddeľovače.

Popis polí

Textový súbor s príponou sal

[Client] — blok informácií o klientovi

Name=Meno a priezvisko (povinné pole)

Mphone=0672356147

CPhone=2568974

ZIP=61072

Country=Ukrajina

Region=Charkovský kraj

City=Charkov

Address=ul. Tobolská 42-A

EMail=info@torgsoft.ua

[Options] — blok informácií o objednávke

OrderNumber=12/21 — povinné pole.

Comment=Dodávka od 14 do 18.

DeliveryCondition=Nová pošta — Textové/String (255), od verzie 390 databázy.

DeliveryAddress=Charkov, ul. Sumska, 124 (Pobočka č.33) — Textové/String (255), od verzie 505 databázy.

ReserveDate=28082013 — dátum rezervácie vo formáte ddmmyyyyy, od verzie 392 databázy.

SaleType=1* — povinné pole.

BonusPay=28,50 — Desatinné/Float, ktorý zobrazuje sumu za objednávku, ktorú klient zaplatil bonusmi, od verzie 463 databázy.

GiftCertificate=9567200000106,9567200000182 — zoznam darčekových certifikátov, ktoré klient použil na zaplatenie objednávky cez ČIARKU, od verzie 470 databázy.

OrderDate=2009-01-31 01:55:14 — dátum vytvorenia objednávky (nepovinné pole) vo formáte yyyy-mm-dd hh:mm:ss, od verzie 470 databázy.

CurrencyInternationalCode=UAH — Textové/String (4) medzinárodný kód meny objednávky (nepovinné pole; ak nie je uvedené, objednávka sa spracováva v národnej mene), od verzie 493 databázy

SaleForm=1 — číselné (hodnota 1 — Veľkoobchod, 2 — Maloobchod), typ predaja objednávky; ak pole nie je uvedené alebo je uvedené nesprávne, objednávka sa spracováva ako maloobchod, od verzie 500 databázy.

[NewPostDeliveryOptions] — pridaná nová sekcia

RecepientType=2 — typ príjemcu: 1 — právnická osoba, 2 — fyzická osoba.

EGRPOU= — pre právnickú osobu sa uvádza kód EGRPOU — 8-ciferný číselný kód.

LastName=Petrov — priezvisko kontaktnej osoby príjemcu Novej pošty.

FirstName=Peter — meno kontaktnej osoby príjemcu Novej pošty.

MiddleName=Petrovič — patronymum kontaktnej osoby príjemcu Novej pošty.

Phone=0676758462 — mobilný telefón kontaktnej osoby príjemcu Novej pošty.

DeliveryType=2 — typ dodávky: 1 — doručenie na adresu príjemcu, 2 — doručenie na sklad Novej pošty.

DeliveryCity=Zabolotiv — mesto, kam sa má doručiť a pre ktoré mesto sa má vytvoriť nová adresa pri DeliveryType= 1 alebo vyhľadávať sklad novej pošty pri DeliveryType= 2.

WarehouseNumber=1 — číslo pobočky Novej pošty.

WarehouseAddress=ul. M. Hruševského, 3 — adresa pobočky Novej pošty (pre presnejšie vyhľadávanie pobočky, pretože Číslo pobočky nie je veľmi unikátne).

StreetType= — pri doručovaní na adresu typ ulice "ul", "prov" atď., pri doručovaní na sklad — musí byť prázdne.

StreetName= — pri doručovaní na adresu príjemcu názov ulice, pri doručovaní na sklad Novej pošty — musí byť prázdne.

BuildingNumber= — číslo domu pri doručovaní na adresu príjemcu na vytvorenie doručovacej adresy.

Flat= — číslo bytu, ak je, na vytvorenie adresy príjemcu Novej pošty.

Adresné polia musia byť vyplnené v ukrajinskom jazyku, pretože pri práci s API Novej Pošty sa zoznam ulíc a pobočiek načítava v ukrajinskom jazyku. Je to potrebné pre správnosť vyhľadávania podľa zadaných hodnôt na serveri Novej pošty a vytvorenie a pridanie adresy.

Pre súbory vo formáte .JSON a .XML popis polí má byť obdobný

[1] — blok informácií o prvom tovare objednávky

GoodID=201 — kľúč tovaru, (povinné pole),

Price=120,05 — predajná cena tovaru, (povinné pole),

Count=20 — množstvo objednaného tovaru, (povinné pole),

[2] — blok informácií o druhom tovare objednávky

GoodID=20294

Price=19,00

Count=1

....

[n] — blok informácií o n-tom tovare objednávky

GoodID=13854

Price=63,00

Count=5

Súbor vo formáte XML, od verzie 493 databázy

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

<Order>

   <Client>

      <Name>Pupkin Ivan Petrovič</Name>

      <MPhone>0675746830</MPhone>

      <CPhone>7601828</CPhone>

      <ZIP>61072</ZIP>

      <Country>Ukrajina</Country>

      <Kraj>Charkovský</ Kraj>

      <City>Charkov</City>

      <Address>ul.Tobolská 42-A</Address>

      <EMail>info@torgsoft.com.ua</EMail>

   </Client>

   <Options>

      <SaleType>1</SaleType>

      <Comment>Kód vchodu 1685</Comment>

      <OrderNumber>12</OrderNumber>

      <DeliveryCondition>Nová Pošta</DeliveryCondition>

      <DeliveryAddress>Charkov, ul. Sumska, 124 (Pobočka č.33)</DeliveryAddress>

      <ReserveDate>28082013</ReserveDate>

      <BonusPay>100.8</BonusPay>

      <GiftCertificate>9567200000106,9567200000182 </GiftCertificate>

      <DateOrderDate>2020-02-04 18:19:44 </DateOrderDate>

      <CurrencyInternationalCode>USD</CurrencyInternationalCode>

   </Options>

   <Goods>

      <Good_1>

         <GoodID>38280</GoodID>

         <Cena>145.33</Price>

         <Count>2</Count>

      </Good_1>

      <Good_2>

         <GoodID>38281</GoodID>

         <Price>131.61</Price>

         <Count>1</Count>

      </Good_2>

   </Goods>

</Order>

Súbor vo formáte JSON, od verzie 493 databázy

{

    "Client": {

        "Name": "Pupkin Ivan Petrovič",

        "MPhone": "0675746830",

        "CPhone": "7601828",

        "ZIP": "61072",

        "Country": "Ukrajina",

        "Region": "Charkovský",

        "Mesto": "Charkov",

        "Address": "ul. Tobolská 42-A",

        "EMail": "info@torgsoft.com.ua"

    },

    "Options": {

        "SaleType": "1",

        "Comment": "Kód vchodu 1685",

        "OrderNumber": "12",

        "DeliveryCondition": "Nová Pošta",

        "DeliveryAddress": "Charkov, ul. Sumska, 124 (Pobočka č.33)",

        "ReserveDate": "28082013",

        "BonusPay": "100.8",

        "GiftCertificate": "9567200000106,9567200000182",

        "OrderDate": "2020-02-04 18:19:44",

        "CurrencyInternationalCode": "USD"

    },

    "Goods": [

        {

            "GoodID": "38280",

            "Cena": "145.33",

            "Count": "2"

        },

        {

            "GoodID": "38281",

            "Price": "131.61",

            "Count": "1"

        }

    ]

} 

*Hodnota SaleType môže byť od 1 do 5:

1 — predobjednávka: vytvorí sa objednávka, podľa ktorej je možné vytvoriť faktúru,

2 — vytvorený predaj: vytvorí sa faktúra so 100% predplatením,

3 — vytvorený predaj s odoslaním: vytvorí sa faktúra so 100% predplatením, podľa ktorej sa tovar odosiela (vytvorenie výdajného dokladu),

4 — vytvorený predaj s odoslaním, ale bez platby: vytvorí sa faktúra bez platby, podľa ktorej sa tovar odosiela (vytvorenie výdajného dokladu),

5 — iba faktúra: objednávka sa nevytvára, vytvorí sa okamžite faktúra.

4. Export politiky veľkoobchodných cien, od verzie 447 databázy

Pri aktivácii doplnkovej funkcie «Politika veľkoobchodných cien» je možné uložiť politiku veľkoobchodných cien do xml súboru a preniesť ho na FTP server.

Príklad xml súboru

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

<WholesalePrice>

  <Good GoodID="1378">

    <Price>

      <Quantity>2</Quantity>

      <QuantityPrice>33</QuantityPrice>

    </Price>

    <Price>

      <Quantity>3</Quantity>

      <QuantityPrice>32</QuantityPrice>

    </Price>

    <Price>

      <Quantity>5</Quantity>

      <QuantityPrice>30</QuantityPrice>

    </Price>

  </Good>

  <Good GoodID="42">

    <Price>

      <Quantity>2</Quantity>

      <QuantityPrice>6.5</QuantityPrice>

    </Price>

    <Price>

      <Quantity>3</Quantity>

      <QuantityPrice>6.3</QuantityPrice>

    </Price>

    <Price>

      <Quantity>5</Quantity>

      <QuantityPrice>6.1</QuantityPrice>

    </Price>

  </Good>

</WholesalePrice>

Popis značiek

• WholesalePrice — rodičovská sekcia (koreňový prvok).

• Good — sekcia tovaru, má jeden parameter GoodID — kľúč tovaru (vyhľadávací), Celé/Integer.

• Price — sekcia ceny.

• Quantity — sekcia množstva, hodnota — množstvo pre prechod, Desatinné/Float.

• QuantityPrice — sekcia ceny, hodnota — cena počas prechodu, Desatinné/Float.

5. Export darčekových certifikátov do súboru *.csv formátu s názvom TSGiftCertificate.trs, od verzie 470 databázy

Či tento súbor vytvárať, rozhoduje používateľ príslušným nastavením. Názov súboru je možné zmeniť. Súbor sa odosiela do rovnakého adresára ako TSGoods.trs.

Súbor obsahuje polia

1. Čiarový kód certifikátu — Textové/String (40).

2. Suma certifikátu — Desatinné/Float.

3. Dátum skončenia platnosti certifikátu — dátum formátu ddmmyyyyyy (ak nie je, certifikát nemá platnosť alebo sa počíta od dátumu predaja certifikátu, ale ešte nie je predaný).

4. Typ certifikátu — môže mať hodnoty 1 alebo 2: 1 — vydaný, môže sa predať, ale nemožno ho použiť na platbu; 2 — kúpený, kúpený klientom, môže sa použiť na platbu.