01
Introduction
Integration with TyreSoft works by exchanging files on a shared server (SFTP/FTP). No API or permanent connection between the systems is needed: each side writes and reads files in designated directories. Server credentials are issued individually to each partner.
02
Data flow
The diagram shows who writes and who reads files in each directory. Arrows show the direction of data flow.
Order lifecycle
- Order placedThe partner saves an XML file in the
/ordersdirectory. - ImportTyreSoft picks up new files at regular intervals and creates the orders in the system.
- ConfirmationAfter a successful import the file is moved, unchanged, to
/orders_processed. - FulfilmentThe order is picked, packed and handed over to the carrier.
- Tracking numberA PDF waybill and a line in the Waybill CSV appear in
/tracking.
Stock levels
Independently of orders, TyreSoft regularly overwrites /stock/stock.csv with current stock levels. The partner downloads it to know which products, and how many, can be ordered.
03
Directory structure
The partner has four directories on the server. Each directory has exactly one “owner” who writes to it.
/ ├── orders/ Partner → new orders (*.xml) ├── orders_processed/ TyreSoft → imported orders ├── tracking/ TyreSoft → waybills (*.pdf) + Waybill (*.csv) └── stock/ TyreSoft → stock.csv, current stock
| Directory | Written by | Read by | Format | File name | Meaning |
|---|---|---|---|---|---|
| /orders | Partner | TyreSoft | XML | {number}.xml | New orders waiting to be imported. |
| /orders_processed | TyreSoft | Partner | XML | unchanged | Orders accepted into the system. File present = order accepted. |
| /tracking | TyreSoft | Partner | PDF, CSV | {TrackingId}.pdfwaybill_YYYYMMDD_HHMMSS.csv | Waybills and tracking numbers for dispatched parcels. |
| /stock | TyreSoft | Partner | CSV | stock.csv | Always a single file with current stock. |
If a file stays in
/orders for longer than one import cycle, please contact us: it may contain a structural error.04
XML order
Each order is a separate XML file with a fixed structure. Below are all elements, the formatting rules and a complete example.
General rules
- One file = one order. UTF-8 encoding, declaration
<?xml version="1.0" encoding="UTF-8"?>. - The file name is the partner's order number with the
.xmlextension, e.g.00006475-WY.xml. File names must be unique. - Root element
<DOCUMENTORDER>; section order:INVOICE→ order data →PRODUCTS→DELIVERY. - Dates in
YYYY-MM-DDformat. Amounts with a dot as decimal separator (157.00). Prices are net prices. - Optional fields may be omitted or left empty, e.g.
<PHONE></PHONE>. - Special characters must be escaped:
&→&,<→<,>→>.
Element reference
| Element | W/O | Description | Example |
|---|---|---|---|
Buyer invoice data: <INVOICE> | |||
| <NUMBER> | W | Contractor's order number (document number in the partner's system). | 178 |
| <FROM> | W | Unique contractor code (Company ID), agreed with TyreSoft. | 1234563218 |
| <NAME> | W | Full company name for the invoice. | Firma Przykładowa Sp. z o.o. |
| <TAXID> | W | Buyer's VAT number. | 1234563218 |
| <STREET> | W | Street. | Przykładowa |
| <STREETNUMBER> | W | Building / apartment number. | 1/2 |
| <POSTALCODE> | W | Postal code. | 00-001 |
| <CITYNAME> | W | City. | Warszawa |
| <COUNTRY> | W | Country. | Polska |
| Order data | |||
| <DATE> | W | Order date (YYYY-MM-DD). | 2026-10-31 |
| <DELIVERYDATE> | W | Shipment date requested by the customer. | 2026-11-02 |
| <ORDERCURRENCY> | W | Order currency (ISO 4217 code). | PLN |
| <NUMBER> | W | Individual order number assigned by the contractor. Returned in the Waybill CSV as CustomerRef. | 00006475-WY |
Products: <PRODUCTS><PRODUCT> (repeatable, one per line item) | |||
| <CODE> | W | Unique product code: EAN or manufacturer code (as in stock.csv). | PO488H1 |
| <NAME> | W | Product name. | Opona 205/65R16C … |
| <ORDERQUANTITY> | W | Ordered quantity (integer). | 4 |
| <SELL_PRICE> | W | Unit net price. | 157.00 |
Delivery: <DELIVERY> | |||
| <MODEOFTRANSPORT> | O | Transport type: 1 = courier, 2 = ordering party's courier. | 1 |
| <CODCOST> | O | Cash-on-delivery amount. 0 = no COD. | 0 |
| <CUSTOMERNAME> | W | Delivery recipient's name. | Firma Przykładowa Sp. z o.o. |
| <STREET> | W | Street. | Przykładowa |
| <STREETNUMBER> | W | Building / apartment number. | 1/2 |
| <POSTALCODE> | W | Postal code. | 00-001 |
| <CITYNAME> | W | City. | Warszawa |
| <COUNTRY> | W | Country. | Polska |
| <PHONE> | O | Recipient's phone, in case of delivery problems. | +48 600 100 200 |
| <PACKQ> | O | Number of parcels. | 4 |
| <LINK> | O | Link to the waybill (PDF), with MODEOFTRANSPORT = 2. | https://…/label.pdf |
| <COMMENTS> | O | Notes for the courier. | Dostawa 8–16 |
Complete file example
An order with two line items and the optional fields filled in.
00008120-WY.xml /orders
<?xml version="1.0" encoding="UTF-8"?> <DOCUMENTORDER> <INVOICE> <NUMBER>181</NUMBER> <FROM>1234563218</FROM> <NAME>Firma Przykładowa Sp. z o.o.</NAME> <TAXID>1234563218</TAXID> <STREET>Przykładowa</STREET> <STREETNUMBER>1/2</STREETNUMBER> <POSTALCODE>00-001</POSTALCODE> <CITYNAME>Warszawa</CITYNAME> <COUNTRY>Polska</COUNTRY> </INVOICE> <DATE>2026-10-31</DATE> <DELIVERYDATE>2026-11-02</DELIVERYDATE> <ORDERCURRENCY>PLN</ORDERCURRENCY> <NUMBER>00008120-WY</NUMBER> <PRODUCTS> <PRODUCT> <CODE>PO488H1</CODE> <NAME>Opona 205/65R16C SNOWTOUR 107/105R POWERTRAC</NAME> <ORDERQUANTITY>4</ORDERQUANTITY> <SELL_PRICE>157.00</SELL_PRICE> </PRODUCT> <PRODUCT> <CODE>225/70R15CSC328</CODE> <NAME>Opona 225/70R15C SC328 112/110R GOODRIDE</NAME> <ORDERQUANTITY>2</ORDERQUANTITY> <SELL_PRICE>178.00</SELL_PRICE> </PRODUCT> </PRODUCTS> <DELIVERY> <MODEOFTRANSPORT>1</MODEOFTRANSPORT> <CODCOST>0</CODCOST> <CUSTOMERNAME>Firma Przykładowa Sp. z o.o.</CUSTOMERNAME> <STREET>Przykładowa</STREET> <STREETNUMBER>1/2</STREETNUMBER> <POSTALCODE>00-001</POSTALCODE> <CITYNAME>Warszawa</CITYNAME> <COUNTRY>Polska</COUNTRY> <PHONE>+48 600 100 200</PHONE> <PACKQ>6</PACKQ> <LINK></LINK> <COMMENTS>Dostawa w godz. 8-16</COMMENTS> </DELIVERY> </DOCUMENTORDER>
05
PDF waybills
For every dispatched parcel TyreSoft saves a PDF shipping document in the /tracking directory.
- The file name is the tracking number, e.g.
10000000001.pdf. The same number appears in theTrackingIdcolumn of the Waybill CSV. - An order shipped in several parcels has several PDF files, one per parcel.
- To match a PDF to an order, look up its number in the Waybill CSV and read the
CustomerRefcolumn.
How the files link together
/orders · XML
<NUMBER>00007993-OW</NUMBER>→
/tracking · Waybill CSV
CustomerRef = 00007993-OWTrackingId = 10000000001→
/tracking · PDF
10000000001.pdfPartner's own carrier (MODEOFTRANSPORT = 2)
If the shipment is collected by the ordering party's carrier, the partner provides its own waybill as a URL in the <LINK> field of the <DELIVERY> section. A print-ready PDF must be available at that URL.
06
Waybill CSV
The Waybill CSV links tracking numbers to the partner's orders. TyreSoft saves it in the /tracking directory.
File format
- Separator: semicolon
;. UTF-8 encoding. The first row contains column headers. - Every row ends with a semicolon.
- One row = one parcel (one tracking number). An order shipped in several parcels takes several rows.
- The
DeliveryDatecolumn uses theD-M-YYYYformat, e.g.21-7-2020. - File name:
waybill_YYYYMMDD_HHMMSS.csv. - The key linking a row to an order is
CustomerRef, i.e. the partner's order number.
| Column | Description | Example |
|---|---|---|
| CompanyId | TyreSoft company / branch identifier. | 100 |
| CustomerId | Partner number in the TyreSoft system. | 100001 |
| DeliveryDate | Dispatch date (D-M-YYYY). | 21-7-2020 |
| PickingListId | Picking list number. | PM1071083 |
| LineNum | Line number on the picking list. | 1 |
| PackingSlipId | Packing slip (dispatch note) number. | PX2120101 |
| OrderId | Order number in the TyreSoft system. | QV200686844 |
| CustomerRef | Partner's order number (NUMBER from the XML file). | 00007993-OW |
| ItemId | Product code. | GY2154516HEFFP |
| EanItemId | Product EAN. | 5452000571731 |
| QuantityDelivered | Quantity shipped in this parcel. | 1 |
| TrackingId | Tracking number (= PDF file name). | 10000000001 |
| DeliveryMode | Carrier / service code. | GLSPLFR |
Example
waybill_20200721_140000.csv /tracking
CompanyId;CustomerId;DeliveryDate;PickingListId;LineNum;PackingSlipId;OrderId;CustomerRef;ItemId;EanItemId;QuantityDelivered;TrackingId;DeliveryMode; 100;100001;21-7-2020;PM1071083;1;PX2120101;QV200686844;00007993-OW;GY2154516HEFFP;5452000571731;1;10000000001;GLSPLFR; 100;100001;21-7-2020;PM1071082;1;PX2120101;QV200688021;00008002-OW;PI2754521YSCZEASPLRX;8019227343250;1;10000000002;GLSPLFR; 100;100001;21-7-2020;PM1071082;2;PX2120101;QV200688021;00008002-OW;PI2754521YSCZEASPLRX;8019227343250;1;10000000003;GLSPLFR; 100;100001;21-7-2020;PM1071081;1;PX2120102;QV200682112;00007952-WY;HI2256516RTRANSIT;6953913105550;1;10000000004;GLSPLFR; 100;100001;21-7-2020;PM1071084;1;PX2120103;QV200685555;00007828-WY;GY2055516HEFFIPRE;5452000812018;1;10000000005;GLSPLFR;
Order
00008002-OW was shipped in two parcels, so it has two rows with different TrackingId numbers.07
Stock CSV
The /stock directory always contains one current stock.csv file. TyreSoft overwrites it at agreed intervals with the complete list of available products. The file contains no history and no incremental changes.
- Semicolon
;separator, UTF-8 encoding, headers in the first row, dot as decimal separator. - Always read the whole file and treat it as the full stock: a product missing from the file is unavailable.
- Use the value of the
Codecolumn as<CODE>in the XML order. - The
UpdatedAtcolumn shows when the stock snapshot was generated.
| Column | Description | Example |
|---|---|---|
| Code | Product code, used as <CODE> in the order. | GY2154516HEFFP |
| EAN | EAN code. | 5452000571731 |
| Name | Product name. | Opona 215/45R16 … |
| Quantity | Available quantity (pcs). | 24 |
| Price | Partner net price. | 289.00 |
| Currency | Price currency. | PLN |
| UpdatedAt | Time the snapshot was generated. | 2026-10-31 12:00 |
stock.csv /stock
Code;EAN;Name;Quantity;Price;Currency;UpdatedAt GY2154516HEFFP;5452000571731;Opona 215/45R16 Goodyear EfficientGrip Performance;24;289.00;PLN;2026-10-31 12:00 GY2055516HEFFIPRE;5452000812018;Opona 205/55R16 Goodyear EfficientGrip Performance;40;265.00;PLN;2026-10-31 12:00 PI2754521YSCZEASPLRX;8019227343250;Opona 275/45R21 Pirelli Scorpion Zero;8;912.00;PLN;2026-10-31 12:00 PO488H1;;Opona 205/65R16C SNOWTOUR 107/105R POWERTRAC;12;157.00;PLN;2026-10-31 12:00 225/70R15CSC328;;Opona 225/70R15C SC328 112/110R GOODRIDE;0;178.00;PLN;2026-10-31 12:00
The set of columns (e.g. prices, delivery time) and the update frequency are agreed with the partner during onboarding.
08
Best practices
Atomic uploadUpload the file under a temporary name (e.g.
.tmp) and rename it to .xml only when the upload is complete. The import will then never pick up a partial file.Leave the archive aloneDo not modify or delete files in
/orders_processed. They confirm that the order was accepted.No duplicatesEvery file in
/orders is treated as a new order. Do not resend the same order under a different name.Read regularlyCheck
/tracking periodically and keep track of the files you have already processed.Check stockCompare quantities with the current
stock.csv before placing an order.Changes & cancellationsReport corrections or cancellations of submitted orders directly to TyreSoft.
09
Going live
- Agree the scopeWe agree the partner identifier (
FROM), currency, delivery method and the data included instock.csv. - Server accessThe partner receives a username and password for the server with the prepared directories.
- Product mappingThe partner downloads
stock.csvand maps theCodevalues to its own catalogue. - Test orderThe partner sends a file marked
TESTin<COMMENTS>and checks that it is moved to/orders_processed. - Go liveOnce the test is approved, orders are fulfilled as normal.
10
Contact
For onboarding, credentials and technical questions: