Wprowadzenie
Integracja z TyreSoft odbywa się przez wymianę plików na wspólnym serwerze (SFTP/FTP). Nie wymaga API ani stałego połączenia między systemami: każda ze stron zapisuje i odczytuje pliki we wskazanych katalogach. Dane dostępowe do serwera przekazujemy indywidualnie każdemu partnerowi.
Przepływ danych
Schemat pokazuje, kto zapisuje i kto odczytuje pliki w każdym katalogu. Strzałki wskazują kierunek przepływu danych.
Cykl życia zamówienia
- Złożenie zamówieniaPartner zapisuje plik XML w katalogu
/orders. - ImportTyreSoft cyklicznie pobiera nowe pliki i zakłada zamówienia w systemie.
- PotwierdzeniePo poprawnym imporcie plik jest przenoszony bez zmian do
/orders_processed. - RealizacjaZamówienie jest kompletowane, pakowane i przekazywane kurierowi.
- Numer listuW
/trackingpojawia się list przewozowy PDF i wiersz w pliku Waybill CSV.
Stany magazynowe
Niezależnie od zamówień TyreSoft regularnie nadpisuje plik /stock/stock.csv aktualnymi stanami. Partner pobiera go, aby wiedzieć, które produkty i w jakiej ilości może zamówić.
Struktura katalogów
Na serwerze partner ma do dyspozycji cztery katalogi. Każdy z nich ma jednego „właściciela”, który w nim zapisuje.
/ ├── orders/ Partner → nowe zamówienia (*.xml) ├── orders_processed/ TyreSoft → zamówienia zaimportowane ├── tracking/ TyreSoft → listy przewozowe (*.pdf) + Waybill (*.csv) └── stock/ TyreSoft → stock.csv, aktualne stany
| Katalog | Zapisuje | Odczytuje | Format | Nazwa pliku | Znaczenie |
|---|---|---|---|---|---|
| /orders | Partner | TyreSoft | XML | {numer}.xml | Nowe zamówienia czekające na import. |
| /orders_processed | TyreSoft | Partner | XML | bez zmian | Zamówienia przyjęte do systemu. Obecność pliku = potwierdzenie przyjęcia. |
| /tracking | TyreSoft | Partner | PDF, CSV | {TrackingId}.pdfwaybill_RRRRMMDD_HHMMSS.csv | Listy przewozowe i numery listów dla nadanych paczek. |
| /stock | TyreSoft | Partner | CSV | stock.csv | Zawsze jeden plik z aktualnym stanem magazynu. |
/orders dłużej niż jeden cykl importu, prosimy o kontakt: może zawierać błąd struktury.Zamówienie XML
Każde zamówienie to osobny plik XML o stałej strukturze. Poniżej opisujemy wszystkie elementy, reguły formatowania i kompletny przykład.
Zasady ogólne
- Jeden plik = jedno zamówienie. Kodowanie UTF-8, deklaracja
<?xml version="1.0" encoding="UTF-8"?>. - Nazwa pliku to numer zamówienia partnera z rozszerzeniem
.xml, np.00006475-WY.xml. Nazwy nie mogą się powtarzać. - Element główny
<DOCUMENTORDER>; kolejność sekcji:INVOICE→ dane zamówienia →PRODUCTS→DELIVERY. - Daty w formacie
RRRR-MM-DD. Kwoty z kropką jako separatorem dziesiętnym (157.00). Ceny są cenami netto. - Pola opcjonalne można pominąć lub pozostawić puste, np.
<PHONE></PHONE>. - Znaki specjalne muszą być zakodowane:
&→&,<→<,>→>.
Opis elementów
| Element | W/O | Opis | Przykład |
|---|---|---|---|
Dane nabywcy do faktury: <INVOICE> | |||
| <NUMBER> | W | Numer zamówienia kontrahenta (numer dokumentu w systemie partnera). | 178 |
| <FROM> | W | Unikalny kod kontrahenta (Company ID), uzgodniony z TyreSoft. | 1234563218 |
| <NAME> | W | Pełna nazwa firmy do faktury. | Firma Przykładowa Sp. z o.o. |
| <TAXID> | W | Numer NIP / VAT ID nabywcy. | 1234563218 |
| <STREET> | W | Ulica. | Przykładowa |
| <STREETNUMBER> | W | Numer budynku / lokalu. | 1/2 |
| <POSTALCODE> | W | Kod pocztowy. | 00-001 |
| <CITYNAME> | W | Miejscowość. | Warszawa |
| <COUNTRY> | W | Kraj. | Polska |
| Dane zamówienia | |||
| <DATE> | W | Data złożenia zamówienia (RRRR-MM-DD). | 2026-10-31 |
| <DELIVERYDATE> | W | Data wysyłki proponowana przez klienta. | 2026-11-02 |
| <ORDERCURRENCY> | W | Waluta zamówienia (kod ISO 4217). | PLN |
| <NUMBER> | W | Indywidualny numer zamówienia nadany przez kontrahenta. Wraca w Waybill CSV jako CustomerRef. | 00006475-WY |
Produkty: <PRODUCTS><PRODUCT> (powtarzalny, jeden na pozycję) | |||
| <CODE> | W | Unikalny kod towaru: EAN lub kod producenta (jak w stock.csv). | PO488H1 |
| <NAME> | W | Nazwa towaru. | Opona 205/65R16C … |
| <ORDERQUANTITY> | W | Zamawiana ilość (liczba całkowita). | 4 |
| <SELL_PRICE> | W | Jednostkowa cena netto. | 157.00 |
Dostawa: <DELIVERY> | |||
| <MODEOFTRANSPORT> | O | Rodzaj transportu: 1 = kurier, 2 = kurier zamawiającego. | 1 |
| <CODCOST> | O | Kwota pobrania. 0 = bez pobrania. | 0 |
| <CUSTOMERNAME> | W | Nazwa odbiorcy dostawy. | Firma Przykładowa Sp. z o.o. |
| <STREET> | W | Ulica. | Przykładowa |
| <STREETNUMBER> | W | Numer budynku / lokalu. | 1/2 |
| <POSTALCODE> | W | Kod pocztowy. | 00-001 |
| <CITYNAME> | W | Miejscowość. | Warszawa |
| <COUNTRY> | W | Kraj. | Polska |
| <PHONE> | O | Telefon do odbiorcy, na wypadek problemów z doręczeniem. | +48 600 100 200 |
| <PACKQ> | O | Liczba paczek. | 4 |
| <LINK> | O | Link do listu przewozowego (PDF), przy MODEOFTRANSPORT = 2. | https://…/label.pdf |
| <COMMENTS> | O | Uwagi dla kuriera. | Dostawa 8–16 |
Przykład kompletnego pliku
Zamówienie z dwiema pozycjami i wypełnionymi polami opcjonalnymi.
<?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>
Listy przewozowe PDF
Dla każdej nadanej paczki TyreSoft zapisuje w katalogu /tracking dokument przewozowy w formacie PDF.
- Nazwa pliku to numer listu przewozowego, np.
10000000001.pdf. Ten sam numer znajduje się w kolumnieTrackingIdpliku Waybill CSV. - Zamówienie wysłane w kilku paczkach ma kilka plików PDF, po jednym na paczkę.
- Aby przypisać PDF do zamówienia, wyszukaj jego numer w Waybill CSV i odczytaj kolumnę
CustomerRef.
Jak powiązać pliki
<NUMBER>00007993-OW</NUMBER>CustomerRef = 00007993-OWTrackingId = 1000000000110000000001.pdfWłasny kurier partnera (MODEOFTRANSPORT = 2)
Jeśli przesyłkę nadaje kurier zamawiającego, partner przekazuje własny list przewozowy jako adres w polu <LINK> sekcji <DELIVERY>. Pod tym adresem musi być dostępny plik PDF gotowy do wydruku.
Waybill CSV
Plik Waybill CSV łączy numery listów przewozowych z zamówieniami partnera. TyreSoft zapisuje go w katalogu /tracking.
Format pliku
- Separator: średnik
;. Kodowanie UTF-8. Pierwszy wiersz zawiera nagłówki kolumn. - Każdy wiersz kończy się średnikiem.
- Jeden wiersz = jedna paczka (jeden numer listu). Zamówienie wysłane w kilku paczkach zajmuje kilka wierszy.
- Data w kolumnie
DeliveryDatema formatD-M-RRRR, np.21-7-2020. - Nazwa pliku:
waybill_RRRRMMDD_HHMMSS.csv. - Kluczem łączącym z zamówieniem jest
CustomerRef, czyli numer zamówienia partnera.
| Kolumna | Opis | Przykład |
|---|---|---|
| CompanyId | Identyfikator firmy / oddziału TyreSoft. | 100 |
| CustomerId | Numer partnera w systemie TyreSoft. | 100001 |
| DeliveryDate | Data wydania przesyłki (D-M-RRRR). | 21-7-2020 |
| PickingListId | Numer listy kompletacyjnej. | PM1071083 |
| LineNum | Numer pozycji na liście kompletacyjnej. | 1 |
| PackingSlipId | Numer dokumentu wydania (WZ). | PX2120101 |
| OrderId | Numer zamówienia w systemie TyreSoft. | QV200686844 |
| CustomerRef | Numer zamówienia partnera (NUMBER z pliku XML). | 00007993-OW |
| ItemId | Kod towaru. | GY2154516HEFFP |
| EanItemId | Kod EAN towaru. | 5452000571731 |
| QuantityDelivered | Ilość wysłana w tej paczce. | 1 |
| TrackingId | Numer listu przewozowego (= nazwa pliku PDF). | 10000000001 |
| DeliveryMode | Kod przewoźnika / usługi. | GLSPLFR |
Przykład
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;
00008002-OW zostało wysłane w dwóch paczkach, dlatego ma dwa wiersze z różnymi numerami TrackingId.Stany magazynowe CSV
Katalog /stock zawiera zawsze jeden aktualny plik stock.csv. TyreSoft nadpisuje go w ustalonych odstępach czasu pełną listą dostępnych produktów. Plik nie zawiera historii ani zmian przyrostowych.
- Separator średnik
;, kodowanie UTF-8, nagłówki w pierwszym wierszu, kropka jako separator dziesiętny. - Wczytuj zawsze cały plik i traktuj go jako pełny stan: produkt nieobecny w pliku jest niedostępny.
- Wartość z kolumny
Codepodawaj jako<CODE>w zamówieniu XML. - Kolumna
UpdatedAtinformuje, kiedy wygenerowano stan.
| Kolumna | Opis | Przykład |
|---|---|---|
| Code | Kod towaru, używany jako <CODE> w zamówieniu. | GY2154516HEFFP |
| EAN | Kod EAN. | 5452000571731 |
| Name | Nazwa towaru. | Opona 215/45R16 … |
| Quantity | Dostępna ilość w sztukach. | 24 |
| Price | Cena netto partnera. | 289.00 |
| Currency | Waluta ceny. | PLN |
| UpdatedAt | Czas wygenerowania stanu. | 2026-10-31 12:00 |
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
Dobre praktyki
.tmp) i dopiero po zakończeniu zmień rozszerzenie na .xml. Import nie pobierze wtedy niekompletnego pliku./orders_processed. To potwierdzenie przyjęcia zamówienia./orders jest traktowany jako nowe zamówienie. Nie wysyłaj ponownie tego samego zamówienia pod inną nazwą./tracking cyklicznie i zapamiętuj pliki, które już przetworzyłeś.stock.csv.Uruchomienie integracji
- Ustalenie zakresuUzgadniamy identyfikator partnera (
FROM), walutę, sposób dostawy i zakres danych wstock.csv. - Dostęp do serweraPartner otrzymuje login i hasło do serwera z przygotowanymi katalogami.
- Mapowanie produktówPartner pobiera
stock.csvi wiąże kodyCodeze swoim katalogiem. - Zamówienie testowePartner wysyła plik z dopiskiem
TESTw<COMMENTS>i sprawdza jego przeniesienie do/orders_processed. - Start produkcyjnyPo akceptacji testu zamówienia są realizowane standardowo.
Kontakt
W sprawie wdrożenia, danych dostępowych i pytań technicznych: