PRZEWODNIK DLA PARTNERÓW
Čeština Němčina Angličtina Chorvatština Maďarština Polština Slovenština Vietnamština
Wstęp Praktyczne instrukcje Dobra API stron trzecich

API stron trzecich

Ten artykuł został przetłumaczony maszynowo.

API służy do przekazywania informacji o zleceniach pomiędzy systemem Slevomat a systemem partnera handlowego. API wymaga realizacji komunikacji dwukierunkowej – system Slevomat wywołuje API partnera, a partner wywołuje API Slevomat.

Zlecenia wyeksportowane do API partnera nie mogą być już manipulowane w interfejsie partnera Slevomat, a jedynie przeglądane. Manipulacja wyeksportowanymi zamówieniami może odbywać się tylko za pośrednictwem API.

Wszystkie żądania muszą być wykonane na HTTPS, a wszystkie dane są w formacie JSON.

Dostęp do API

Dostęp do danych uwierzytelniających API można uzyskać z zakładki Ustawienia w interfejsie partnera. Aby uzyskać dane, musisz podać główny adres URL części partnerskiej API do wykorzystania w kierunku Slevomat → Partner, np. 

https://example­.com/slevomat-zbozi-api

Dane dostępowe zostaną wyświetlone tylko raz przy dostępie do API, proszę je starannie przechowywać.

Po uzyskaniu dostępu do API system zacznie eksportować do niego nowo utworzone zamówienia.

Wstępny eksport danych

Aby przenieść istniejące zamówienia w momencie dostępu do API, możesz użyć jednorazowego eksportu do CSV w interfejsie partnera.

Jeśli masz istniejące zamówienia (utworzone przed udostępnieniem API) we własnym systemie i chcesz rozpocząć pracę z nimi przez API, skorzystaj z funkcji "Rozpocznij pracę z zaznaczonymi zamówieniami przez API" w menu "Masowe działania ze zleceniami".

Opis typowych odpowiedzi HTTP

  • 200 OK – żądanie zostało pomyślnie przetworzone
  • 204 No Content – żądanie zostało przetworzone, odpowiedź nie ma treści
  • 400 Bad Request – żądanie jest nieprawidłowe – może brakować parametrów lub są one nieprawidłowe w stosunku do specyfikacji
  • 403 Forbidden – autoryzacja klienta nie powiodła się
  • 404 Not Found – nie znaleziono punktu końcowego lub wymaganych danych
  • 405 Method Not Allowed – punkt końcowy nie obsługuje tej metody HTTP
  • 422 Unprocessable Entity – spodziewany błąd podczas przetwarzania żądania (patrz sekcja Warunki błędów)
  • 500 Internal Server Error – wystąpił błąd po stronie serwera
  • 502 Bad Gateway – wystąpił błąd po stronie serwera
  • 503 Service Unavailable – serwer jest w trybie konserwacji (może trwać wdrażanie nowej wersji lub planowany przestój)
  • 504 Gateway Timeout – wystąpił błąd po stronie serwera

Odpowiedzi HTTP 5×x nie mogą używać formatu JSON.

W przypadku błędów 4xx winne jest wychodzące żądanie, które należy poprawić przed ponownym próbowaniem.

Błędy 5xx wskazują na błędy serwera i żądanie można ponowić bez jego zmiany. W przypadku 503, wywołujący powinien respektować nagłówek odpowiedzi Retry-After i ponowić próbę dopiero po upływie czasu określonego w nagłówku.

Statusy zamówień

Zamówienie jest zawsze w jednym z następujących stanów:

Wartość stanu Opis
1 Nowe opłacone zamówienie
2  Obsługiwane
3  W drodze (tylko zamówienia z wysyłką)
4  Przygotowanie do odbioru osobistego – np. transport do oddziału
5  Gotowy do odbioru osobistego
6  Dostarczony do klienta – oczekuje na potwierdzenie przez klienta
7  Dostarczony i potwierdzony przez klienta
8  Klient odmówił potwierdzenia otrzymania zamówienia
9  Anulowane zamówienie

O zmianie statusu klient jest informowany drogą mailową.

Zamówienie nie musi koniecznie przechodzić przez wszystkie statusy, aby zostało pomyślnie dostarczone, z "Nowe zamówienie opłacone" można od razu przejść do "W drodze" / "Gotowe do odbioru osobistego", a następnie do "Dostarczone do klienta – oczekuje potwierdzenia przez klienta". Wykorzystanie wszystkich statusów prowadzi jednak do lepszego informowania klienta o postępach w realizacji zamówienia i jest zalecane.

Stany błędów

W przypadku kodów HTTP 4×x, odpowiedź zawsze zawiera klucz status (patrz książka kodów poniżej) oraz pole messages z tekstowymi opisami błędów.

Wartość statusu Opis
1  Nieważny wniosek – brakujące lub nieważne wartości
2  Nieprawidłowe dane logowania
3  Nieistniejące zamówienie
4  Nieistniejąca pozycja zamówienia
5  Przejście zlecenia w stan niedozwolony
6  Nieważne anulowanie – anulowanie większej liczby pozycji niż istnieje
7  Inny błąd
8  Zlecenie nie zostało jeszcze wyeksportowane do API partnera – nie można nim manipulować przez API
9  Aby przesyłka automatycznie ustawiała status "Towar dostarczony do klienta"

Przykład: 

{ "status": 3, "messages": [ "Order #1234 was not found." ] }

Typy danych.

Typy danych każdego klucza w żądaniach i odpowiedziach są zawsze opisane dla konkretnych punktów końcowych. Jeżeli nie określono inaczej, wartość w cudzysłowie "" jest zawsze obowiązkowym ciągiem znaków. O ile nie określono inaczej, wartość liczbowa jest zawsze obowiązkową liczbą całkowitą.

Komunikacja Slevomat ⇒ Partner

Ta część API jest zaimplementowana po stronie partnera i Slevomat ją wywołuje.

Wymagany główny adres URL API jest dostarczany przez partnera i powinien mieć postać 

 https://www.example.com/slevomat-zbozi-api/v1

Żądanie autoryzacji

Kiedy API jest włączone, partner otrzymuje partner_api_se­cret, który dowodzi, że przychodzące żądania są rzeczywiście od Slevomat.

Parametr ten jest przekazywany w nagłówku HTTP X-PartnerApiSecret.

Interfejs testowy

Slevomat zawiera funkcjonalność umożliwiającą wywołanie API po stronie partnera i obejrzenie odpowiedzi. Główny adres URL określony przez partnera podczas udostępniania API jest dołączany do -test, dzięki czemu w testach API jest wywoływane np. 

https://example­.com/slevomat-zbozi-api-test

aby uniknąć mieszania danych testowych z zamówieniami na żywo.

Testowanie partnerskiego API odbywa się poprzez zapytania POST na następujące adresy: 

  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/new-order
    - Nowe Zamówienie 
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/update-shipping-dates
    - Zbiorcza aktualizacja przewidywanych terminów wysyłki 
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/mark-delivered
    - Zmiana statusu zamówienia na "Dostarczono do klienta – oczekuje potwierdzenia przez klienta" 
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/ready-for-pickup
    - Zmień status zamówienia na "Gotowe do odbioru osobistego". 
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/confirm-delivery
    - Potwierdzenie dostawy 
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/reject-delivery
    - Odmowa przyjęcia 
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/cancel
    - anulowanie

Zastąp część <orderId> adresu URL dowolnym numerem zamówienia, żądania do API partnera są wykonywane z tym numerem zamówienia.

Żądania do tego interfejsu testowego muszą być autoryzowane za pomocą nagłówków X-PartnerToken i X-ApiSecret.

Podczas wykonywania testowego połączenia z partnerskim API system wysyła nagłówek X-PartnerApiSecret, tak jak w przypadku pracy na żywo.

Dane wysyłane z nowym zamówieniem są danymi testowymi i generowane losowo.

W przypadku wysyłania anulowania zamówienia należy w ciele POST żądania w JSON (w tym samym formacie, w jakim wysyła je API) zawrzeć pole items, które interfejs testowy zweryfikuje i przekaże do partnerskiego API w tej samej formie.

Nowe zamówienie

Żądanie zawiera dane nowo utworzonego zamówienia.

Zamówienia zawsze mają unikalny adres slevomatId. Jeśli API otrzyma duplikat slevomatId, żądanie powinno zostać zignorowane przez API partnera (pierwsze żądanie zostało ocenione jako nieudane przez Slevomat i dlatego zostało powtórzone), a odpowiedź powinna być również HTTP 204.

created jest datą w formacie ISO 8601, tj. YYYY-MM-DD'T'HH:mm:ss­+zz:zz.

productId zawiera identyfikator zdarzenia, variantId identyfikator zakupionego wariantu.

Opcjonalny internalId wskazuje na wewnętrzny identyfikator wprowadzony dla wariantu działania podczas jego tworzenia w interfejsie partnera. Jest on używany do identyfikacji produktu w systemie partnera.

W billingAddress (adres rozliczeniowy) obowiązkowa jest tylko nazwa klienta (name).

W shippingAddress (adres dostawy) firma (company) jest opcjonalna. W przypadku dostawy na adres shippingAddress zawiera on adres klienta, w przypadku odbioru osobistego adres placówki, w której klient odbierze towar.

Klucz delivery.type może przyjąć wartość address (dostawa na adres) lub pickup (odbiór osobisty). delivery.name zawiera nazwę transportu lub nazwę zakładu.

delivery.expec­tedShippingDa­te (przewidywana data wysyłki) i delivery.expec­tedDeliveryDa­te (przewidywana data dostawy) są danymi w formacie YYYY-MM-DD.

Klucz weight zawiera wagę zamówienia w kilogramach. Jeśli nie znamy wagi wszystkich pozycji w zamówieniu, przyjmuje on wartość null.

POST /order/$slevomatId 

{ "slevomatId": "721896899157", "created": "2021–08–25T15:14:24+02:00", "items": [ { "slevomatId": "960", "productId": "22", "variantId": "105", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "7577400222", "productId": "1752", "variantId": "9855", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": "Novák a syn", "street": "Vodičkova 32", "city": "Praha 1", "postalCode": "110 00", "country": "Česko" }, "shippingAddress": { "name": "Petr Novák", "company": null, "street": "Strašnická 8", "city": "Praha", "postalCode": "100 00", "phone": "+420777888999" }, "delivery": { "type": "address", "name": "PPL", "expectedShip­pingDate": "2021–08–27", "expectedDeli­veryDate": "2021–08–30", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

POST /order/$slevomatId 

{ "slevomatId": "124146766678", "created": "2021–09–01T12:49:37+02:00", "items": [ { "slevomatId": "863", "productId": "64", "variantId": "14", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "2364201450", "productId": "7057", "variantId": "5802", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": "Novák a syn", "street": "Vodičkova 32", "city": "Praha 1", "postalCode": "110 00", "country": "Česko" }, "shippingAddress": { "name": "Provozovna Jahodová", "company": null, "street": "Jahodová 33", "city": "Praha 10", "postalCode": "100 00", "phone": "+420222888999", "deliveryPremise": { "id": 45445, "name": "Provozovna Jahodová" } }, "delivery": { "type": "pickup", "name": "Osobní odběr na provozovně", "expectedShip­pingDate": "2021–09–02", "expectedDeli­veryDate": "2021–09–02", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

Masowa aktualizacja dat spodziewanych wysyłek

Jeśli deals manager, na prośbę partnera, masowo przesuwa daty wysyłki wybranych zamówień, system informuje API partnera o tej aktualizacji.

Wysyłane dane zawierają pole ID zamówienia oraz nową przewidywaną datę wysyłki. 

POST /update-shipping-dates
{ "expectedShip­pingDate": "2021–08–25", "slevomatIds": [ "123456", "45454544" ] }

Anulowanie zamówienia

Odwołania mogą być tworzone zarówno po stronie Slevomat jak i w systemie partnera. Ten punkt końcowy obsługuje tworzenie odwołania po stronie Slevomat i jego przekazanie do systemu partnera.

Tworzy on anulowanie pozycji zamówienia w określonej ilości. Jeśli całe zamówienie ma być anulowane, wszystkie pozycje z odpowiednią ilością są wymienione.

Poszczególne pozycje mogą być również anulowane częściowo (np. 1 z 2).

Notatka o anulowaniu (note) jest opcjonalna. 

POST /order/$slevo­matId/cancel
{ "items": [ { "slevomatId": "1212", "amount": 1 }, { "slevomatId": "4545454", "amount": 2 } ], "note": "storno v zákonné lhůtě" }

Potwierdzenie dostawy

Po oznaczeniu zamówienia jako "Dostarczone do klienta" poprosimy klienta o potwierdzenie, że faktycznie je otrzymał. Kiedy zamówienie zostanie oznaczone jako otrzymane, ten punkt końcowy zostanie wywołany. 

POST /order/$slevo­matId/confirm-delivery
{}

Odmowa przyjęcia 

POST /order/$slevo­matId/reject-delivery
{ "rejectionReason": "Důvod odmítnutí zákazníkem" }

Zmiana statusu zamówienia na "Gotowe do odbioru osobistego"

autoMarkRea­dyForPickuptrue Ten punkt końcowy zostanie wywołany, jeśli za pomocą previous ustawiono status "Gotowe do odbioru osobistego", a po stronie Slevomat zamówienie zostało automatycznie przełączone na "Gotowe do odbioru osobistego". 

POST /order/$slevo­matId/delivery-ready-for-pickup
{}

Zmień status zamówienia na "Dostarczone do klienta – oczekuje potwierdzenia przez klienta"

autoMarkDeli­veredtrue Ten punkt końcowy jest wywoływany, jeśli za pomocą previous ustawiono status "W drodze", "Gotowe do odbioru osobistego" lub "Gotowe do odbioru osobistego", a zamówienie zostało automatycznie przełączone na status "Dostarczone do klienta – oczekiwanie na potwierdzenie klienta" po stronie Slevomat. 

POST /order/$slevo­matId/mark-delivered
{}

Partner komunikacyjny ⇒ Slevomat

Ta część API jest zaimplementowana po stronie Slevomat i jest wywoływana przez system partnerski.

Główny adres URL API to. 

 https://www.slevomat.cz/zbozi-api/v1

Biblioteka PHP

Do implementacji tej strony API można wykorzystać przygotowaną bibliotekę PHP. Biblioteka ta wymaga obecnie PHP w wersji 5.4 lub wyższej i wymaga użycia Composera.

Instrukcja korzystania z biblioteki i kod źródłowy znajdują się na GitHubie.

Poproś o autoryzację

Kiedy API jest włączone, partner otrzymuje partner_token i api_secret, które są używane do uwierzytelniania się podczas wywoływania API Slevomat.

Parametry te są przekazywane w nagłówkach X-PartnerToken i X-ApiSecret.

Interfejs testowy

Główny adres URL interfejsu testowego to 

https://www.slevomat.cz/zbozi-api/v1-test

Można na nim wywoływać wszystkie akcje tak jak na interfejsie live.

Interfejs testowy sprawdza autoryzację żądań (poprawność tokena partnerskiego i sekretu API) oraz poprawność przychodzących ciał żądań (JSON). Pod tymi względami zachowuje się identycznie jak API na żywo.

Interfejs testowy nie pracuje jednak z rzeczywistymi zleceniami. Nie sprawdza więc, czy zamówienie przechodzi między prawidłowymi stanami i czy zawiera pozycje o podanych identyfikatorach. Po przejściu autoryzacji i walidacji formularza żądania, interfejs testowy zawsze odpowiada kodem sukcesu 200 lub 204. 

Tworzenie anulowania

Tworzy anulowanie pozycji zamówienia w podanej ilości. Jeśli zamówienie ma być anulowane w całości, na liście znajdują się wszystkie pozycje z odpowiednią ilością.

Poszczególne pozycje mogą być również anulowane częściowo (np. 1 z 2).

Notatka o anulowaniu (note) jest opcjonalna.

POST /order/$slevomatId/cancel 

{ "items": [ { "slevomatId": 45454, "amount": 15 } ], "note": "nepovinná poznámka" }

Zmiana statusu zamówienia na "Oczekujące"

POST /order/$slevomatId/mark-pending 

{}

Zmiana statusu zamówienia na "W drodze"

Dla zamówienia można użyć parametru autoMarkDelivered, aby określić, czy powinno ono automatycznie przejść do statusu "Dostarczone do klienta – oczekuje na potwierdzenie klienta" po ustalonym czasie wysyłki ("Czas od wysyłki do dostawy").

Odpowiedź zawiera zaktualizowaną szacunkową datę dostawy.

POST /order/$slevomatId/mark-en-route 

{ "autoMarkDeli­vered": true }

Odpowiedź 200 

{ "expectedDeli­veryDate": "2021–08–25" }

Zmiana statusu zamówienia na "Gotowe do odbioru osobistego"

Za pomocą parametru autoMarkReady­ForPickup można określić, czy zamówienie ma być automatycznie przełączane na status "Gotowe do odbioru osobistego" po upływie czasu od wysłania do dostarczenia dla danego typu punktu odbioru.

Dla zamówienia można użyć parametru autoMarkDelivered, aby określić, czy powinno ono automatycznie przechodzić ze statusu "Gotowe do odbioru osobistego" do statusu "Dostarczone do klienta – oczekuje na potwierdzenie klienta" po ustalonej liczbie dni na odbiór w danym typie punktu odbioru.

Kombinacja parametrów autoMarkReady­ForPickup false i autoMarkDelivered true jest niedozwolona. W takim przypadku zostanie zwrócony kod błędu 9. 

Odpowiedź zawiera zaktualizowaną oczekiwaną datę dostawy.

POST /order/$slevomatId/mark-gotowy-do-odbioru 

{ "autoMarkReady­ForPickup": true, "autoMarkDeli­vered": true }

Odpowiedź 200 

{ "expectedDeli­veryDate": "2021–08–25" }

Zmiana statusu zamówienia na "Gotowe do odbioru osobistego"

Za pomocą parametru autoMarkDelivered można określić, czy zamówienie ma być automatycznie przełączane do statusu "Dostarczone do klienta – oczekuje na potwierdzenie klienta" po ustalonej liczbie dni do odbioru w danym typie punktu odbioru. 

POST /order/$slevo­matId/mark-ready-for-pickup
{ "autoMarkDeli­vered": true }

Zmiana statusu zamówienia na "Dostarczone do klienta – oczekuje na potwierdzenie klienta" 

POST /order/$slevo­matId/mark-delivered
{}

Zmień adres dostawy

Adres dostawy można zmienić tylko w przypadku dostawy na adres (tzn. nie można zmienić miejsca odbioru osobistego).

Wymagane są wszystkie klucze oprócz company.

Prawidłowe wartości dla klucza state to cz (Republika Czeska) i sk (Słowacja). 

POST /order/$slevo­matId/update-shipping-address
{ "name": "Karel Novák", "street": "Pod horou 34", "city": "Pardubice", "postalCode": "530 00", "state": "CZ", "phone": "+420777888999", "company": "Knihkupectví Novák" }

Changelog

Powrót do listy artykułów

Súvisiace články
Nahoru