API Ikonki: jak połączyć je z Allegro

8 października 2026 roku hurtownia Ikonka opublikowała artykuł o swoim nowym API zamówień. To dobra wiadomość dla sklepów, które dziś przepisują zamówienia z Allegro do sklepu Ikonki ręcznie. Trzeba jednak wiedzieć jedno: API robi jedną rzecz, czyli przyjmuje zamówienia. Oferta, stany, statusy i faktury płyną innymi drogami. Bez tej wiedzy łatwo zaplanować integrację, która się nie domknie.

Zastrzeżenie. SkalujOnline nie jest partnerem Ikonki. Opisujemy wyłącznie to, co Ikonka publikuje na swoich stronach i w dokumentacji API. Źródła są na końcu tekstu.

Co ogłosiła Ikonka

Ikonka to hurtownia z Białegostoku (hurt, dropshipping, import). W artykule „Zamówienia hurtowe prosto z Twojego systemu: czym jest API i co daje Twojej firmie” pisze, że API pozwala składać zamówienia z systemu klienta bez udziału pracownika, na tych samych cenach i warunkach co w sklepie.

Najważniejsze warunki:

API jest bezpłatne dla każdego kontrahenta z kontem B2B;
wdrożenie ma wykonać, słowami Ikonki, programista po stronie klienta albo firma, która obsługuje jego system;
dokumentacja jest po polsku i po angielsku, razem ze specyfikacją w standardzie OpenAPI, w wersji 0.9.0.

Numer wersji poniżej 1.0 to zwykle sygnał, że interfejs może się jeszcze zmieniać. Warto to uwzględnić w planie utrzymania integracji.

Co robi API

API ma dwie metody robocze (i trzecią, która tylko sprawdza, czy usługa działa). Prostym językiem, da się przez nie zrobić trzy rzeczy:

Złożenie zamówienia (POST /v1/orders). Twój system wysyła listę produktów, formę dostawy i płatności oraz adres.
Sprawdzenie bez zapisu. To samo zapytanie z polem "checkOnly": true przechodzi pełne sprawdzenie, ale niczego nie zapisuje. Zwraca wartość zamówienia, koszt dostawy, liczbę paczek i wynik czterech kroków: produkty, dostawa, płatność, adres.
Katalog (GET /v1/catalog). Formy dostawy i płatności dostępne dla Twojego konta i kraju.

Do tego kilka zasad, które mają znaczenie w praktyce:

Logowanie to e-mail i hasło konta B2B ze sklepu Ikonki, a nie osobny klucz. Integracja musi więc przechowywać te dane, a po zmianie hasła w sklepie trzeba je zmienić także w integracji.
Ochrona przed duplikatem. Każde zamówienie ma Twój identyfikator (externalId). Ponowne wysłanie tego samego identyfikatora nie tworzy drugiego zamówienia, tylko zwraca istniejące.
Rozmiar zamówienia: do 200 pozycji, do 9999 sztuk na pozycję, każdy kod produktu raz.
Braki. Gdy brakuje towaru, zamówienie jest odrzucane z listą powodów (np. OUT_OF_STOCK), wszystkimi naraz.
Dropshipping. Zamówienie z adresem odbiorcy wymaga włączonego dropshippingu na koncie. Faktura od Ikonki jest zawsze wystawiana na dane z konta.

Czego API nie robi

Ikonka pisze to wprost. Poza API zostają:

status zamówienia, numer przesyłki i faktury. Są widoczne w koncie w sklepie Ikonki;
oferta, ceny i stany. Te dane idą plikiem XML;
zmiany i anulowanie zamówienia. Działają tak jak przy zamówieniu złożonym w sklepie.

Wniosek: pełne połączenie „zamówienie z Allegro, zamówienie w Ikonce, numer paczki z powrotem na Allegro” wymaga więcej niż samego API. Potrzebny jest plik XML (oferta i stany), API (zamówienia) i trzecie źródło informacji o wysyłce.

Plik XML: BASIC, LIGHT i opłata

Ikonka udostępnia trzy rodzaje plików:

Plik	Zawartość	Aktualizacja
BASIC	pełna oferta z opisami i zdjęciami	raz dziennie
LIGHT	kod, kod kreskowy, stan, VAT, cena	co godzinę
personalizowany	własny wybór pól, do 5 plików	według ustawień

Dwie rzeczy łatwo przeoczyć. Pole ceny to cena sugerowana netto, więc VAT trzeba doliczyć. Link do pliku generuje się po zalogowaniu, a bez logowania adres zwraca błąd 404.

Od 1 września 2025 roku plik XML jest płatny: 199 zł brutto rocznie dla klientów z Polski i 50 EUR brutto dla klientów zagranicznych. Bez opłaty mają go klienci, którzy współpracują z Ikonką co najmniej 12 miesięcy i w tym czasie osiągnęli obrót co najmniej 100 000 zł netto.

Przepływ z Allegro krok po kroku

Poniżej projekt przepływu na podstawie dokumentacji Allegro i Ikonki. To nie jest opis gotowego wdrożenia: formaty obu stron się zgadzają, ale dostępność form wysyłki własnej zależy od konta.

Zamówienie na Allegro. Integracja czyta dziennik zdarzeń zamówień i czeka na zdarzenie „gotowe do realizacji” (READY_FOR_PROCESSING). Dopiero wtedy adres i dane do faktury są pewne. Zdarzenia mogą przyjść w innej kolejności i w duplikatach, więc integracja zapamiętuje, które zamówienia już obsłużyła.
Dopasowanie produktów. Każda oferta na Allegro musi wskazywać kod produktu Ikonki z pliku XML.
Etykieta (przy wysyłce własnej). Integracja tworzy przesyłkę w Wysyłam z Allegro i pobiera etykietę jako PDF w formacie A6. Allegro pozwala wybrać format A4 albo A6.
Sprawdzenie. Zamówienie idzie do Ikonki z checkOnly, żeby zobaczyć braki, koszt dostawy i błędy adresu, zanim cokolwiek zostanie złożone.
Złożenie. Te same dane bez checkOnly, z identyfikatorem zamówienia z Allegro jako externalId.
Numer przesyłki. Przy wysyłce własnej integracja zna numer od początku i dodaje go do zamówienia na Allegro. Przy innych formach dostawy numer jest tylko w koncie B2B.
Faktura dla kupującego. Wystawia ją Twój program do faktur, a integracja może dołączyć ją do zamówienia na Allegro jako PDF albo link. Szczegóły w artykule Faktura do zamówienia Allegro: API i KSeF.

Wysyłka własna z etykietą

W katalogu API Ikonki są formy wysyłki własnej: DPD i InPost opisane jako „(Allegro SMART!)” oraz forma opisana jako „Orlen Paczka/UPS/Kolporter (Allegro) / Allegro One Kurier”. Do takiego zamówienia dołącza się numer przesyłki i etykietę: PDF A6, jedna strona, do 5 MB. Czy dana forma jest dostępna na Twoim koncie, pokazuje katalog: formy wyłączone dla konta są w nim oznaczone.

Limity i pułapki

6 zapytań na minutę i 100 na godzinę z jednego konta. Do limitu liczą się zamówienia, sprawdzenia bez zapisu i katalog razem. Po przekroczeniu API odpowiada błędem 429 z informacją, po jakim czasie spróbować ponownie.
Z prostego rachunku: jeśli każde zamówienie najpierw sprawdzasz, a potem składasz, to dwa zapytania na zamówienie, czyli najwyżej około 50 zamówień na godzinę. Przy większej liczbie trzeba kolejkować i łączyć, a sprawdzenie bez zapisu robić tylko tam, gdzie ma sens.
Pobranie: formy za pobraniem działają tylko w sklepie internetowym, przez API odmowa.
GLS z własną etykietą działa tylko w sklepie, przez API odmowa.
Hasło konta w integracji. Zmiana hasła w sklepie wyłącza integrację do czasu aktualizacji.

Platforma, własny programista czy firma wdrożeniowa

Są trzy drogi i żadna nie jest jedynie słuszna.

Platforma. Ikonka sama wskazuje do integracji z Allegro platformy Sky-Shop, TakeDrop, BaseLinker, Redcart i Apilo. 14 października 2026 opisała też Base Connect: synchronizację oferty, stanów, cen, zamówień i statusów przez platformę Base, z dopiskiem „już wkrótce”. Ikonka publikuje także instrukcję eksportów w BaseLinkerze do składania zamówień przez API. Jeśli korzystasz z Base, rozsądnie jest najpierw sprawdzić, czy to połączenie pokrywa Twoje potrzeby.

Własny programista. Dokumentacja jest publiczna, a specyfikacja OpenAPI pozwala szybko zobaczyć wszystkie pola. Trzeba tylko pamiętać, że integracja wymaga też utrzymania: limitów, odświeżania zgody konta Allegro i zmian w obu API.

Firma wdrożeniowa. Ma sens, gdy przepływ wychodzi poza to, co robi platforma: wysyłka z etykietą Allegro, kilka hurtowni dla jednego produktu, własne reguły cen albo program do faktur bez wtyczki. Tak pracujemy w integracji hurtowni z Allegro: najpierw opis procesu, potem zakres na piśmie i wycena, a pierwsze uruchomienie w trybie podglądu, który niczego nie wysyła naprawdę.

Pytania

Czy API Ikonki jest płatne?

Nie. Według Ikonki API jest bezpłatne dla każdego kontrahenta z kontem B2B. Płatny jest plik XML z ofertą i stanami: 199 zł brutto rocznie w Polsce, chyba że spełniasz warunki zwolnienia.

Czy przez API sprawdzę stan magazynu?

Nie bezpośrednio. Stany są w pliku XML (LIGHT odświeża się co godzinę). Sprawdzenie zamówienia bez zapisu pokaże problemy z produktami przed złożeniem, ale zużywa ten sam limit 100 zapytań na godzinę, więc nie nadaje się do odpytywania stanów całego katalogu.

Jak wysłać zamówienie z Allegro do Ikonki?

Integracja czeka, aż zamówienie na Allegro będzie gotowe do realizacji, dopasowuje oferty do kodów Ikonki, opcjonalnie pobiera etykietę z Allegro, sprawdza zamówienie bez zapisu i składa je z identyfikatorem z Allegro. Ten sam identyfikator chroni przed złożeniem zamówienia dwa razy.

Czy potrzebuję programisty?

Do samego API tak, albo firmy wdrożeniowej. Tak pisze też Ikonka. Bez programisty zostają platformy, które Ikonka wymienia, i zapowiadane połączenie przez Base.

Czy da się zamówić za pobraniem przez API?

Nie. Formy za pobraniem są według dokumentacji dostępne tylko w sklepie internetowym.

Ile zamówień na godzinę przyjmie API?

Limit to 100 zapytań na godzinę i 6 na minutę z jednego konta, łącznie ze sprawdzeniami i katalogiem. Ile to zamówień, zależy od tego, czy każde najpierw sprawdzasz.

Chcesz połączyć Ikonkę z Allegro albo ze sklepem? Opisz swój proces, a dopytamy o resztę.

Źródła (odczyt 23.10.2026): Ikonka: API zamówień, dokumentacja API, specyfikacja OpenAPI, zasady integracji XML, generator XML, integracja XML, Base Connect, automatyzacja zamówień, Allegro: obsługa zamówień, Allegro: Wysyłam z Allegro.