Przegląd dla programistów

Omnilinker ma REST API pod adresem https://omnilinker.pl/api/. To to samo API, z którego korzysta aplikacja webowa, więc większość tego, co robisz na ekranie, możesz też zrobić ze skryptu, z middleware’u takiego jak n8n czy Make albo z własnej usługi. Każde żądanie uwierzytelniasz kluczem API, który działa w imieniu osoby, która go utworzyła.

Co możesz dziś zintegrować

Chcesz	Użyj
Odczytywać lub zmieniać katalog, ceny, zamówienia, stany, przesyłki i kontakty	REST API z kluczem API
Reagować na zmiany w zamówieniach	Kanału zmian dziennika zamówień; zobacz Webhooki i kanały zmian
Zbiorczo dodawać lub zdejmować stany z arkusza	Importu stanów; zobacz Formaty plików
Wczytać produkty i ceny z arkusza	Importów katalogu; zobacz Import produktów, cen i zdjęć
Pobrać dane jako plik Excel lub CSV	Eksportów; zobacz Formaty plików

Jeszcze niedostępne:

Webhooki wychodzące. Omnilinker nie wywołuje Twojego endpointu, gdy coś się zmieni. Zamiast tego odpytuj dziennik zamówień; zobacz Webhooki i kanały zmian.
Klienci OAuth dla Twoich aplikacji. W Omnilinkerze nie zarejestrujesz klienta OAuth ani OpenID Connect. Użyj klucza API; zobacz Uwierzytelnianie.
Biblioteki klienckie. Nie ma oficjalnego SDK. Jeśli go potrzebujesz, wygeneruj klienta z dokumentu OpenAPI; zobacz Dokumentacja API.

Dokumentacja API

Dokumentacja wymienia każdy endpoint z jego parametrami i schematem odpowiedzi:

Co	Gdzie
Swagger UI	`https://omnilinker.pl/swagger`
ReDoc	`https://omnilinker.pl/api-docs`
Dokument OpenAPI (JSON)	`https://omnilinker.pl/swagger/v1/swagger.json`

Na stronie Klucze API przycisk Dokumentacja API otwiera Swagger UI. Dokumentacja opisuje całe API, także endpointy, z których klucz API nie może korzystać (zarządzanie użytkownikami, rolami, ustawieniami i kluczami). Które to są, wyjaśnia strona Uwierzytelnianie.

Pierwsze żądanie

Utwórz klucz API

W Omnilinkerze otwórz Klucze API i kliknij Nowy klucz API. Wybierz, co będzie z niego korzystać, nadaj mu nazwę i kliknij Utwórz klucz. Skopiuj klucz, gdy się pojawi: widzisz go tylko raz. Zobacz Uwierzytelnianie.

Sprawdź klucz

Wywołaj GET /api/api-key-management/whoami z kluczem w nagłówku X-Api-Key:

curl https://omnilinker.pl/api/api-key-management/whoami \
  -H "X-Api-Key: $OMNILINKER_API_KEY"

Odpowiedź podaje nazwę klucza, osobę, w której imieniu działa, Twoją organizację i uprawnienia, które klucz faktycznie ma. Jeśli grantedPermissions jest puste, klucz nie może jeszcze nic zrobić.

Wywołaj endpoint

Na przykład pobierz najnowsze zamówienia (klucz potrzebuje uprawnienia Zamówienia):

curl "https://omnilinker.pl/api/ordering/order?MaxResultCount=20" \
  -H "X-Api-Key: $OMNILINKER_API_KEY"

Wywołuj API z serwera lub skryptu, nie z kodu, który działa w przeglądarce: klucz umieszczony na stronie może odczytać każdy, kto ją otworzy.

Obszary API

Każdy moduł ma własny prefiks ścieżki. Tabela wymienia obszary, z których integracja najczęściej korzysta; dokumentacja API wymienia wszystkie.

Prefiks ścieżki	Moduł	Więcej
`/api/catalog/`	Produkty, marki, kategorie, tagi, poziomy cen	Produkty
`/api/pricing-intelligence/`	Oferty, sprzedawcy, historia cen, przegląd produktów, repricer	Analiza cen
`/api/ordering/`	Zamówienia, statusy i źródła zamówień, dodatkowe pola, dziennik zamówień	Zamówienia
`/api/contacts/`	Klienci i statystyki ich zamówień	Klienci
`/api/inventory/`	Magazyny, stany, ruchy magazynowe, import stanów	Stany i ruchy magazynowe
`/api/shipping/`	Przesyłki, etykiety i śledzenie	Przesyłki
`/api/marketplaces/`	Konta i oferty Allegro i OLX	Tworzenie ofert
`/api/automation/`	Własne wyzwalacze i uruchomienia automatyzacji	Własne wyzwalacze
`/api/devices/`, `/api/printing/`	Stanowiska, drukarki i zadania drukowania	Zadania drukowania
`/api/fiscal/`	Paragony fiskalne	Paragony fiskalne
`/api/erp-integration/`	Połączenia z ERP i polecenia	Integracja ERP

Endpointy modułu, który nie jest włączony dla Twojej organizacji, odpowiadają 403 Forbidden. To, jakie moduły masz, zależy od Twojego planu; zobacz Moduły i dostępność funkcji.

Konwencje

Żądania i odpowiedzi

Treść żądań i odpowiedzi to JSON. Nazwy właściwości są w camelCase: totalCount, items, orderId.
Wyliczenia (enumy) wysyłasz i dostajesz jako liczby. Dokumentacja API podaje, jakie liczby przyjmuje każde z nich.
Identyfikatory to GUID-y, chyba że dokumentacja mówi inaczej (na przykład id w dzienniku zamówień to liczba).
Czasy są zwracane w UTC, w formacie ISO 8601. Wysyłaj je też w UTC, z Z lub przesunięciem, żeby nie zostały odczytane w innej strefie czasowej.
dimensions i weight produktu są w jego własnej jednostce unit, tak samo w odpowiedzi jak w żądaniu: pudełko o wysokości 15 cm to "height": 15 z jednostką centymetr, a odesłanie tej wartości zostawia 15 cm. Mimo nazwy weight.amountInGrams zawiera wagę w jednostce weight.unit. Wartości są zaokrąglone do 15 cyfr znaczących, więc odesłane bez zmian, nawet przez typ double, zachowują dokładnie zapisaną wartość.
Endpointy, które zwracają plik (eksport, szablon importu), odpowiadają samym plikiem, a nie JSON-em.

Listy i stronicowanie

Endpointy list przyjmują trzy parametry zapytania:

Parametr	Znaczenie
`SkipCount`	Ile pozycji pominąć. Domyślnie `0`.
`MaxResultCount`	Ile pozycji zwrócić. Domyślnie `10`, najwyżej `1000`, chyba że dokumentacja podaje mniej.
`Sorting`	Wyrażenie sortowania, gdy endpoint je obsługuje, na przykład nazwa pola i `asc` lub `desc`.

Lista stronicowana zwraca łączną liczbę pozycji i jedną stronę:

{
  "totalCount": 1284,
  "items": [ ]
}

Kolejne strony pobierasz, zwiększając SkipCount o MaxResultCount, dopóki nie masz totalCount pozycji. Niektóre endpointy mają własne stronicowanie, jak kursor dziennika zamówień; mówi o tym ich opis w dokumentacji.

Twoja organizacja

Klucz należy do jednej organizacji, a każde wywołanie z nim odczytuje i zapisuje tylko dane tej organizacji. Nie wysyłasz nagłówka ani identyfikatora najemcy: decyduje klucz. Aby pracować z dwiema organizacjami, użyj klucza z każdej z nich.

Bezpieczne tworzenie zamówień

Gdy tworzysz zamówienie przez POST /api/ordering/order, wyślij nagłówek Idempotency-Key z wartością unikalną dla tego zamówienia w Twoim systemie, do 128 znaków. Jeśli wywołanie przekroczy limit czasu i wyślesz je ponownie z tą samą wartością, Omnilinker zwróci zamówienie, które już utworzył, zamiast tworzyć drugie. Wartość możesz też wysłać jako idempotencyKey w treści żądania; gdy są obie, wygrywa ta z treści.

Błędy

Gdy wywołanie się nie uda, treść odpowiedzi opisuje błąd zawsze w tym samym kształcie, niezależnie od endpointu:

{
  "error": {
    "code": "Inventory:NegativeStockNotAllowed",
    "message": "Czytelny opis tego, co poszło nie tak.",
    "details": null,
    "data": { },
    "validationErrors": null
  }
}

code identyfikuje błąd. Jest obecny, gdy błąd go ma; obsługę błędów opieraj na nim, a nie na komunikacie.
message jest przeznaczony dla ludzi i jest w języku żądania: wyślij Accept-Language: pl-PL, aby dostać komunikat po polsku, albo Accept-Language: en, aby dostać go po angielsku.
validationErrors wymienia każde niepoprawne pole, jako message i members (nazwy pól), gdy żądanie nie przeszło walidacji.
data zawiera wartości związane z błędem, na przykład przekroczony limit.

Kod statusu mówi, jaki to rodzaj błędu:

Status	Znaczenie
`400 Bad Request`	Żądanie nie przeszło walidacji. Zobacz `validationErrors`.
`401 Unauthorized`	Nie wysłano klucza albo klucz jest nieważny: nieznany, wygasły, dezaktywowany, usunięty, zastąpiony lub jego właściciel nie może się już zalogować.
`403 Forbidden`	Klucz jest ważny, ale nie może tego zrobić: brakuje mu uprawnienia, uprawnienie jest z tych, których klucz nigdy nie dostaje, albo moduł nie jest włączony dla Twojej organizacji. Wiele reguł biznesowych też odmawia z kodem `403` i polem `code`.
`404 Not Found`	Rekord nie istnieje albo nie należy do Twojej organizacji.
`409 Conflict`	Ktoś zmienił rekord, odkąd go odczytałeś, albo zmiana jest sprzeczna z jego obecnym stanem. Odczytaj go ponownie i ponów próbę.
`500 Internal Server Error`	Nieoczekiwany błąd. Spróbuj później; jeśli się powtarza, skontaktuj się z pomocą i podaj czas wywołania.

Omnilinker nie ogranicza dziś liczby żądań wysyłanych z klucza API.

Uwierzytelnianie

Wysyłanie klucza, testowanie i to, co klucz może.

Webhooki i kanały zmian

Śledzenie zmian w zamówieniach przez dziennik zamówień.

Formaty plików

Kolumny importu stanów i eksportów.

Klucze API

Tworzenie, wymiana i unieważnianie kluczy.

​Co możesz dziś zintegrować

​Dokumentacja API

​Pierwsze żądanie

​Obszary API

​Konwencje

​Żądania i odpowiedzi

​Listy i stronicowanie

​Twoja organizacja

​Bezpieczne tworzenie zamówień

​Błędy