API stron trzecich

API służy do przesyłania informacji o zamówieniach między Slevomat a systemem naszego partnera handlowego. API wymaga implementacji komunikacji dwukierunkowej – system Slevomat wywołuje API partnera, a partner wywołuje API Slevomat.

Zamówienia eksportowane do API partnera nie mogą być już manipulowane w interfejsie partnera Slevomat, można je tylko przeglądać. Manipulowanie eksportowanymi zamówieniami może odbywać się tylko za pośrednictwem API.

Wszystkie żądania muszą być przesyłane za pomocą protokołu HTTPS, a wszystkie dane muszą być 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, należy podać główny adres URL części partnerskiej API do użycia w kierunku Slevomat → Partner, np.

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

Dane dostępowe zostaną wyświetlone tylko raz przy próbie dostępu do interfejsu API. Prosimy o ich ostrożne zapisanie.

Po uzyskaniu dostępu do API system rozpocznie eksportowanie nowo utworzonych zamówień.

Początkowy eksport danych

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

Jeśli w swoim systemie posiadasz istniejące zamówienia (utworzone przed udostępnieniem API) i chcesz zacząć z nimi pracować za pośrednictwem API, skorzystaj z funkcji „Rozpocznij pracę z oznaczonymi zamówieniami za pośrednictwem API” w menu „Działania zbiorcze na zamówieniach”.

Opis typowych odpowiedzi HTTP

• 200 OK – prośba została pomyślnie przetworzona
• 204 No Content – żądanie zostało przetworzone, odpowiedź nie zawiera treści
• 400 Bad Request – żądanie jest nieprawidłowe – mogą występować brakujące lub nieprawidłowe parametry 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 – oczekiwany błąd podczas przetwarzania żądania (patrz sekcja Warunki błędu )
• 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 znajduje się w trybie konserwacji (może być w trakcie wdrażania nowej wersji lub planowany jest przestój)
• 504 Gateway Timeout – wystąpił błąd po stronie serwera

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

W przypadku4xx błędy, żądanie wychodzące jest błędne i należy je poprawić przed ponowną próbą.

Błędy5xx wskaż błędy serwera i żądanie może zostać ponowione bez jego zmiany. W przypadku503 , osoba dzwoniąca powinna uszanowaćRetry-After nagłówek odpowiedzi i ponów próbę dopiero po upływie czasu określonego w nagłówku.

Statusy zamówień

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

O każdej zmianie statusu klient jest informowany drogą mailową.

Zamówienie nie musi koniecznie przechodzić przez wszystkie statusy, aby pomyślnie dostarczyć, z „Nowe zamówienie opłacone” można przejść bezpośrednio do „Towary wysłane” / „Gotowe do odbioru osobistego”, a następnie do „Dostarczone do klienta – oczekuje na potwierdzenie przez klienta”. Korzystanie ze wszystkich statusów prowadzi jednak do lepszych informacji klienta o postępie realizacji zamówienia i jest zalecane.

Stany błędów

W przypadku kodów HTTP 4×x odpowiedź zawsze zawiera kluczstatus (zobacz poniższy kod) i polemessages z opisami tekstowymi błędów.

Przykład:

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

Typy danych

Typy danych każdego klucza w żądaniach i odpowiedziach są zawsze opisywane dla określonych punktów końcowych. O ile 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 implementowana po stronie partnera i jest wywoływana przez Slevomat.

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

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

Żądanie autoryzacji

Po włączeniu API partner otrzymujepartner_api_se­cret , co dowodzi, że przychodzące żądania rzeczywiście pochodzą ze Slevomat.

Ten parametr jest przekazywany w nagłówku HTTPX-PartnerApiSecret .

Interfejs testowy

Slevomat obejmuje funkcjonalność umożliwiającą wywołanie API po stronie partnera i wyświetlenie odpowiedzi. Główny adres URL określony przez partnera, gdy API jest udostępniane, jest dołączany do-test , tak aby podczas testowania API było wywoływane np.

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

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

Testowanie interfejsu API partnera odbywa się za pomocą żądań POST wysyłanych 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 

   – Masowa aktualizacja przewidywanych dat wysyłki

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/mark-delivered 

   – Zmień status zamówienia na „Dostarczone do klienta – oczekiwanie na potwierdzenie 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<orderId> część adresu URL zawierająca dowolny numer zamówienia, żądania do interfejsu API partnera są wysyłane z użyciem tego numeru zamówienia.

Żądania do tego interfejsu testowego muszą zostać autoryzowane za pomocą nagłówkówX-PartnerToken IX-ApiSecret .

Podczas wykonywania połączenia testowego do interfejsu API partnera system wysyłaX-PartnerApiSecret nagłówek, tak jak ma to miejsce podczas pracy na żywo.

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

W przypadku wysłania anulowania zamówienia należy dołączyćitems pole w treści POST żądania w formacie JSON (w tym samym formacie, w jakim jest wysyłane przez API), które interfejs testowy zweryfikuje i przekaże do API partnera w tej samej formie.

Nowe zamówienie

Żądanie zawiera dane nowo utworzonego zamówienia.

Zamówienia zawsze mają unikalnyslevomatId . Jeśli API otrzyma duplikatslevomatId , żądanie powinno zostać zignorowane przez API partnera (pierwsze żądanie zostało ocenione jako nieudane przez Slevomat i dlatego 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 ID zakupionego wariantu.

OpcjonalnieinternalId wskazuje wewnętrzny identyfikator wprowadzony dla wariantu akcji, gdy jest on tworzony w interfejsie partnera. Służy do identyfikacji produktu w systemie partnera.

WbillingAddress (adres rozliczeniowy) tylko imię i nazwisko klienta (name ) jest obowiązkowe.

WshippingAddress (adres dostawy) firma (company ) jest opcjonalne. W przypadku dostawy doshippingAddress zawiera adres Klienta, a w przypadku odbioru osobistego adres placówki, w której Klient odbierze towar.

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

delivery .expec­tedShippingDa­te (szacowana data wysyłki) idelivery .expec­tedDeliveryDa­te (szacowana data dostawy) to dane w formacieYYYY-MM-DD .

Kluczweight zawiera wagę zamówienia w kilogramach. Jeśli nie znamy wagi wszystkich elementów zamówienia, przyjmuje 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 przewidywanych dat wysyłki

Jeżeli menedżer ds. transakcji na prośbę partnera zmieni daty wysyłki wybranych zamówień, system poinformuje API partnera o tej zmianie.

Wysłane dane zawierają pole identyfikatora zamówienia i nową przewidywaną datę wysyłki.

POST /update-shipping-dates

{ "expectedShip­pingDate": "2021–08–25", "slevomatIds": [ "123456", "45454544" ] }

Anulowanie

Anulacje mogą być tworzone zarówno po stronie Slevomat, jak i po stronie systemu partnera. Ten punkt końcowy obsługuje tworzenie anulowania po stronie Slevomat i jego transfer do systemu partnera.

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

Można również anulować częściowo poszczególne pozycje (np. 1 z 2).

Notatka o anulowaniu (note ) jest opcjonalne.

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ł. Gdy 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" }

Zmień status zamówienia na „Gotowe do odbioru osobistego”

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

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

{}

Zmień status zamówienia na „Dostarczone do klienta – oczekiwanie na potwierdzenie przez klienta”

Ten punkt końcowy jest wywoływany, jeśli poprzedni status „W drodze”, „Gotowy do odbioru osobistego” lub „Gotowy do odbioru osobistego” został ustawiony za pomocąautoMarkDeli­veredtrue a zamówienie automatycznie zmieniło status na „Dostarczone do klienta – oczekiwanie na potwierdzenie przez klienta” po stronie Slevomat.

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

{}

Partner komunikacyjny ⇒ Slevomat

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

Główny adres URL interfejsu API to

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

Biblioteka PHP

Aby zaimplementować tę stronę API, możesz użyć przygotowanej biblioteki PHP. Biblioteka obecnie wymaga PHP 5.4 lub nowszego i wymaga użycia Composera.

Instrukcje dotyczące korzystania z biblioteki i kodu źródłowego można znaleźć na GitHub .

Poproś o autoryzację

Po włączeniu API partner otrzymujepartner_token Iapi_secret , które służą do uwierzytelniania podczas wywoływania interfejsu API Slevomat.

Te parametry są przekazywane wX-PartnerToken IX-ApiSecret nagłówki.

Interfejs testowy

Główny adres URL interfejsu testowego to

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

Wszystkie akcje można wywołać tak samo, jak w interfejsie na żywo.

Interfejs testowy sprawdza autoryzację żądań (poprawność tokenu partnera i sekretu API) oraz ważność przychodzących ciał żądań (JSON). Pod tym względem zachowuje się identycznie jak API na żywo.

Jednak interfejs testowy nie działa z rzeczywistymi zamówieniami. W związku z tym nie weryfikuje, czy zamówienie przechodzi między prawidłowymi stanami i czy zawiera elementy o podanych identyfikatorach. Po przejściu autoryzacji i walidacji formularza żądania interfejs testowy zawsze dopasowuje kod powodzenia 200 lub 204.

Tworzenie anulowania

Tworzy anulowanie pozycji zamówienia w określonej ilości. Jeśli zamówienie ma zostać anulowane w całości, wszystkie pozycje z odpowiadającą ilością są wymienione.

Można również anulować częściowo poszczególne pozycje (np. 1 z 2).

Notatka o anulowaniu (note ) jest opcjonalne.

POST /order/$slevomatId/cancel

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

Zmień status zamówienia na „Oczekujące”

POST /order/$slevomatId/mark-pending

{}

Zmień status zamówienia na „Towar wysłany”

W celu złożenia zamówienia, autoMarkDelivered Parametru można użyć do określenia, czy status ma zostać automatycznie przełączony na „Dostarczone do klienta – oczekiwanie na potwierdzenie przez klienta” po upływie określonego czasu wysyłki („Czas od wysyłki do dostawy”).

Odpowiedź zawiera zaktualizowaną szacowaną datę dostawy.

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

{ "autoMarkDeli­vered": true }

Odpowiedź 200

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

Zmień status zamówienia na „Gotowe do odbioru osobistego”

Możesz użyć parametruautoMarkReady­ForPickup aby określić, czy zamówienie ma zostać automatycznie przełączone na status „Gotowe do odbioru osobistego” po upływie czasu od wysłania do dostarczenia dla danego typu punktu odbioru.

W przypadku zamówienia, autoMarkDelivered parametru można użyć, aby określić, czy przesyłka ma zostać automatycznie przełączona ze statusu „Gotowe do odbioru osobistego” na status „Dostarczone do klienta – oczekiwanie na potwierdzenie przez klienta” po upływie określonej liczby dni od momentu odbioru w danym punkcie odbioru.

Połączenie parametrówautoMarkReady­ForPickup fałszywy iautoMarkDelivered true nie jest dozwolone. W tym przypadku zostanie zwrócony kod błędu 9.

Odpowiedź zawiera zaktualizowaną przewidywaną datę dostawy.

POST /order/$slevomatId/oznacz-gotowosc-do-odbioru

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

Odpowiedź 200

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

Zmień status zamówienia na „Gotowe do odbioru osobistego”

TenautoMarkDelivered parametru można użyć do określenia, czy zamówienie ma zostać automatycznie przełączone na status „Dostarczone do klienta – oczekiwanie na potwierdzenie przez klienta” po określonej liczbie dni w celu odbioru w danym punkcie odbioru.

POST /order/$slevo­matId/mark-ready-for-pickup

{ "autoMarkDeli­vered": true }

Zmień status zamówienia na „Dostarczone do klienta – oczekiwanie na potwierdzenie przez klienta”

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

{}

Zmień adres dostawy

Zmiana adresu dostawy jest możliwa wyłącznie w przypadku dostawy na adres (tj. nie można zmienić miejsca odbioru osobistego).

Wszystkie klucze opróczcompany są wymagane.

Prawidłowe wartości dlastate Kluczem jestcz (Czechy) isk (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" }

Dziennik zmian