Apaczka — moduł przewoźnika Orbito

Wersja 0.2.5. Logo Apaczki jest dołączone do paczki i rejestrowane w buckecie każdej instancji. Niezależne konto core/apaczka, wiele instalacji, bez zależności od innych modułów. Obsługa krajowych paczek w PLN z adresu lub punktu nadawcy do adresu lub punktu odbioru, nadanie samodzielne lub odbiór kurierem, pobranie, etykiety PDF i śledzenie. Nie obsługuje jeszcze palet, przesyłek zagranicznych, odprawy celnej, anulowania ani zamawiania dodatkowych opcji usługi. Katalog i dostępność usług pochodzą z konta Apaczki, bez zaszytych ID.

Połączenie

1. Włącz Web API na koncie Apaczki, następnie w zakładce Web API dodaj aplikację.
2. Zainstaluj paczkę Apaczki. Dla każdego konta utwórz oddzielną instalację.
3. W konfiguracji zapisz nazwę konta, App ID i App Secret.
4. Wybierz konkretne instancje rejestru zamówień i przesyłek. Przesyłki wymagają

wersji 2.19.1 lub nowszej, obsługującej sourceScope: 'all' w instalacji szablonów.

1. W zakładce Adres nadania i dane nadawcy uzupełnij wymagany krajowy adres,

telefon i e-mail. W Podjazd kuriera wybierz sposób odbioru: samodzielne nadanie/stały podjazd albo zamawianie kuriera przy nadaniu. W drugim przypadku wymagane są godziny od–do. Dla pobrań zapisz 26-cyfrowy rachunek PLN w Nadania Apaczka.

1. Kliknij Sprawdź połączenie i zainstaluj metody dostawy. Jeśli najpierw

sprawdziłeś klucze, a rejestry wybrałeś później, użyj Zainstaluj metody dostawy.

1. W warunkach doboru przewoźnika sprawdź frazy nazw dostaw, wymiary i zakresy wag.

Frazy startowe są nazwami usług Apaczki; można dopasować je do nazw dostaw używanych przez swoje źródła zamówień. Każde konto ma osobne szablony.

Akcje konfiguracji korzystają z uwierzytelnionego kontekstu użytkownika ustawień przekazywanego przez platformę (ctx.userId w SDK 4.3). Dane formularza nie nadają uprawnień. Publiczne metody connection.test i presets.install wymagają apaczka.manage. Pozostałe uprawnienia: conditions.edit do instalacji w rejestrze, shipments.view do odczytów, shipments.edit do nadawania. Dostęp do hooków opiera się na uwierzytelnionym kontekście platformy, bez wyjątków dla marek modułów-klientów.

Preinstalowane szablony

Jak w ErliPRO, katalog usług instaluje nazwane paczki w warunkach dostawy przez shipping.conditions.provision. Instalacja jest jednorazowa, nie zastępuje ręcznych warunków i nie nadpisuje późniejszych zmian użytkownika.

Zgodnie z uzgodnieniem wymiary startowe skopiowano z konfiguracji/słownika ERLI z 2026-10-06. To lokalne dane początkowe, bez importu kodu, odczytu konfiguracji ani zależności od instalacji ERLI podczas działania modułu. Dla usług bez pasującego wymiaru startem jest 10 × 10 × 10 cm, również dla Pocztex XL, który w słowniku ERLI ma tylko ograniczenie sumy boków.

Wymiary i zakresy są edytowalne, nie stanowią deklaracji limitów Apaczki. Usługi dobierane są po nazwie/supplier i oznaczeniu dostawy do punktu w katalogu. Waga nadania pochodzi z pełnego kompletu produktów i zestawów, nie z domyślnej wagi szablonu; jest ponownie sprawdzana przed nadaniem. API wymaga pełnych cm i wagi z dokładnością do 0,1 kg — moduł zaokrągla wagę w górę.

Formularz pokazuje wyłącznie usługi zgodne z dostawą z zamówienia. Pola zmieniają się reaktywnie po wyborze usługi. Wymiary i waga pozostają danymi przesyłki. Adres nadania, sposób zamawiania kuriera i stałe godziny podjazdu pochodzą z konfiguracji i nie można ich nadpisać payloadem formularza. Data odbioru jest widoczna tylko dla nadania, które ma zamówić kuriera. Usługi nadawane w punkcie pomijają ustawienia kuriera. Usługa z obowiązkowym kurierem wymaga włączenia zamawiania w konfiguracji.

Dla dostawy do punktu moduł rozpoznaje sieć wybranej usługi przy jednoznacznym dopasowaniu i potwierdza punkt zamówienia w katalogu Apaczki. Użytkownik widzi nazwę i adres; techniczne identyfikatory są przesyłane wewnętrznie. Gdy brakuje jednoznacznego dopasowania, formularz udostępnia wybór sieci i/lub punktu po nazwie oraz adresie. Lista pokazuje do 200 dopasowań w miejscowości odbiorcy oraz zweryfikowany punkt z zamówienia, także poza limitem. Punkty bez obsługi pobrania są wykluczone dla COD. Brak katalogu jest widocznym błędem i blokuje nadanie.

Dla usług z nadaniem w punkcie najpierw zapisz sieć i miejscowość/kod/ulicę w Punkt nadania — sieć i wyszukiwanie, następnie w Nadania Apaczka wybierz wymagany punkt z listy nazw i adresów. Oddzielny zapis wyszukiwania pozwala zmienić sieć lub zawęzić listę również wtedy, gdy poprzedni punkt jest już niedostępny. Moduł zachowuje wcześniej zapisane ID i ustawienia przy aktualizacji, weryfikuje punkt przed nadaniem i nigdy nie przypisuje podobnie nazwanego punktu automatycznie.

Nadanie i odzyskiwanie wyniku

Przed nadaniem moduł wybiera jedną instancję rejestru zamówień i przesyłek, weryfikuje dostępność oraz zapisuje zamiar w swojej bazie. Rozproszona blokada jest odnawiana. Timeout, nieczytelna odpowiedź lub błąd zapisu po utworzeniu zamówienia blokuje ponowienie order_send. Sprawdź panel Apaczki i w formularzu podaj numer istniejącego zamówienia w Apaczce, nie numer listu. Pole uzgodnienia pojawia się dopiero po niepewnym nadaniu; wtedy formularz oferuje wyłącznie odzyskanie istniejącej przesyłki. Uzgodnienie wymaga zapisanej intencji, zgodnego znacznika Orbito:…, usługi, odbiorcy i paczki.

Znane ID pozwala wznowić pobranie gotowego listu. Niepewne przekazanie do rejestru wymaga sprawdzenia rejestru i jawnego powiązania ID. Brak etykiety nie powoduje ponownego nadania: pobierzesz ją później z listy przesyłek. Po pierwszej intencji nie zmieniaj rejestrów tego konta; inne konto/rejestry wymagają osobnej instalacji. Rotacja sekretu wymaga ponownego sprawdzenia połączenia, zachowuje tożsamość konta.

API i weryfikacja

Implementacja: oficjalna dokumentacja Web API v2 i podpisy/formularz zgodne z udostępnionym tam PHP SDK. Wszystkie wywołania są POST do https://www.apaczka.pl/api/v2/, podpis HMAC-SHA256, ważność 5 minut, kontrola zarówno HTTP, jak i status w JSON. Sekret i surowe błędy API nie trafiają do logów/odpowiedzi. Katalog usług i punktów jest cache'owany przez 24 godziny osobno dla konta, typu punktów, kraju i aktualnych danych dostępowych. Śledzenie korzysta z tracking/:waybill_number/; nierozpoznane statusy pozostają unknown. Moduł nie wysyła rzeczywistych zleceń przy uruchomieniu ani testowaniu kluczy.

npm ci
npm test
npm run check
omm pack --dry-run
omm pack

Z katalogu workspace dodatkowo uruchom testy module-contracts i modułu przesyłek zgodnie z codex.md. Testy automatyczne używają atrap API i rzeczywistego protokołu hooków, także alternatywnych autorów i wielu instancji. Nadanie na rzeczywistym koncie i formularz działającej instancji wymagają osobnej weryfikacji po instalacji.

Plany opakowań

Wycena opcji nadania pochodzi z POST /api/v2/order_valuation/ dla dokładnej struktury order, wybranej usługi i punktów nadania/odbioru. price (netto) wybranej usługi jest przeliczane z groszy na price: { amount, currency: 'PLN', basis: 'net' } w istniejącym hooku shipping.carrier.getQuickShipOptions. Wycena nie tworzy zamówienia ani listu. Cache ważny przez 60 s jest oddzielny dla konta, danych dostępowych i pełnego żądania. Brak poprawnej kwoty lub błąd API pomija cenę, zachowując możliwość nadania. Limit czasu zapytania o cenę wynosi 4 s; błędy są pamiętane najwyżej przez 5 s. Źródło: Apaczka Web API v2.

Hub przesyłek może przekazać potwierdzony packingPlan przez kontrakt shipping.carrier. Wymiary i waga brutto pochodzą z planu, a adapter ponownie sprawdza zgodność z aktualnym zamówieniem przed nadaniem. Zmiana zamówienia wymaga ponownego potwierdzenia. Obsługa jest deklarowana przez packingPlans: true oraz packingPlanVersions: [1, 2]. Wersja 2 obsługuje zestawy z osobnymi trybami połączenia kartonów; do API trafia wynikowa lista paczek. Nadal obowiązują limity usług i liczby paczek; starszy hub zachowuje dotychczasowy sposób nadania.

Aktualny adapter obsługuje jedną fizyczną paczkę. Plan osobnych podpaczek jest jawnie odrzucany; kartony połączone mogą być obsłużone po kontroli limitów usługi.

Gdy usługa nie obsługuje podpaczek w jednym nadaniu, aktualny Shipping może nadać każdą fizyczną paczkę na osobnym liście (separateShipments, packingParcelIndex). Pełny plan jest ponownie walidowany przed każdym nadaniem. Pobranie jest dzielone według sum maksymalnych obciążeń kartonów w paczce, w groszach, tak aby suma na wszystkich listach była dokładnie równa kwocie zamówienia. Każdy zapisany list ma własną etykietę i zdarzenie do istniejącej automatyzacji wydruku. Częściowy sukces lub niepewna odpowiedź zatrzymuje serię i blokuje automatyczne ponowienie.