Integracja FTP / SFTP

SPIS TREŚCI

• 1. Opis ogólny
• 2. Model działania
• 3. Wymagania po stronie integratora
  • 3.1. Serwer
  • 3.2. Dane dostępowe
• 4. Konfiguracja po stronie Z24
  • Pola:
• 5. Format i nazewnictwo plików
  • 5.1. Nazwa pliku
  • 5.2. Lokalizacja docelowa
• 6. Dostępne formaty plików
  • Przykładowe formaty:
    • 6.1. XML
    • 6.2. CSV
    • 6.3. TXT (stała szerokość)
    • 6.4. EDI
    • 6.5. Excel
• 7. Struktura danych (przykład XML)
• 8. Obsługa błędów
  • 8.1. Możliwe błędy
  • 8.2. Zachowanie systemu
• 9. Mechanizm kolejkowania
• 10. Timeouty i ograniczenia
• 11. Bezpieczeństwo
  • Zalecenia:
• 12. Tryb pasywny FTP
• 13. Rozszerzalność
• 14. Testy integracyjne
• 15. Kontakt techniczny

1. Opis ogólny

System Zamawiaj24 umożliwia automatyczne przekazywanie zamówień do systemów zewnętrznych poprzez:

• FTP (port domyślny 21)
• SFTP (port domyślny 22)

Pliki są generowane w systemie Z24, a następnie wysyłane na wskazany serwer kontrahenta (dystrybutora).

Wysyłka odbywa się asynchronicznie przez kolejkę.

2. Model działania

1. Zamówienie zostaje utworzone w systemie Z24
2. Generowany jest plik eksportu (np. XML, CSV, TXT, EDI)
3. Tworzony jest wpis w kolejce wysyłki na serwer ftp
4. Plik jest wysyłany na serwer FTP/SFTP
5. Status eksportu jest aktualizowany:
   • sent – sukces
   • failed – błąd

3. Wymagania po stronie integratora

Integrator musi udostępnić:

3.1. Serwer

• FTP lub SFTP
• Publicznie dostępny adres hosta (IP lub domena)
• Otwarty port:
  • FTP: 21
  • SFTP: 22 (lub inny, jeśli niestandardowy)

3.2. Dane dostępowe

Wymagane:

• host
• port (opcjonalny – jeśli brak, używany jest domyślny)
• login
• hasło
• ścieżka docelowa (remote_path)

Opcjonalne:

• tryb pasywny FTP (passive_mode, domyślnie true)

4. Konfiguracja po stronie Z24

Każdy serwer FTP/SFTP jest definiowany w tabeli:

team_ftp_servers

Pola:

• host – adres serwera
• port – port
• login – użytkownik
• password – hasło
• remote_path – katalog docelowy
• protocol – ftp lub sftp
• passive_mode – tylko dla FTP

5. Format i nazewnictwo plików

5.1. Nazwa pliku

Plik posiada nazwę:

[file_name]

Przykłady:

ZAM-2026-000123.xml
ZAM-2026-000123.csv
ZAM-2026-000123.edi

5.2. Lokalizacja docelowa

Plik zapisywany jest jako:

[remote_path]/[file_name]

Przykład:

/incoming/orders/ZAM-2026-000123.xml

6. Dostępne formaty plików

System obsługuje wiele formatów eksportu. Każdy format posiada:

• code – identyfikator techniczny
• file_ext – rozszerzenie
• mime_type
• template_engine

Przykładowe formaty:

6.1. XML

• UNIVERSAL_B2B_ORDER_XML
• COMARCH_OPTIMA_XML

6.2. CSV

• COMARCH_OPTIMA_CSV

6.3. TXT (stała szerokość)

• TXT_FIXED_WIDTH
• TXT_FIXED_WIDTH_AGRA

6.4. EDI

• EDIFACT_D96A

6.5. Excel

• EXCEL_EXACT

7. Struktura danych (przykład XML)

Przykład uproszczony:

<Order>
  <Header>
    <OrderNumber>ZAM-2026-000123</OrderNumber>
    <OrderDate>2026-05-01</OrderDate>
  </Header>

  <Buyer>
    <ExternalId>12345</ExternalId>
    <Name>Sklep ABC</Name>
    <NIP>1234567890</NIP>
  </Buyer>

  <Items>
    <Item>
      <LineNo>1</LineNo>
      <EAN>5901234123457</EAN>
      <Quantity>10</Quantity>
    </Item>
  </Items>
</Order>

Dokładna struktura zależy od wybranego formatu.

8. Obsługa błędów

8.1. Możliwe błędy

• brak połączenia z serwerem
• błędne dane logowania
• brak katalogu docelowego
• timeout połączenia
• błąd zapisu pliku

8.2. Zachowanie systemu

W przypadku błędu:

• status eksportu → failed
• zapisywany jest komunikat błędu
• możliwe jest ponowne przetworzenie (retry)

9. Mechanizm kolejkowania

System używa mechanizmu:

FOR UPDATE SKIP LOCKED

Dzięki temu:

• wiele workerów może działać równolegle
• brak konfliktów przy pobieraniu rekordów

Statusy:

• pending – oczekuje
• processing – w trakcie
• sent – wysłane
• failed – błąd

10. Timeouty i ograniczenia

• Timeout SFTP: 90 sekund
• Timeout połączenia SSH: 30 sekund
• Przetwarzanie batchowe (domyślnie): 10 rekordów

11. Bezpieczeństwo

Zalecenia:

• preferowane SFTP zamiast FTP
• ograniczenie dostępu IP do serwera
• dedykowane konto użytkownika
• brak dostępu do innych katalogów

12. Tryb pasywny FTP

Jeżeli integrator korzysta z FTP:

• zalecany tryb pasywny (passive_mode = true)
• wymagane otwarte porty pasywne po stronie serwera

13. Rozszerzalność

System został zaprojektowany tak, aby:

• łatwo dodawać nowe formaty plików
• obsługiwać kolejne protokoły w przyszłości
• rozszerzać logikę eksportu bez zmian po stronie integratora

14. Testy integracyjne

Rekomendowany proces:

1. konfiguracja środowiska testowego FTP/SFTP
2. wysyłka testowego zamówienia
3. weryfikacja:
   • czy plik pojawił się na serwerze
   • czy format jest poprawny
4. testy błędów (np. złe hasło)

15. Kontakt techniczny

W przypadku problemów z integracją:

• prosimy o przekazanie:
  • daty i godziny problemu
  • nazwy pliku
  • adresu serwera
  • komunikatu błędu