Español
English
Català
Deutsch
Français
Português
Italiano
Nederlands
Opublikowaliśmy konektory MRW, SEUR, Correos Express, DHL, GLS, UPS i CTT dla Odoo oraz zintegrowaliśmy przewoźników na stronach, za którymi nie stoi Odoo, takich jak eclipseando.com. API różnią się nazwami i formatem, ale praca jest zawsze taka sama: cztery wywołania, trzy lub cztery powtarzające się błędy i jedna decyzja architektoniczna, którą warto podjąć przed napisaniem pierwszej linii kodu. Ten artykuł dotyczy wersji dla własnej strony; jeśli Twój sklep działa na Odoo, większość tych rzeczy jest już rozwiązana w konektorach przewoźników.
Kluczowa myśl: integracja nie kończy się, gdy powstaje etykieta. Kończy się, gdy klient dostaje powiadomienie, że jego paczka jest w drodze albo czeka w punkcie odbioru, a nikt z Twojego zespołu niczego nie przepisywał. Jeśli zaprojektujesz tylko etykietę, resztę będziesz robić ręcznie.
Zanim zaczniesz programować: umowa i środowisko testowe
Żaden przewoźnik nie da Ci dostępu do swojego API za wypełnienie formularza na stronie. Potrzebna jest umowa transportowa z handlowcem, a z niej wynikają dane dostępowe: kod klienta lub abonenta, użytkownik i hasło lub klucz, a czasem kod franczyzy lub oddziału. Poproś o nie od pierwszego dnia i poproś także o środowisko testowe, którego nie mają wszyscy i które nie zawsze zachowuje się jak produkcja. Niektóre API to nadal SOAP z XML (tak jest historycznie u kilku hiszpańskich przewoźników), inne to REST z JSON. Nie zmienia to tego, co trzeba zrobić, zmienia tylko, ile kosztuje czytanie dokumentacji.
Cztery wywołania
| Wywołanie | Co wysyłasz | Co dostajesz w odpowiedzi | Gdzie się psuje |
|---|---|---|---|
| Utworzenie przesyłki | Nadawca, odbiorca, paczki, waga, usługa, odnośnik zamówienia. | Numer przesyłki i prawie zawsze etykieta w tej samej odpowiedzi. | Adresy bez normalizacji, kody pocztowe z Wysp Kanaryjskich lub Balearów, numery telefonów ze spacjami, znaki spoza ASCII. |
| Etykieta | Numer przesyłki i format (PDF, ZPL, rozmiar). | Plik, zwykle w base64. | Pobranie jej dwa razy i utworzenie dwóch przesyłek; wydruk na A4 tego, co miało być 10×15. |
| Śledzenie | Numer przesyłki. | Lista zdarzeń z datą, kodem i opisem. | Odpytywanie co minutę i odcięcie przez przewoźnika; brak przełożenia kodów na własne statusy. |
| Manifest / zamknięcie dnia | Data i przesyłki z danego dnia. | Potwierdzenie lub dokument odbioru. | Zapomnienie o nim: przewoźnik nie odbiera tego, co nie zostało zamanifestowane. |
Utworzenie przesyłki: połowa pracy to czyszczenie adresu
To właśnie przy tworzeniu przesyłki koncentruje się najwięcej odrzuceń. Każdy przewoźnik ma własne wyobrażenie o poprawnym adresie: maksymalna długość ulicy, kod pocztowy z dokładnie pięciu cyfr, prowincja jako kod, a nie tekst, telefon obowiązkowy i bez prefiksu, a u kilku nic spoza ASCII w nazwie. Sprawdza się normalizacja przed wywołaniem: rozdzielenie ulicy i numeru, przycięcie pól do maksimum akceptowanego przez dane API, zastąpienie znaków diakrytycznych tam, gdzie API ich nie przyjmuje, oraz sprawdzenie, czy kod pocztowy istnieje dla danego kraju. I zawsze zapisuj pełne żądanie i odpowiedź, w XML lub JSON, razem z zamówieniem. Gdy paczka zaginie trzy tygodnie później, ten ślad jest jedynym dowodem tego, co zostało wysłane.
Śledzenie: rozsądne odpytywanie albo webhook, jeśli jest dostępny
Niewielu przewoźników powiadamia przez webhook; większość trzeba odpytywać. Prawidłowe rozwiązanie to zaplanowane zadanie, które sprawdza wyłącznie otwarte przesyłki, w rozsądnym odstępie (zwykle wystarcza co godzinę, częściej w dniu dostawy), przestaje, gdy status jest końcowy, i przestrzega limitów API. Kody zdarzeń przekłada się na niewielki zestaw własnych statusów: przyjęta, w tranzycie, w doręczeniu, doręczona, incydent, zwrócona. Pięć lub sześć, nie czterdzieści. A każda zmiana statusu uruchamia powiadomienie klienta, bo po to jest to wszystko.
Gdy nie masz API, bo wysyła Twój dostawca
To częstsze, niż się wydaje: sprzedajesz Ty, ale paczkę przygotowuje i wysyła dostawca z własną umową transportową. Nie masz danych dostępowych, nie możesz utworzyć przesyłki ani jej sprawdzić. Prawie zawsze masz za to maile, które przewoźnik wysyła na adres kontaktowy przy każdym ruchu paczki. Na eclipseando.com rozwiązaliśmy to tak z GLS: zadanie czyta skrzynkę co dziesięć minut, rozpoznaje cztery rodzaje maili (w drodze, w doręczeniu, w punkcie odbioru z terminem, odbiorcy nie zastano), wyciąga numer przesyłki i zamówienie, do którego należy, i zamienia każdy z nich na status oraz powiadomienie dla kupującego. Dwa ostatnie są pilne: paczka w punkcie odbioru wraca do nadawcy, jeśli nikt jej nie odbierze, a klient, który nie wie, że tam leży, po nią nie pójdzie.
Błędy, które widzimy na produkcji
- Testowanie wyłącznie na sandboxie. Kilku przewoźników ma środowisko testowe, które przyjmuje to, co produkcja odrzuca. Test, który się liczy, to prawdziwa przesyłka do Twojego własnego biura.
- Tworzenie przesyłki w chwili potwierdzenia zamówienia na stronie. Przesyłkę tworzy się przy przygotowaniu paczki. Jeśli powstanie wcześniej, każde anulowanie to przesyłka-widmo, za którą czasem wystawiana jest faktura.
- Niezapisywanie żądania i odpowiedzi. Bez pełnego XML lub JSON przy zamówieniu reklamacja to Twoje słowo przeciwko słowu przewoźnika.
- Jeden numer śledzenia na zamówienie. Działa do pierwszego zamówienia z dwiema paczkami lub dwoma dostawcami. Śledzenie modeluje się per przesyłka.
- Stare certyfikaty i szyfrowanie. Niektóre API nadal działają na TLS z szyframi, które nowoczesne biblioteki domyślnie odrzucają. Wychodzi to pierwszego dnia, a nie w dniu uruchomienia.
Gdy za stroną stoi Odoo, prawie nic z tego się nie programuje
Jeśli sklep działa na Odoo, te cztery wywołania są już napisane w konektorach, które publikujemy w App Store, przetestowanych na Odoo 19, 18 i 17 na prawdziwym Odoo.sh: etykieta powstaje przy zatwierdzeniu dokumentu dostawy, śledzenie jest odpytywane przez cron i zapisywane w dokumencie dostawy, manifest zamyka się z poziomu samego Odoo, a powiadomienie klienta wychodzi mailem lub SMS-em z wybranym przez Ciebie szablonem. Strona musi tylko odczytywać status dokumentu dostawy. Dlatego gdy ktoś prosi nas o integrację przewoźnika ze stroną, a ma już Odoo, odpowiedzią zwykle jest podłączenie strony do ERP, a nie ponowne pisanie integracji.
Najczęstsze pytania
Ile trwa integracja przewoźnika?
Zależy głównie od dwóch rzeczy, których nie kontrolujesz: jak długo przewoźnik będzie przygotowywał dla Ciebie dane dostępowe i środowisko testowe oraz czy jego API to REST z aktualną dokumentacją, czy SOAP z PDF-em sprzed lat. Same cztery wywołania to praca ograniczona; wydłużają ją oczekiwanie i testy na prawdziwych przesyłkach.
Czy można zintegrować kilku przewoźników naraz?
Tak, i warto zaprojektować to tak od początku: własna warstwa z czterema operacjami (utworzenie, etykieta, śledzenie, manifest) i adapter dla każdego przewoźnika pod spodem. Dodanie drugiego kosztuje ułamek pierwszego, jeśli pierwszy zbudowano z takim rozdzieleniem.
A jeśli mój dostawca wysyła swoim przewoźnikiem, a ja nie mam dostępu?
Pracuje się z tym, co przychodzi: z mailami przewoźnika lub plikami, które zwraca dostawca. Automatyczne czytanie ich i zamiana na statusy i powiadomienia nie jest tak czysta jak API, ale eliminuje ręczne przepisywanie i, przede wszystkim, zapobiega sytuacji, w której klient nie wie, że jego paczka czeka w punkcie odbioru.
Przydatne linki w FlexigoTech
Co robimy w tym zakresie
Musisz podłączyć przewoźnika i nie wiesz, od czego zacząć?
Napisz nam, o którego przewoźnika chodzi, czy masz już dane dostępowe i czy za stroną stoi Odoo. Powiemy Ci, co trzeba zaprogramować, co już istnieje i o co poprosić przewoźnika przed startem. Napisz na comercial@flexigobe.com lub zadzwoń pod numer +34 616 809 504.