Technical requirements for synchronizing the online store with Torgsoft

1. Product Upload to the Website

A list of what an online store should be able to do for successful integration.

Your online store should be able to upload a price list from a file:

• in *.csv format with a delimiter ; and the name TSGoods.trs,

• or in *.yml format.

The file may not include all the fields, which fields are exported and their order are configurable:

Price lists and orders are located in any folder on the ftp-server, photos — in another folder and have a name identical to the GoodID, and the file extensions of the photos correspond to their type.

From database version 452, additional product photos are also moved to the photo folder with the following name format: photo code (product ID), underscore, additional photo number (not necessarily sequential), dot, file extension.

It doesn't matter how you name the fields in your online store database, or whether you will use all of them or not.

Additional Options

Setting the order of fields in the *.csv file and the ability to exclude fields unnecessary for the online store from the file.

Forming column names in the *.csv file. They can be generated automatically or manually by the user.

When exporting to a YML file, there is a list of reserved tags (if we name the exported field as such, it will be exported as a tag with that name, and not through the param tag — the tag of additional product characteristics):

• name — product name,

• model — product model name,

• vendor — product manufacturer,

• vendorCode — article,

• price — price with discount,

• oldprice — retail price,

• price_old — retail price,

• categoryId — product type/category ID,

• description — product description,

• country — country of manufacturer,

• group_id — product model ID,

• stock_quantity — product quantity,

• barcode — product barcode,

• url — product page URL on the store's website,

• enable_auto_discounts — automatic calculation and display of discounts for the offer,

• vat — VAT rate,

• delivery — true|false — possibility of courier delivery,

• delivery-options — courier delivery conditions for the store's region: types of delivery, terms, cost,

• option — courier delivery conditions for the store's region: types of delivery, terms, cost,

• cost — delivery cost,

• days — delivery term in business days,

• order-before — time before which the order should be placed to receive it within this term,

• pickup — true|false — possibility of pickup from delivery points in all regions the store delivers to,

• store — true|false — possibility to buy the product without a prior order,

• sales_notes — mandatory element if you have purchase restrictions, such as a minimum product quantity or the need for prepayment. You can also specify payment options, promotions, and sales; in this case, the element is optional.

• min-quantity — minimum quantity of identical products in the order for cases where purchase is only possible in bulk, not individually.

• manufacturer_warranty — true|false — official manufacturer warranty,

• adult — true|false — product is related to satisfying sexual needs or otherwise exploits interest in sex,

• expiry — expiration date, shelf life, or end of service life date,

• weight — product weight in kilograms including packaging,

• dimensions — product dimensions in packaging: length, width, height. Specify sizes in centimeters.

• age — product age category,

• typePrefix — type/category,

• country_of_origin — country of origin,

• partType — installment payment,

• partCount — number of payments in installments,

• sale — product available under the "Warm Loans" program, provided that the "Installment Payment" block is mandatory, should be valued as hc,

• partPrice — payment amount.

2. Order Processing in the Program

Additionally, Torgsoft can generate a *.csv file (delimiter ;) with a client database TSClients.trs, which is sent to the same folder as TSGoods.trs. Whether to generate this file is decided by the user with the appropriate setting.

Field Set:

1. Full Name — String (100)

2. Email — String (50)

3. Mobile Phone Number — String (100)

4. Client Discount — Float

5. Landline Phone — String (255)

6. Card Number (client barcode) — String (16)

7. Index — String (15)

8. Country — String (50)

9. Region — String (100)

10. City — String (50)

11. Address — String (255)

12. Additional Information — String field not specified (max length not specified)

13. Discount Calculation Amount — Float

14. Accumulated Bonus Amount — Float

3. Order File Format Type

• Text file with .sal extension — file encoding: Win-1251 or UTF-8, from DB version 428, depending on the synchronization object setting.

• XML file — file encoding: UTF-8, from DB version 493.

• JSON file — file encoding: UTF-8, from DB version 493.

The order file name should consist of ASCII characters — Latin letters, numbers, and delimiters.

Field Descriptions

Text file with .sal extension

[Client] — customer information block

Name=Full Name (required field)

Mphone=0672356147

CPhone=2568974

ZIP=61072

Country=Ukraine

Region=Kharkiv Region

City=Kharkiv

Address=Tobolskaya St. 42-A

EMail=info@torgsoft.ua

[Options] — order information block

OrderNumber=12/21 — required field.

Comment=Delivery from 14 to 18.

DeliveryCondition=Nova Poshta — String (255), from DB version 390.

DeliveryAddress=Kharkiv, Sumskaya St., 124 (Branch No. 33) — String (255), from DB version 505.

ReserveDate=28082013 — reserve date in ddmmyyyy format, from DB version 392.

SaleType=1* — required field.

BonusPay=28.50 — Float, reflecting the amount for the order paid by the client with bonuses, from DB version 463.

GiftCertificate=9567200000106,9567200000182 — list of gift certificates used by the client to pay for the order, separated by commas, from DB version 470.

OrderDate=2009-01-31 01:55:14 — order creation date (optional field) in yyyy-mm-dd hh:mm:ss format, from DB version 470.

CurrencyInternationalCode=UAH — String (4) international order currency code (optional field; if not specified, the order is processed in the national currency), from DB version 493

SaleForm=1 — numeric (value 1 — Wholesale, 2 — Retail), order trade type; if the field is not specified or incorrectly specified, the order is processed as retail trade type, from DB version 500.

[NewPostDeliveryOptions] — new section added

RecepientType=2 — recipient type: 1 — legal entity, 2 — individual.

EGRPOU= — for a legal entity, specify the EDRPOU code — 8-digit numerical code.

LastName=Petrov — recipient contact person's last name for Nova Poshta.

FirstName=Peter — recipient contact person's first name for Nova Poshta.

MiddleName=Petrovich — recipient contact person's middle name for Nova Poshta.

Phone=0676758462 — recipient contact person's mobile phone number for Nova Poshta.

DeliveryType=2 — delivery type: 1 — address delivery to the recipient, 2 — delivery to the Nova Poshta branch.

DeliveryCity=Zabolotiv — city for delivery and to create a new address if DeliveryType= 1 or choose to search for a Nova Poshta branch if DeliveryType= 2.

WarehouseNumber=1 — Nova Poshta branch number.

WarehouseAddress=M. Hrushevskogo St., 3 — Nova Poshta branch address (for more accurate branch search, as the Branch Number is not very unique for search).

StreetType= — for address delivery, the type of street "st.", "ln." etc., for branch delivery — should be empty.

StreetName= — for address delivery to the recipient, the name of the street, for Nova Poshta branch delivery — should be empty.

BuildingNumber= — building number for address delivery to the recipient to create the delivery address.

Flat= — apartment number, if any, for creating the Nova Poshta recipient's address.

Address fields must be filled in Ukrainian, as the list of streets and branches is loaded in Ukrainian when working with the Nova Poshta API. This is necessary for correct search by the passed values on the Nova Poshta server and for creating and adding the address.

For .JSON and .XML format files, the field descriptions should be similar

[1] — block of information about the first order item

GoodID=201 — product key (required field),

Price=120.05 — product sale price (required field),

Count=20 — ordered product quantity (required field),

[2] — block of information about the second order item

GoodID=20294

Price=19.00

Count=1

....

[n] — block of information about the n-th order item

GoodID=13854

Price=63.00

Count=5

XML file format, from DB version 493

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

<Order>

   <Client>

      <Name>Pupkin Ivan Petrovich</Name>

      <MPhone>0675746830</MPhone>

      <CPhone>7601828</CPhone>

      <ZIP>61072</ZIP>

      <Country>Ukraine</Country>

      <Region>Kharkiv</Region>

      <City>Kharkiv</City>

      <Address>Tobolskaya St. 42-A</Address>

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

   </Client>

   <Options>

      <SaleType>1</SaleType>

      <Comment>Entrance code 1685</Comment>

      <OrderNumber>12</OrderNumber>

      <DeliveryCondition>Nova Poshta</DeliveryCondition>

      <DeliveryAddress>Kharkiv, Sumskaya St., 124 (Branch No. 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>

         <Price>145.33</Price>

         <Count>2</Count>

      </Good_1>

      <Good_2>

         <GoodID>38281</GoodID>

         <Price>131.61</Price>

         <Count>1</Count>

   </Good_2>

   </Goods>

</Order>

JSON file format, from DB version 493

{

    "Client": {

        "Name": "Pupkin Ivan Petrovich",

        "MPhone": "0675746830",

        "CPhone": "7601828",

        "ZIP": "61072",

        "Country": "Ukraine",

        "Region": "Kharkiv",

        "City": "Kharkiv",

        "Address": "Tobolskaya St. 42-A",

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

    },

    "Options": {

        "SaleType": "1",

        "Comment": "Entrance code 1685",

        "OrderNumber": "12",

        "DeliveryCondition": "Nova Poshta",

        "DeliveryAddress": "Kharkiv, Sumskaya St., 124 (Branch No. 33)",

        "ReserveDate": "28082013",

        "BonusPay": "100.8",

        "GiftCertificate": "9567200000106,9567200000182",

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

        "CurrencyInternationalCode": "USD"

    },

    "Goods": [

        {

            " GoodID": "38280",

            "Price": "145.33",

            "Count": "2"

        },

        {

            "GoodID": "38281",

            "Price": "131.61",

            "Count": "1"

        }

    ]

} 

*SaleType value can be from 1 to 5:

1 — pre-order: an order is created for which an invoice can be generated,

2 — completed sale: an invoice is created with 100% prepayment,

3 — completed sale with shipping: an invoice is created with 100% prepayment, from which the product is shipped (creation of the shipping invoice),

4 — completed sale with shipping but without payment: an invoice is created without payment, from which the product is shipped (creation of the shipping invoice),

5 — invoice only: order is not created, invoice is created directly.

4. Wholesale Price Policy Export, from DB version 447

When activating the additional «Wholesale Price Policy» function, it is possible to save the wholesale price policy to an xml file and transfer it to the FTP server.

Example of xml file

<?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>

Tag Descriptions

• WholesalePrice — parent section (root element).

• Good — product section, has one parameter GoodID — product key (searchable), Integer.

• Price — price section.

• Quantity — quantity section, value — transition quantity, Float.

• QuantityPrice — price section, value — transition price, Float.

5. Gift Certificate Export to a *.csv File Named TSGiftCertificate.trs, from DB Version 470

Whether to generate this file is decided by the user with the appropriate setting. The file name can be changed. The file is sent to the same folder as TSGoods.trs.

Field Set

1. Gift Certificate Barcode — String (40).

2. Gift Certificate Amount — Float.

3. Gift Certificate Expiry Date — date in ddmmyyyy format (if absent, then the certificate does not have an expiry date or it is counted from the date of certificate sale, but it has not been sold yet).

4. Certificate Type — can take values 1 or 2: 1 — issued, can be sold but cannot be used for purchases; 2 — purchased, bought by the client, can be used for purchases.