Integracje i API

Jakie integracje oferuje OptiRoutes?

Wczytywanie zamówień z pliku, FTP lub SFTP

Najprostsza integracja to plik, który firmowy system już eksportuje. Na ekranie zamówień przycisk Wczytaj dostawy odczytuje plik Excel lub CSV; każde pole systemu – adres, nazwę klienta, numer zamówienia, ilość itd. – mapuje się raz na nazwę kolumny, a każdy kolejny plik wczytuje się tak samo. W przypadku pliku TXT o stałej szerokości zamiast nazw kolumn podaje się pozycje znaków. Wiersze można pomijać na podstawie słowa znacznika w uwagach, drugi znacznik może zastępować adres, a firma decyduje, czy istniejący numer zamówienia jest aktualizowany, czy dodawany jako nowy.

Aby wyeliminować ręczną pracę, wystarczy wybrać w ustawieniach automatyczną metodę wczytywania:

• Serwer plików OptiRoutes – firmowy system umieszcza dzienny plik, nazwany datą, w folderze firmy na serwerze FTP lub szyfrowanym serwerze SFTP.
• Własny serwer FTP – OptiRoutes łączy się przy użyciu podanego użytkownika i wczytuje plik nazwany dzisiejszą datą lub ostatnio zaktualizowany plik.
• Automatyczny import i eksport – zamówienia wczytują się samoczynnie, a trasy są od razu planowane, bez żadnego kliknięcia.
• Files API – firmowe oprogramowanie przesyła plik zamówień przez HTTPS, jak opisano poniżej.

Na ekranie klientów plik Excel lub CSV z numerem klienta, nazwą, adresem, czasem postoju oraz godzinami otwarcia i zamknięcia tworzy lub aktualizuje klientów i ich okna czasowe.

Files API: zamówienia do systemu, POD i raporty z systemu

Każda firma w OptiRoutes ma własny prywatny folder plików: wczytywane zamówienia, podpisane dowody dostawy ze zdjęciami i podpisami, eksporty tras i raporty na koniec dnia. Files API pozwala firmowym systemom bezpośrednio odczytywać i zapisywać ten folder przez HTTPS, bez pośredniczącego serwera FTP. Kierownik firmy przełącza się między FTP a API w sekcji Ustawienia → API i pliki i tam tworzy klucze – nie trzeba zgłaszać się do wsparcia, a nowe firmy zaczynają od API.

Wywołania obejmują sprawdzenie klucza, wyświetlenie zawartości folderu, pobieranie, przesyłanie (do 50 MB na plik) i usuwanie przesłanych plików, wyświetlenie plików POD z danego dnia według zamówienia i rodzaju oraz pobranie wszystkich plików POD z danego dnia w jednym pliku ZIP. Przewodnik zawiera przykłady kodu w Pythonie, C# i Node.js oraz skrypt PowerShell, który synchronizuje folder na serwerze firmy z folderem firmy – dzięki temu zespół przyzwyczajony do FTP może pracować tak jak dotąd. Szczegóły w przewodniku po Files API.

Jak zabezpieczone są klucze API?

• Minimalne uprawnienia – każdy klucz otrzymuje tylko potrzebne uprawnienia: wyłącznie podpisane POD, odczyt wszystkich plików lub przesyłanie zamówień i plików do folderu inbox.
• Dozwolone adresy – klucz można ograniczyć do stałych adresów IP serwera firmy.
• Wygasanie i rotacja – klucz może wygasać po określonej liczbie dni; wystarczy utworzyć nowy klucz, przełączyć się, a potem unieważnić stary – bez przestojów.
• Natychmiastowe unieważnienie – unieważniony klucz przestaje działać w ciągu 30 sekund.
• Audyt – każde wywołanie jest rejestrowane z godziną, adresem, plikiem i odpowiedzią i widoczne dla kierownika.
• Bezpieczne przechowywanie – OptiRoutes przechowuje tylko odcisk SHA-256 każdego klucza; połączenia odbywają się przez HTTPS z TLS 1.2 lub nowszym, a klucz ma dostęp wyłącznie do folderu własnej firmy.

Limity: 300 żądań na minutę na klucz, 50 MB na plik, 20 aktywnych kluczy na firmę i do 5000 pozycji w jednym wykazie folderu.

API raportów i przesyłania danych

Na potrzeby narzędzi raportowych i konektorów ERP osobne API pod adresem api-users.optiroutes.com udostępnia dane firmy w postaci raportów i przyjmuje przesyłane dane. Jeden adres i jeden token, wydany przez OptiRoutes dla firmy, obsługują wszystkie wywołania. Na stronie dokumentacji można wkleić token i zobaczyć, które raporty są dostępne oraz jakie jest mapowanie kolumn na koncie: dokumentacja API.

Dwa wywołania przesyłające działają w przeciwnym kierunku: przesłanie zamówień zapisuje plik zamówień z danego dnia i uruchamia automatyczne wczytywanie, a przesłanie kierowców, linii i pojazdów zastępuje całą flotę, podobnie jak plik floty. Ponieważ przesłana lista kierowców jest traktowana jako pełna flota, zawsze należy wysyłać wszystkich kierowców, a nie tylko zmiany.

Eksport tras i webhooki

Eksport tras zapisuje zaznaczone trasy w formatach CSV, XLSX, XML, JSON lub TXT o stałej szerokości. Tabela kolumn określa, które pola są eksportowane i pod jakim nagłówkiem, można dodać oryginalne kolumny z pliku zamówień, a przy zarządzaniu pozycjami drugi plik wymienia każdą pozycję. Eksport może trafić na komputer, na własny serwer FTP lub do folderu firmy, a w formacie JSON można go także wysłać pod adres internetowy; jeśli wysyłka się nie powiedzie, system próbuje jeszcze raz.

Aby otrzymywać każdą dostawę na bieżąco, wystarczy uzupełnić adres raportów dostaw w ustawieniach aplikacji kierowcy: każdy raport dostawy sporządzony przez kierowców jest wysyłany także tam, dzięki czemu inny system firmy aktualizuje się samoczynnie.

E-mail, płatności, mapy i komunikacja

• E-mail – podpisane dowody dostawy są wysyłane z własnego konta Gmail firmy przy użyciu hasła do aplikacji Google; raporty, takie jak raport palet na koniec dnia, trafiają na adres e-mail raportów; płacący klienci otrzymują z kasy potwierdzenia wpłaty, a kierowcy – potwierdzenia rozliczenia.
• Płatności – doładowania opłaca się na bezpiecznej stronie płatności Stripe, z opcjonalnie zapisaną kartą do automatycznego doładowania.
• Adresy i mapy – adresy wybiera się z podpowiedzi Google i weryfikuje na mapie przed planowaniem.
• Nawigacja – aplikacja kierowcy przekazuje każdy przystanek do Waze lub do Map Apple na iPhonie, według adresu lub dokładnych współrzędnych.
• SMS i WhatsApp – wiadomości o przyjeździe i linki do śledzenia dla klientów, alerty dla kierowników, linie dla podwykonawców i obrazy tras dla kierowców przez WhatsApp.

Najczęściej zadawane pytania