Integracje kurierskie w Open Mercato: wysyłka, tracking i uzgodnienie

Cztery wybory menedżera

Zapisz autorytet, stan możliwości, dowód, ownera, ścieżkę wyjątku, odbiór i obowiązkowy stop.

Migawka dowodów i legenda

Sprawdzono: 2026-07-14 · branch: develop · revision: 01911d00e28f44cf484d0b1d04860dcfef5370bf · describe: v0.6.5-1202-g01911d00e · wersja root: 0.6.5 · najnowszy tag publiczny: v0.6.5 · dystans: 1,202 commits

Zachowanie po tagu jest oznaczone current develop. Możliwość używa dokładnie czterech stanów, a dowód sześciu osobnych etykiet. Gotowość ma cztery osobne wyniki: verified, conditional, unverified lub stop.

• available
• configurable
• custom
• integration-required

• latest public release
• current develop
• current first-party documentation
• specification or plan
• external primary requirement
• editorial recommendation

Łańcuch dziewięciu rekordów wysyłki

Nie łącz tych rekordów w jeden status. Każde wdrożenie musi nazwać system źródłowy, trwałą tożsamość, właściciela statusu, czasy, mechanizm zmiany, dane wrażliwe, klucz uzgodnienia, właściciela wyjątku i dowód.

Dwa rejestry przesyłek wymagają jawnego join

SalesShipment należy do zamówienia, ma ilości SalesShipmentItem, a jego komenda sales przelicza fulfilled quantity każdej linii zamówienia. Może przechowywać metodę sales, status słownikowy, nazwę przewoźnika, numery tracking, czasy shipped i delivered, wartości deklarowane, notatki, snapshot adresu i korekty.

CarrierShipment zapisuje orderId, providerKey, carrierShipmentId, trackingNumber, unifiedStatus, surowy carrierStatus, labelUrl lub labelData, trackingEvents, lastWebhookAt, lastPolledAt, zakres tenantu i organizacji oraz czasy cyklu. Bieżące carrier create wywołuje adapter i zapisuje CarrierShipment; nie tworzy SalesShipment ani wierszy SalesShipmentItem i nie aktualizuje fulfilled quantities.

CarrierShipment jest powiązany z zamówieniem i nie ma sprawdzonego pola salesShipmentId. Bieżący enricher odpowiedzi wybiera latest carrier shipment per order przy dekorowaniu odpowiedzi sales shipment. Wiele sales shipments, paczek lub etykiet kurierskich wymaga więc trwałej korelacji właściwej wdrożeniu, kardynalności, polityki split/merge, uzgodnienia i kolejki wyjątków. Latest per order stanowi dowód prezentacji. Sprawdzone dowody nie potwierdzają inwariantu jeden-do-jednego.

Dwie ścieżki operatora pozostają osobne

Samodzielna route wizarda służy wdrożeniu. Nie potwierdza pełnej konsoli wysyłkowej ani dowodów pick, pack, weryfikacji adresu, zamknięcia manifestu, bookingu odbioru, cła, customer self-service lub dostawy. Wiele paczek nie zapewnia mapowania item-to-parcel, cartonization ani egzekwowania pakowania.

Inventory providerów zapisuje dowody. Obecność na liście nie potwierdza obsługi kuriera.

Przykład w dokumentacji, provider key w teście, nazwa pakietu, stare wydanie, implementacja interface lub publikacja npm nie potwierdzają instalacji, domyślnej aktywacji, stabilności, wsparcia, zgodności, stanu ani gotowości produkcyjnej providera.

Scorecard gotowości providera

Dla każdego kandydata sklasyfikuj każdy wiersz jako verified, conditional, unverified lub stop z datą dowodu, wersją docelową, ownerem, ograniczeniem i następnym testem. Nigdy nie uśredniaj obowiązkowego stop do marketingowej odznaki.

Wymagane: wynik, dowód, owner, awaria, recovery i odbiór.

• 1. Pochodzenie pakietu
• 2. Zgodność wersji i peer
• 3. Instalacja i build
• 4. Migracje bazy
• 5. Aktywacja w aplikacji docelowej
• 6. Model poświadczeń
• 7. Health check
• 8. Umowa i konto kurierskie
• 9. Stawki sandbox
• 10. Punkty nadania lub odbioru
• 11. Utworzenie przesyłki
• 12. Formaty etykiet i ścieżka druku
• 13. Mapowanie tracking
• 14. Weryfikacja webhooka
• 15. Recovery pollingiem
• 16. Anulowanie
• 17. Redakcja błędów i detal wsparcia
• 18. Obserwowalność i alerty
• 19. Recovery sierot i duplikatów
• 20. Prywatność i retencja
• 21. Właściciel utrzymania
• 22. Wsparcie i eskalacja

Metody adaptera definiują wspólny seam integracyjny

Sprawdź konkretną implementację providera, poświadczenia, błędy, limity i skutek biznesowy. Sygnatura metody nie dowodzi kwalifikacji konta, coverage, terminowości ani compliance.

• 1. calculateRates: usługi providera, kwota, waluta i opcjonalne sygnały czasu
• 2. createShipment: przesyłka providera, tracking i odpowiedź etykiety
• 3. getTracking: bieżący status providera i zdarzenia
• 4. cancelShipment: wynik anulowania u providera
• 5. verifyWebhook i mapStatus: zaufane wejście zdarzenia providera i normalizacja
• 6. searchDropOffPoints, opcjonalnie: wyniki punktów providera

Validator create wymaga provider key, order id o kształcie UUID, miejsca nadania, miejsca docelowego, co najmniej jednej paczki o dodatnich wymiarach i kodu usługi, a dopuszcza format etykiety, kontakty, target point, sending method i opcjonalny klucz idempotencji. Te kontrole obejmują strukturę danych wejściowych. Nie potwierdzają walidacji adresu u kuriera, prawdy o pakowaniu, dangerous-goods clearance ani kwalifikacji usługi.

Zachowaj siedem osobnych rekordów kosztu wysyłki

• Oferta stawki providera
• Stawka wybrana przez operatora
• Korekta kosztu wysyłki w sales
• Obciążenie providera
• Faktura przewoźnika
• Zwrot lub credit kosztu wysyłki
• Zapis księgowy

Stawka providera zawiera kod i nazwę usługi, kwotę, walutę, opcjonalne estimated days i opcjonalny guaranteed-delivery flag dla przesłanych danych. Nie potwierdza ważności negocjowanej, podatków, dopłat paliwowych lub remote-area, wagi gabarytowej, cła, customs, ubezpieczenia, pobrania, wygaśnięcia ceny, faktury końcowej ani dostępności przy odbiorze. Wybrana stawka nie jest zapisana w CarrierShipment i nie potwierdzono automatycznej korekty kosztu wysyłki w sales.

Zapisz wejście, oczekiwane źródło, expiry, właściciela rozbieżności, zabronione założenie i dowód uzgodnienia.

• 1. Umowa i konto
• 2. Miejsce nadania
• 3. Miejsce docelowe
• 4. Wymiary i waga paczki
• 5. Kod usługi
• 6. Waluta
• 7. Podatki i dopłaty
• 8. Waga gabarytowa
• 9. Wygaśnięcie stawki
• 10. Niedostępna usługa
• 11. Timeout i retry
• 12. Zmieniona cena końcowa

Idempotencja create jest lokalna i ograniczona

Unikalny scoped claim wiąże idempotency key, provider key, request hash i późniejsze lokalne id przesyłki. Równe powtórzenie z tym samym kluczem może zwrócić istniejący rekord lokalny; ponowne użycie z innym payload daje konflikt; nierozwiązany równoległy claim daje konflikt. Wybrane awarie zwalniają claim tylko wtedy, gdy kurier nie został skutecznie wywołany. Jeśli call providera się powiedzie, a lokalny zapis potem zawiedzie, claim pozostaje, aby ograniczyć duplikat upstream.

Sprawdzone wejście adapter create nie zawiera klucza idempotencji. Provider-side exactly-once i automatyczne recovery przesyłki upstream bez rozwiązanego rekordu lokalnego nie są potwierdzone. Wymagaj provider request id lub kontroli idempotencji, gdy jest dostępna, korelacji request/response, wykrywania sierot, kontroli duplikatów etykiet, codziennego uzgodnienia, ręcznego recovery i nazwanych właścicieli dowodów.

Cykl etykiety jest decyzją operacyjną i danych

Przypisz cel, czytelnika, writer, processor, dowód, ścieżkę incydentu i warunek stop.

• 1. Źródło providera i żądanie
• 2. Format PDF, ZPL lub PNG
• 3. Zapis URL lub danych inline
• 4. Dostęp do odczytu i pobrania
• 5. Drukarka i ścieżka spool
• 6. Autoryzacja ponownego druku
• 7. Void i zastąpienie
• 8. Okres i cel retencji
• 9. Usunięcie i eksport
• 10. Backup i recovery
• 11. Czyszczenie urządzenia współdzielonego
• 12. Incydent i właściciel dowodu

CarrierShipment zapisuje bezpośrednio labelUrl lub labelData. W sprawdzonych plikach shipping-carrier nie potwierdzono module-specific default encryption map, migracji do attachments, zgodnej z prawem retencji, bezpiecznej drukarki, automatycznego unieważnienia ani usunięcia. Osobno sprawdź kontrole generic platform, storage, infrastruktury i providera.

Traktuj znormalizowany status jako stan zgłoszony przez providera

Zdarzenia providera mogą być opóźnione, zduplikowane, brakujące, poza kolejnością, nieprawidłowo zmapowane lub później skorygowane. Bieżące reguły przejść pozwalają na recovery z failed_delivery i chronią wybrane stany terminalne. Lokalne delivered zapisuje znormalizowany stan zgłoszony przez providera. Sprawdzone dowody nie potwierdzają tożsamości odbiorcy, dokumentu proof-of-delivery, akceptacji klienta, zakończenia sales, revenue recognition ani zamknięcia support lub księgowości.

GET, refresh, webhook i polling są różnymi kontrolami

Wsparcie webhooka zależy od providera i nie gwarantuje kompletnego, uporządkowanego, terminowego ani exactly-once dostarczenia. Błędy providera są logowane server-side i na sprawdzonych ścieżkach pokazywane callerowi jako błędy ogólne. Zapewnia to ograniczoną redakcję. Nie gwarantuje obserwowalności ani recovery. Webhook, polling, codzienne uzgodnienie i ręczne recovery tworzą model operacyjny.

Podaj setup, zdarzenie providera, oczekiwany stan lokalny, zabronioną regresję, dowód kolejki, replay, poll recovery i ownera.

• 1. Nieprawidłowy podpis
• 2. Nieznany provider
• 3. Nieznana przesyłka
• 4. Duplikat zdarzenia
• 5. Opóźnione zdarzenie
• 6. Zdarzenie poza kolejnością
• 7. Regresja stanu terminalnego
• 8. Awaria kolejki
• 9. Awaria workera
• 10. Replay po recovery
• 11. Recovery pollingiem

Anulowanie nie kończy fizycznego recall ani odwrócenia finansowego

Hub sprawdza dozwolone przejście lokalne, wysyła żądanie providera, zapisuje wynik providera i emituje cancellation. Traktuj osobno jako dowody: żądanie anulowania, akceptację providera, label void, cutoff odbioru, przechwycenie paczki, stan lokalny, credit kosztu, odwrócenie SalesShipment, fulfilled quantity, zwolnienie magazynu, powiadomienie klienta i wynik księgowy.

Wymagaj dowodu providera i lokalnego, wyniku operatora, recovery, wyniku kosztu i uzgodnienia.

• 1. Przed odbiorem
• 2. Po odbiorze
• 3. Po doręczeniu
• 4. Duplikat żądania
• 5. Timeout providera
• 6. Niejednoznaczna odpowiedź providera
• 7. Uzgodnienie po awarii

Punkty i paczki pozostają zależne od providera i magazynu

Opcjonalne searchDropOffPoints może zwrócić punkty providera dla query, type lub postcode. Wynik nie potwierdza świeżości, kompletności geograficznej, godzin otwarcia, accessibility, capacity, zapisanej tożsamości wyboru, publicznego checkout UX ani dostępności usługi. Każdy wybrany punkt zapisz i uzgadniaj jawnie.

Pick, pack, ruch stock, skład paczki, skany, wymiary, waga i fizyczny handoff pozostają kanoniczne dla właściciela inventory lub WMS. SalesShipment, fulfilled quantity, SalesReturn, refund, credit memo i invoice pozostają kanoniczne dla sales i finansów. E-mail, SMS, dostarczenie wiadomości klienta i publiczny tracking UX pozostają kanoniczne dla właścicieli komunikacji lub portalu. Carrier returned nie tworzy automatycznie żadnego z tych wyników.

Macierz możliwości i dowodów

Dla każdego wiersza zapisz jeden stan możliwości, jedną etykietę dowodu, bieżącą powierzchnię, zależność od providera, ograniczenie, ownera, confidence i następny test. Sprawdzony hub sam nie zapewnia tych typowych wyników oprogramowania wysyłkowego.

Wynik domyślny: integration-required, dopóki świeży zgodny dowód produktu lub providera nie potwierdzi inaczej.

• 1. Batchowe tworzenie etykiet
• 2. Wave picking
• 3. Cartonization
• 4. Stanowisko pakowania i skanery
• 5. Agent drukarki
• 6. Manifesty
• 7. Planowanie odbioru przez kuriera
• 8. Porównanie wielu kurierów w jednym żądaniu
• 9. Reguły routingu i substytucja usług
• 10. Walidacja lub korekta adresu
• 11. Proces towarów niebezpiecznych
• 12. Dokumenty celne międzynarodowe
• 13. Cła i podatki
• 14. Ubezpieczenie i roszczenia
• 15. Pobranie
• 16. Proof of delivery
• 17. Brandowana strona tracking
• 18. Proaktywne powiadomienia klienta
• 19. Analityka SLA kuriera
• 20. Audyt faktur przewoźnika
• 21. Freight, LTL i wysyłki paletowe
• 22. Etykiety zwrotne i portal zwrotów klienta

Słownik dostępu i macierz odpowiedzialności

Bieżące features to shipping_carriers.view i shipping_carriers.manage. Default setup nadaje oba superadmin i admin, a view pracownikowi. Rates, create, cancel i zapisujący refresh wymagają manage; tracking i lookup punktów wymagają view. Dwa feature ids nie zapewniają least-privilege separation między porównaniem stawek, zakupem etykiet, anulowaniem, widokiem etykiet i PII, administracją poświadczeniami, recovery wyjątków, akceptacją refund i uzgodnieniem faktury przewoźnika. Zaprojektuj i przetestuj zabronione kombinacje jawnie.

Przypisz responsible, accountable, consulted i informed, zastępstwo, segregation, dowód, authority wyjątku i release sign-off.

• 1. Zwolnienie zamówienia
• 2. Prawda o pozycji i paczce magazynowej
• 3. Wybór providera
• 4. Administracja poświadczeniami
• 5. Polityka stawek
• 6. Dostęp i druk etykiet
• 7. Odbiór i fizyczny handoff
• 8. Wyjątki tracking
• 9. Obsługa klienta i powiadomienia
• 10. Zwroty i inspekcja
• 11. Uzgodnienie kosztów wysyłki
• 12. Prywatność i retencja
• 13. Bezpieczeństwo i reakcja na incydent
• 14. Odbiór wydania i rollback

Zakres, bezpieczeństwo i rejestr danych wrażliwych

Poświadczenia są rozwiązywane przez integration credential service w zakresie tenantu i organizacji. Lookup tracking odpytuje providera dopiero po znalezieniu lokalnej przesyłki należącej do tego zakresu, a zakres webhooka wynika z zapisanych kandydatów i zweryfikowanych scoped credentials. Sprawdzone kontrole obejmują wymienione ścieżki. Nie zapewniają uniwersalnego assurance izolacji, secure configuration, prywatności, retencji ani compliance przewoźnika.

Przypisz cel, minimum collection, reader, processor i transfer, retencję, usunięcie i eksport, backup, ekspozycję search i log, dowód szyfrowania i właściciela incydentu.

• 1. Adresy nadania i docelowe
• 2. Kontakty nadawcy i odbiorcy
• 3. Numery tracking i identyfikatory przesyłek
• 4. Czasy i lokalizacje tracking
• 5. Dane etykiet, URL i kody
• 6. Poświadczenia providera i referencje konta
• 7. Logi aplikacji i providera
• 8. Rekordy przesyłek u providera
• 9. Wiadomości klienta i linki tracking

Trzy syntetyczne architektury

Zapisz rejestry, wybór architektury, stany możliwości, dowody providera, ownerów, awarie, uzgodnienie, odbiór, stops i następny krok.

Słabe dopasowanie bez dodatkowych systemów specjalistycznych

• Gotowy WMS: w sprawdzonym hubie brakuje kompletnego procesu domenowego, kontroli i dowodów. Zachowaj autorytet specjalistyczny lub zweryfikuj integrację dla wdrożenia.
• Wysokowolumenowe stanowisko pakowania: w sprawdzonym hubie brakuje kompletnego procesu domenowego, kontroli i dowodów. Zachowaj autorytet specjalistyczny lub zweryfikuj integrację dla wdrożenia.
• Cło międzynarodowe: w sprawdzonym hubie brakuje kompletnego procesu domenowego, kontroli i dowodów. Zachowaj autorytet specjalistyczny lub zweryfikuj integrację dla wdrożenia.
• Towary niebezpieczne: w sprawdzonym hubie brakuje kompletnego procesu domenowego, kontroli i dowodów. Zachowaj autorytet specjalistyczny lub zweryfikuj integrację dla wdrożenia.
• Freight lub LTL: w sprawdzonym hubie brakuje kompletnego procesu domenowego, kontroli i dowodów. Zachowaj autorytet specjalistyczny lub zweryfikuj integrację dla wdrożenia.
• Optymalizacja tras: w sprawdzonym hubie brakuje kompletnego procesu domenowego, kontroli i dowodów. Zachowaj autorytet specjalistyczny lub zweryfikuj integrację dla wdrożenia.
• Zakup usług przewoźników: w sprawdzonym hubie brakuje kompletnego procesu domenowego, kontroli i dowodów. Zachowaj autorytet specjalistyczny lub zweryfikuj integrację dla wdrożenia.
• Portal zwrotów klienta: w sprawdzonym hubie brakuje kompletnego procesu domenowego, kontroli i dowodów. Zachowaj autorytet specjalistyczny lub zweryfikuj integrację dla wdrożenia.
• Audyt faktur przewoźnika: w sprawdzonym hubie brakuje kompletnego procesu domenowego, kontroli i dowodów. Zachowaj autorytet specjalistyczny lub zweryfikuj integrację dla wdrożenia.

Tabela stop lub go

Ustal verified evidence, ownera, próg, wyjątek, recovery i obowiązkowy stop. Unknown oznacza stop.

• 1. Zgodność pakietu providera
• 2. Umowa kurierska i poświadczenia
• 3. Mapowanie zamówienia i przesyłki
• 4. Autorytet magazynu
• 5. Ścieżka drukarki i etykiety
• 6. Recovery webhooka i pollera
• 7. Prywatność i retencja
• 8. Własność obsługi klienta
• 9. Handoff zwrotu
• 10. Uzgodnienie kosztu
• 11. UAT i testy awarii
• 12. Steward operacyjny i zastępstwo

Pakiet odbioru

Podaj setup, abstrakcyjne ids, sekwencję stanów, dowód providera i lokalny, failure injection, zabroniony wynik, recovery, uzgodnienie, ownera i kryterium pass.

• 1. Izolacja draft route
• 2. Aktywacja modułu default
• 3. Aktywacja providera official
• 4. Pola SalesShipment
• 5. Fulfilled quantity pozycji przesyłki
• 6. Pola CarrierShipment
• 7. Brak korelacji salesShipmentId
• 8. Enrichment najnowszego carrier per order
• 9. Ręczna ścieżka sales
• 10. Wizard uruchamiany z zamówienia
• 11. Prefill miejsca docelowego
• 12. Wiele paczek
• 13. Wybór stawki i usługi
• 14. Kontakty i punkt
• 15. Formaty etykiet
• 16. Tylko mock w default provider
• 17. Pochodzenie InPost i tagi npm
• 18. Dowód zgodności z aplikacją docelową
• 19. Metody adaptera
• 20. Przypadki kontraktu stawek
• 21. Brak zapisu wybranej stawki
• 22. Kształt adresu wobec weryfikacji
• 23. Prawda o paczce
• 24. Retry z tym samym kluczem idempotencji
• 25. Konflikt payload idempotencji
• 26. Równoległy nierozwiązany claim
• 27. Call providera i błąd lokalnego zapisu
• 28. Wykrywanie sierot
• 29. Zapobieganie duplikatom etykiet
• 30. Dostęp i retencja etykiet
• 31. Każdy znormalizowany status
• 32. Dozwolone przejścia
• 33. Regresja terminalna
• 34. Recovery failed delivery
• 35. GET tracking tylko do odczytu
• 36. POST refresh zapisuje
• 37. Decyzje wdrożeniowe pollera
• 38. Nieprawidłowy podpis webhooka
• 39. Duplikat i kolejność webhooka
• 40. Awaria kolejki i workera
• 41. Recovery pollingiem
• 42. Granice anulowania
• 43. Granice punktów nadania
• 44. Autorytet magazynu
• 45. Autorytet komunikacji
• 46. Returned wobec SalesReturn
• 47. ACL i zabronione kombinacje
• 48. Zakres tenantu i organizacji
• 49. Kontrole danych wrażliwych
• 50. Uzgodnienie i sign-off ownera

Obowiązkowe warunki stop

• Brak zgodnego i odebranego adaptera providera.
• Brak trwałej korelacji zamówienia, sales shipment, paczki i carrier.
• Brak właściciela handoff magazynu.
• Brak kontroli dostępu, druku, retencji lub incydentu etykiety.
• Brak ścieżki webhook, poll i ręcznego recovery.
• Brak recovery duplikatów lub sierot.
• Brak handoff zwrotu i obsługi klienta.
• Brak uzgodnienia stawek, faktury i księgowości.
• Wpisanie prawdziwych danych osobowych lub poświadczeń do arkusza.
• Nieznane wymaganie bezpieczeństwa, celne, dangerous goods lub regulacyjne.

Rejestr źródeł i ścieżka korekty

Powierzchnia twierdzenia, stan możliwości, etykieta dowodu, rewizja lub data, confidence, ograniczenie, public suitability i owner przeglądu zapisane 14 lipca 2026.

• 1. Moduły default app i pusta aktywacja official w sprawdzonej rewizji
• 2. Kontrakt adaptera carrier i validator
• 3. Shipping service, idempotencja i przejścia statusu
• 4. Encja carrier, routes, webhook i workery
• 5. Encje sales shipment i komendy fulfilled quantity
• 6. Enricher odpowiedzi carrier
• 7. Dokumentacja projektu Open Mercato dotycząca frameworka shipping-carrier
• 8. Najnowsze publiczne wydanie Open Mercato v0.6.5
• 9. Przypięty publiczny kod InPost w official-modules
• 10. Metadane npm sprawdzone 14 lipca 2026
• 11. Dokumentacja API InPost ze źródła pierwotnego
• 12. Wyniki wyszukiwania na żywo w języku angielskim i polskim z 14 lipca 2026

Najnowsze sprawdzone wydanie publiczne · Niezmienny kod hubu carrier · Niezmienny kod sales shipment · Przypięty kod kandydata InPost · Dokumentacja API InPost ze źródła pierwotnego

Zgłoś korektę z dokładnym twierdzeniem, zastępczym dowodem ze źródła pierwotnego, odpowiednią datą lub rewizją, wpływem operacyjnym i ownerem. Wyniki wyszukiwania i metadane pakietu odświeżono po angielsku i polsku 14 lipca 2026; dokumentują wyłącznie oczekiwania kupujących i discoverability.