Today Automate logo

🧾 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ć.

Teczka z papierowym samolotem, symbol zleceń wysyłanych przez API

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.

Klucz i tarcza, symbol podpisanych zapytań do API

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.

Niebieskie koła zębate, symbol połączonych systemów

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.

    1. BaseLinker
    2. Apaczka
    3. dopasowanie po numerze
    4. rozliczenie
    Czytaj case study →
  • 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.

    1. BaseLinker
    2. dashboard
    3. zespół pakowania
    Czytaj case study →

Jak pracujemy

  1. Konsultacja

    Ustalamy, czy dane z Apaczki mają tylko kontrolować wysyłki, czy też tworzyć zlecenia, i co ma wyjść w raporcie.

  2. 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.

  3. Integracja

    Podpisane zapytania, pełne pobieranie listy zleceń, szczegóły z wagą i pobraniem, dopasowanie do paczek z BaseLinkera.

  4. 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.

  • Logo Baselinker

    BaseLinker API

    Paczki zamówień i numery przesyłek do dopasowania. BaseLinker API →

  • Logo n8nLogo Make

    n8n lub Make

    Dane do rozliczenia albo powiadomienia dalej, bez własnego serwera. n8n → Make →

  • Logo PythonLogo Django

    Python i Django

    Pobieranie, dopasowanie i harmonogram nocnych przebiegów.

  • Logo Next.js

    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

  1. Odpisujemy w ciągu 1 dnia roboczego.
  2. Umawiamy 30-minutową rozmowę.
  3. Przygotowujemy propozycję i wycenę.

pole wymagane

Administratorem Twoich danych jest Today Group spółka z ograniczoną odpowiedzialnością (KRS 0001253446, NIP 9542911671). Użyjemy ich tylko po to, żeby odpowiedzieć na Twoje zapytanie. Podstawą jest nasz uzasadniony interes, czyli odpowiedź na Twoje zapytanie (art. 6 ust. 1 lit. f RODO). Masz prawo dostępu do danych, ich poprawienia, usunięcia i sprzeciwu. Szczegóły są w polityce prywatności.

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)?

  1. Treść metody zapisujesz jako tekst JSON. To on idzie w polu request.
  2. Czas ważności expires ustawiasz na najwyżej 15 minut od teraz, jako znacznik czasu Unix.
  3. Ciąg do podpisu to app_id, route, request i expires połączone dwukropkiem. Route ma ukośnik na końcu.
  4. Podpis to HMAC-SHA256 tego ciągu z kluczem app_secret, w hex małymi literami.
  5. Wysyłka to POST z czterema polami formularza na adres metody w API v2.
Najczęstszy błąd podpisu to ponowne zapisanie JSON po podpisaniu, np. z inną kolejnością pól albo innymi spacjami. Podpisuje się dokładnie ten tekst, który wychodzi w zapytaniu.

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.