🧾 Apaczka bez ręcznych zestawień
Integracja Apaczka API
Zlecenia z Twojego konta Apaczki trafiają do Twojego systemu z numerem przesyłki, wagą, wymiarami, pobraniem i statusem. Łączymy je z paczkami z BaseLinkera po numerze listu przewozowego, więc wiesz, które przesyłki należą do którego klienta i które trzeba wyjaśnić.
Integracja Apaczka API w skrócie
Integracja Apaczka API to połączenie konta w Apaczce z Twoim systemem przez API v2, dzięki któremu zlecenia kurierskie, ich numery przesyłek, waga, wymiary, pobrania i statusy są dostępne bez eksportu z panelu. Apaczka jest pośrednikiem: przez jedno API obsługuje wielu przewoźników, więc jedna integracja daje dane z kilku firm kurierskich naraz.
Podpisane zapytania.
Każde zapytanie ma podpis HMAC-SHA256 z sekretu aplikacji, który zostaje na serwerze.
Dopasowanie po numerze przesyłki.
Zlecenie łączy się z paczką z BaseLinkera tylko po numerze listu przewozowego.
Waga, wymiary i pobranie.
Ze szczegółów zlecenia, raz na przesyłkę, z kwotą przeliczoną z groszy na złote.
Błąd widać, nawet przy statusie 200.
Wynik sprawdzamy w treści odpowiedzi, bo Apaczka zwraca HTTP 200 także przy błędach.
Apaczka bez eksportu z panelu
Dziś: Zestawienie zleceń z panelu Apaczki raz w miesiącu
Po wdrożeniu: Zlecenia z Apaczka API pobierane co noc i na żądanie
Dziś: Przesyłki liczone bez związku z zamówieniami
Po wdrożeniu: Każde zlecenie połączone z paczką z BaseLinkera po numerze przesyłki
Dziś: Waga i pobranie sprawdzane w panelu przy reklamacji
Po wdrożeniu: Waga, wymiary i pobranie zapisane przy przesyłce
Dziś: Anulowane zlecenia mieszają się z wysłanymi
Po wdrożeniu: Anulowane zlecenie osobno, poza rozliczeniem
Dziś: Odbiorca u kuriera inny niż w sklepie i nie da się go znaleźć
Po wdrożeniu: Wyszukiwarka także po odbiorcy i telefonie z Apaczki
Apaczka mówi, co przyjął przewoźnik. Twój system wie, którego klienta to paczka.
Co łączymy z Apaczką
Zakres ustalamy na konsultacji. Najczęściej obejmuje te elementy.
Lista zleceń.
Zlecenia z konta z numerem przesyłki, usługą, statusem, datą utworzenia i doręczenia oraz linkiem do śledzenia.
Szczegóły zlecenia.
Waga, wymiary, pobranie i liczba paczek w zleceniu, pobierane osobnym zapytaniem z limitem na jeden przebieg.
Paczkomat InPost przez Apaczkę.
Gabaryt A, B albo C wyliczony z najmniejszego wymiaru paczki, tak jak w raporcie dla przesyłek z konta InPost.
Dopasowanie do BaseLinkera.
Numer listu przewozowego z Apaczki łączymy z numerem paczki w BaseLinkerze. Numer zamówienia z opisu tylko wyjaśnia brak pary.
Zamawianie kuriera.
Wycena i utworzenie zlecenia z Twojej aplikacji, etykieta w PDF, gdy wysyłka ma iść przez Apaczkę bez innego systemu.
Kontrola błędów.
Status sprawdzany w treści każdej odpowiedzi, pełne stronicowanie listy i komunikat na ekranie, gdy pobranie się nie uda.
Apaczka API w naszych wdrożeniach
Firma fulfillment: rozliczanie paczek z kurierami
Zlecenia z konta Apaczki porównane z paczkami z BaseLinkera. W pierwszym sprawdzeniu ok. 96% przesyłek z dwóch tygodni miało parę po numerze, a każda z reszty miała podany powód.
- BaseLinker
- Apaczka
- dopasowanie po numerze
- rozliczenie
Ten sam magazyn: dashboard dla pakowania
Na ekranach w magazynie widać, ile zamówień zostało do spakowania przed odbiorem kuriera i które są opóźnione.
- BaseLinker
- dashboard
- zespół pakowania
Jak pracujemy
Konsultacja
Ustalamy, czy dane z Apaczki mają tylko kontrolować wysyłki, czy też tworzyć zlecenia, i co ma wyjść w raporcie.
Dostęp do API
Aplikację API zakładasz w panelu Apaczki. App ID i sekret wpisujesz w panelu, a test połączenia wykonuje jedno lekkie zapytanie.
Integracja
Podpisane zapytania, pełne pobieranie listy zleceń, szczegóły z wagą i pobraniem, dopasowanie do paczek z BaseLinkera.
Test i uruchomienie
Porównanie próbki przesyłek z panelem Apaczki, potem nocne pobieranie i opieka po wdrożeniu.
Czego nie robimy
- Nie ponawiamy na ślepo utworzenia zlecenia po przekroczeniu czasu, bo może powstać drugie zlecenie i druga opłata.
- Nie przerywamy pobierania listy na pierwszym starym zleceniu.
- Nie przypinamy przesyłki do zamówienia po numerze z opisu ani po odbiorcy.
- Nie trzymamy sekretu aplikacji w przeglądarce, w kodzie ani w repozytorium.
Narzędzia
Apaczka API v2
Lista i szczegóły zleceń, wycena, zamawianie kuriera, etykiety.
HMAC-SHA256
Podpis każdego zapytania kluczem aplikacji, z krótkim czasem ważności.
BaseLinker API
Paczki zamówień i numery przesyłek do dopasowania. BaseLinker API →
n8n lub Make
Dane do rozliczenia albo powiadomienia dalej, bez własnego serwera. n8n → Make →
Python i Django
Pobieranie, dopasowanie i harmonogram nocnych przebiegów.
Next.js
Panel z przesyłkami, uwagami i eksportem do Excela.
Opisz, co chcesz połączyć z Apaczką
Napisz, czym zajmuje się Twoja firma i co chcesz usprawnić.
Wrócimy z konkretną propozycją, a nie z ogólną prezentacją.
Co dzieje się dalej
- Odpisujemy w ciągu 1 dnia roboczego.
- Umawiamy 30-minutową rozmowę.
- Przygotowujemy propozycję i wycenę.
Najczęstsze pytania
Jak działa Apaczka API?
Apaczka API v2 działa na zapytaniach POST z czterema polami formularza: app_id, request (treść jako JSON), expires i signature. Każde zapytanie jest podpisane HMAC-SHA256. Przez jedno API wyceniasz, zamawiasz i śledzisz przesyłki u wielu przewoźników, z którymi współpracuje Apaczka.
Jak wygenerować podpis w Apaczka API?
Podpis to HMAC-SHA256 z ciągu app_id:route:request:expires, liczony kluczem app_secret i zapisany małymi literami w hex. Route to ścieżka metody z ukośnikiem na końcu, np. „order_send/”. Pole expires to czas ważności zapytania, najwyżej 15 minut od teraz. Podpisuje się dokładnie ten tekst JSON, który idzie w polu request.
Gdzie znaleźć app_id i app_secret Apaczki?
App ID i sekret dostajesz po założeniu aplikacji API w panelu Apaczki, w ustawieniach API. Sekret podpisuje każde zapytanie, więc kto go ma, może tworzyć zlecenia na Twoim koncie. Trzymamy go tylko po stronie serwera.
Dlaczego Apaczka API zwraca status 200 przy błędzie?
Tak działa API v2: każda odpowiedź ma kod HTTP 200, a prawdziwy wynik jest w polu status w treści odpowiedzi. 200 oznacza sukces, inna wartość to błąd z opisem w polu message. Integracja musi to sprawdzać przy każdym zapytaniu, inaczej błąd przejdzie jako pusty wynik.
W jakiej jednostce Apaczka API podaje ceny i pobrania?
W groszach: 1 zł to 100 groszy. Kwoty trzymamy jako liczby całkowite i dzielimy przez 100 dopiero przy wyświetlaniu. Wymiary paczki podaje się w centymetrach, a wagę w kilogramach.
Jak pobrać wagę i wymiary przesyłek z Apaczki?
Ze szczegółów zlecenia, które pobiera się osobnym zapytaniem dla każdego zlecenia. W naszym wdrożeniu robimy to raz na przesyłkę, z limitem na jeden przebieg, i zapisujemy wagę, wymiary, pobranie i liczbę paczek. Zaległe szczegóły dochodzą w kolejnych przebiegach.
Jak rozliczyć klientów z przesyłek nadanych przez Apaczkę?
Trzeba połączyć zlecenia z Apaczki z zamówieniami, w których jest klient. W naszym wdrożeniu numer listu przewozowego z Apaczki łączy się z paczką w BaseLinkerze, a klient pochodzi z zamówienia. Opisujemy to w case study rozliczania paczek.
Co daje integracja z Apaczka API?
Apaczka to pośrednik między sklepem a przewoźnikami: jedno konto i jedno API dają dostęp do wielu firm kurierskich i paczkomatów. Według dokumentacji Apaczki (stan na listopad 2026) to ponad 20 przewoźników. Dla integracji oznacza to jedno źródło danych o przesyłkach zamiast osobnych połączeń z każdym kurierem.
Integracja przydaje się na dwa sposoby. Pierwszy to zamawianie kuriera z Twojej aplikacji: wycena, zlecenie i etykieta. Drugi to kontrola i rozliczenia: lista zleceń z konta, waga, pobranie i status, połączone z zamówieniami w Twoim systemie. W naszym wdrożeniu dla firmy fulfillment Apaczka służy do tego drugiego.
Jak podpisać zapytanie do Apaczka API (HMAC)?
- Treść metody zapisujesz jako tekst JSON. To on idzie w polu request.
- Czas ważności expires ustawiasz na najwyżej 15 minut od teraz, jako znacznik czasu Unix.
- Ciąg do podpisu to app_id, route, request i expires połączone dwukropkiem. Route ma ukośnik na końcu.
- Podpis to HMAC-SHA256 tego ciągu z kluczem app_secret, w hex małymi literami.
- Wysyłka to POST z czterema polami formularza na adres metody w API v2.
Pułapki Apaczka API, które widzieliśmy na produkcji
- HTTP 200 przy błędzie. Wynik jest w polu status w treści odpowiedzi, nie w kodzie HTTP.
- Kolejność listy zleceń. U nas lista nie była ułożona ściśle po dacie: stare zlecenia trafiały między nowe. Pobieranie, które kończyło się na pierwszym starym zleceniu, zwróciło 315 z 1170 przesyłek z dwóch tygodni. Teraz kończymy dopiero na stronie, na której wszystkie zlecenia są starsze niż zakres.
- Małe strony. U nas lista zwracała 10 zleceń na stronę, więc miesiąc to setki podpisanych zapytań. Takie pobieranie robimy w tle i zapisujemy w bazie, a nie w czasie otwierania ekranu.
- Nieznane pola są ignorowane. Według dokumentacji błędna nazwa pola nie daje błędu, tylko wartość domyślną, np. wymiary to dimension1, dimension2 i dimension3 w centymetrach.
- Utworzenie zlecenia nie jest idempotentne. Ponowienie po przekroczeniu czasu może utworzyć drugie zlecenie, więc przed ponowieniem sprawdzamy listę zleceń.
Paczkomat InPost przez Apaczkę: jak ustalić gabaryt A, B, C?
W szczegółach zlecenia paczkomatowego z Apaczki dostajemy wymiary paczki, ale nie gabaryt wprost. Wyliczamy go z najmniejszego wymiaru, zgodnie z wysokością skrytek InPost: do 8 cm to gabaryt A, do 19 cm gabaryt B, do 41 cm gabaryt C. Dzięki temu raport paczek per klient ma te same kolumny dla przesyłek z Apaczki i z konta InPost przez ShipX API.
Apaczka, BaseLinker i rozliczenie klientów
Gdy przesyłki zamawia BaseLinker przez integrację z Apaczką, w zamówieniu jest numer przesyłki, a w Apaczce zlecenie z tym samym numerem. Po tym numerze łączymy obie strony. Każde zlecenie kończy z jednym wynikiem: dopasowane, anulowane u przewoźnika, zamówienie ma w BaseLinkerze inną etykietę, zamówienia nie ma jeszcze w synchronizacji albo brak numeru zamówienia w opisie.
Dane do rozliczenia mogą potem iść dalej do scenariusza w n8n albo Make, np. do przygotowania rozliczenia klienta. O samym BaseLinkerze przeczytasz na stronie BaseLinker API.

