API Towary stron trzecich

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

Zamówienia wyeksportowane do API partnera nie mogą być już modyfikowane w interfejsie partnera Zlavomat, można je jedynie przeglądać. Wyeksportowanymi zamówieniami można teraz manipulować 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ępność API

Dostęp do API można uzyskać w zakładce Ustawienia w interfejsie partnera. Aby pobrać dane, należy wprowadzić główny adres URL części partnerskiej API, wybierając opcję Zlavomat → Partner, np.

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

Dane dostępowe zostaną wyświetlone dopiero po uzyskaniu dostępu do interfejsu API, dlatego należy je chronić.

Po udostępnieniu API system rozpocznie eksportowanie do niego nowo utworzonych zamówień.

Początkowy eksport danych

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

Jeśli w swoim systemie posiadasz już 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 – żądanie zostało pomyślnie przetworzone
• 204 No Content – żądanie zostało pomyślnie przetworzone, odpowiedź nie zawiera treści
• 400 Bad Request – żądanie jest nieprawidłowe – może brakować parametrów lub są one nieprawidłowe w porównaniu ze specyfikacją
• 403 Forbidden – autoryzacja klienta nie powiodła się
• 404 Not Found – nie znaleziono punktu końcowego lub żądanych danych
• 405 Method Not Allowed – punkt końcowy nie obsługuje tej metody protokołu HTTP
• 422 Unprocessable Entity – oczekiwany błąd podczas przetwarzania żądania (patrz sekcja Stany 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 znajduje się w trybie konserwacyjnym (może być w trakcie wdrażania nowej wersji lub planowane jest przestoje)
• 504 Gateway Timeout – wystąpił błąd po stronie serwera

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

W przypadku błędów4xx W żądaniu wychodzącym wystąpił błąd. Przed ponowną próbą należy go naprawić.

Błędy5xx wskazują błędy serwera i żądanie można powtórzyć bez jego zmiany. W przypadku503 osoba dzwoniąca powinna uszanować nagłówek odpowiedziRetry-After i powtórz kolejną próbę dopiero po upływie czasu określonego w nagłówku.

Statusy zamówień

Zamówienie zawsze posiada jeden z poniższych statusów:

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

Zamówienie nie musi koniecznie przejść przez wszystkie statusy, aby zostało pomyślnie dostarczone; ze statusu „Nowe opłacone zamówienie” można przejść bezpośrednio do statusu „W drodze” / „Gotowe do odbioru osobistego”, a następnie do statusu „Dostarczone do klienta – oczekuje na potwierdzenie przez klienta”. Korzystanie ze wszystkich statusów zapewnia jednak lepsze informacje o postępach realizacji zamówienia i zalecamy to.

Stany błędów

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

Próbka:

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

Typy danych

Typy danych poszczególnych kluczy w żądaniach i odpowiedziach są zawsze opisywane dla konkretnych punktów końcowych. O ile nie zaznaczono inaczej, wartość w cudzysłowie."" jest zawsze wymaganym ciągiem znaków. O ile nie określono inaczej, wartość liczbowa jest zawsze wymaganą liczbą całkowitą.

Maszyna do Rabatów Komunikacyjnych ⇒ Partner

Ta część API jest implementowana po stronie partnera i nazywana jest przez Zlavovamat.

Wymagany główny adres URL interfejsu API zostanie udostępniony przez partnera i powinien mieć postać

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

Autoryzacja żądań

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

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

Interfejs testowy

Maszyna rabatowa obejmuje funkcjonalność umożliwiającą wywołanie API po stronie partnera i wyświetlenie odpowiedzi. Główny adres URL określony przez partnera podczas udostępniania API jest dołączony do-test , więc w ramach testowania API jest wywoływane na przykład

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.zlavomat.sk/test-zbozi-partner-api/v1/new-order

   – Nowe zamówienie

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/update-shipping-dates

   – Masowa aktualizacja przewidywanych dat wysyłki

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/mark-delivered

   – Zmiana statusu zamówienia na „Dostarczone do klienta – oczekiwanie na potwierdzenie przez klienta”

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/ready-for-pickup

   – Zmiana statusu zamówienia na „Gotowe do odbioru osobistego”

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/confirm-delivery 

   – Potwierdzenie dostawy

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/reject-delivery

   – Odmowa przyjęcia

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/cancel

   – Anulować

Część adresu URL<orderId> zastąp dowolnym numerem zamówienia; żądania do interfejsu API partnera będą wysyłane z użyciem tego numeru zamówienia.

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

Podczas testowania wywołania interfejsu API partnera system wysyła nagłówekX-PartnerApiSecret tak jak podczas normalnej eksploatacji.

Dane przesłane wraz z nowym zamówieniem mają charakter testowy i są generowane losowo.

W przypadku wysyłania anulowania zamówienia konieczne jest dołączenie pola JSON do treści żądania POST.items (w tym samym formacie, w jakim wysyłane jest przez API), który interfejs testowy weryfikuje i przesyła do API partnera w tej samej formie.

Nowe zamówienie

Zapytanie zawiera dane nowo utworzonego zamówienia.

Zamówienia są zawsze wyjątkowezlavomatId Jeśli w interfejsie API pojawi się duplikatzlavomatId Interfejs API partnera powinien zignorować żądanie (pierwsze żądanie wysłane przez Zľavomat zostało ocenione jako nieudane, dlatego je powtarzamy) i odpowiedzieć kodem HTTP 204.

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

productId zawiera identyfikator akcji, variantId Identyfikator zakupionego wariantu.

FakultatywnyinternalId Oznacza wewnętrzny identyfikator wprowadzony dla wariantu akcji podczas jego tworzenia w interfejsie partnera. Służy do identyfikacji produktu w systemie partnera.

WbillingAddress (adres rozliczeniowy) wymagane jest tylko imię i nazwisko ()name ) klienta.

WshippingAddress (adres dostawy) jest opcjonalnym polem firmy (company ). W przypadku dostawy na adresshippingAddress zawiera adres Klienta, a w przypadku odbioru osobistego adres sklepu, w którym Klient odbierze towar.

Klawiszdelivery .type może przyjmować wartościaddress (dostawa na adres) lubpickup (odbiór osobisty).delivery .name zawiera nazwę transportu lub nazwę operacji.

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

Klawiszweight Zawiera wagę zamówienia w kilogramach. Jeśli nie znamy wagi wszystkich pozycji w zamówieniu, przyjmuje wartośćnull .

POST /order/$slevomatId

{ "slevomatId": "480058070336", "created": "2021–09–06T16:39:02+02:00", "items": [ { "slevomatId": "7767", "productId": "25", "variantId": "194", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "4764573102", "productId": "3065", "variantId": "385", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": null, "street": null, "city": null, "postalCode": null, "country": null }, "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–09–08", "expectedDeli­veryDate": "2021–09–11", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

POST /order/$slevomatId

{ "slevomatId": "286238184713", "created": "2021–09–06T16:39:02+02:00", "items": [ { "slevomatId": "3461", "productId": "9", "variantId": "136", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "2320086446", "productId": "2855", "variantId": "7027", "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–07", "expectedDeli­veryDate": "2021–09–07", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

Masowa aktualizacja przewidywanych dat wysyłki

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

Przesłane dane zawierają pole z identyfikatorem zamówienia i nową przewidywaną datą wysyłki.

POST /update-shipping-dates

{ "expectedShip­pingDate": "2021–09–06", "slevomatIds": [ "123456", "45454544" ] }

Anulować

Anulacje można tworzyć zarówno po stronie Zlavomat, jak i w systemie partnerskim. Ten punkt końcowy obsługuje tworzenie anulacji po stronie Zlavomat i ich przesyłanie do systemu partnerskiego.

Tworzy anulowanie zamówienia dla pozycji w określonej ilości. Jeśli całe zamówienie ma zostać anulowane, wyświetlane są wszystkie pozycje w odpowiedniej ilości.

Poszczególne pozycje można również częściowo anulować (np. 1 sztukę z dwóch).

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 je faktycznie otrzymał. Po oznaczeniu zamówienia jako otrzymanego, zostanie wywołany ten punkt końcowy.

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”

Ten punkt końcowy zostanie wywołany, jeśli poprzedni status „Przygotowanie do odbioru osobistego” został ustawiony naautoMarkRea­dyForPickuptrue a po stronie Zlavomat zamówienie automatycznie przeszło w status „Gotowe do odbioru osobistego”

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

{}

Zmiana statusu zamówienia na „Dostarczone do klienta – oczekiwanie na potwierdzenie przez klienta”

Ten punkt końcowy zostanie wywołany, jeśli poprzedni status został ustawiony na „W drodze”, „Przygotowywanie do odbioru osobistego” lub „Gotowy do odbioru osobistego”autoMarkDeli­veredtrue a po stronie Zlavomat zamówienie automatycznie zmieniło status na „Dostarczone do klienta – oczekuje na potwierdzenie przez klienta”.

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

{}

Partner komunikacyjny ⇒ Maszyna rabatowa

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

Główny adres URL interfejsu API to

https://www.zlavomat.sk/zbozi-api/v1

Biblioteka PHP

Aby zaimplementować tę stronę API, możesz skorzystać z gotowej biblioteki PHP. Biblioteka wymaga obecnie wersji PHP 5.4 lub nowszej i zakłada korzystanie z narzędzia Composer.

Instrukcje dotyczące biblioteki i kod źródłowy można znaleźć na GitHub .

Autoryzacja żądań

Po włączeniu API partner otrzymujepartner_token Iapi_secret , który jest używany do udowodnienia podczas wywoływania API Zlavomat.

Te parametry są przekazywane w nagłówkachX-PartnerToken IX-ApiSecret .

Interfejs testowy

Główny adres URL interfejsu testowego to

https://www.zlavomat.sk/zbozi-api/v1-test

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

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

Interfejs testowy nie działa jednak z rzeczywistymi zamówieniami. Nie weryfikuje on, czy zamówienie przechodzi między prawidłowymi stanami i czy zawiera pozycje o podanych identyfikatorach. Po pomyślnej autoryzacji i walidacji formularza zamówienia, interfejs testowy zawsze odpowiada kodem powodzenia 200 lub 204.

Utwórz anulowanie

Utwórz pozycje do anulowania zamówienia w określonej ilości. Jeśli całe zamówienie ma zostać anulowane, wszystkie pozycje z odpowiednią ilością zostaną wyświetlone.

Poszczególne pozycje można również częściowo anulować (np. 1 sztukę z dwóch).

Notatka o anulowaniu (note ) jest opcjonalne.

POST /order/$slevomatId/cancel

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

Zmiana statusu zamówienia na „Przetwarzanie”

POST /order/$slevomatId/mark-pending

{}

Zmiana statusu zamówienia na „W drodze”

Przy składaniu zamówienia należy podać parametrautoMarkDelivered określ, czy status ma automatycznie zmienić się na „Dostarczone do klienta – oczekiwanie na potwierdzenie przez klienta” po ustawionym okresie transportu („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 „Przygotowanie do odbioru osobistego”

Przy składaniu zamówienia należy podać parametrautoMarkReady­ForPickup określić, czy status ma zostać automatycznie zmieniony na „Gotowy do odbioru osobistego” po upływie czasu od nadania do dostarczenia dla danego typu punktu odbioru.

Przy składaniu zamówienia należy podać parametrautoMarkDelivered określ, czy status ma się automatycznie zmieniać z „Gotowe do odbioru osobistego” na „Dostarczone do klienta – oczekiwanie na potwierdzenie przez klienta” po upływie określonej liczby dni od odbioru w danym punkcie odbioru.

Kombinacja parametrówautoMarkReady­ForPickup fałszywy iautoMarkDelivered Wartość true jest niedozwolona. W takim przypadku zwracany jest kod błędu 9.

Odpowiedź zawiera zaktualizowaną szacunkową datę dostawy.

POST /order/$slevomatId/mark-getting-ready-for-pickup

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

Odpowiedź 200

{ "expectedDeli­veryDate": "2021–09–06" }

Zmiana statusu zamówienia na „Gotowe do odbioru osobistego”

Przy składaniu zamówienia należy podać parametrautoMarkDelivered określ, czy status ma zostać automatycznie zmieniony na „Dostarczone do klienta – oczekiwanie na potwierdzenie przez klienta” po upływie ustalonej liczby dni odbioru dla danego typu punktu odbioru.

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

{ "autoMarkDeli­vered": true }

Zmiana statusu zamówienia na „Dostarczone do klienta – oczekiwanie na potwierdzenie przez klienta”

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

{}

Zmiana adresu dostawy

Adres dostawy można zmienić jedynie w przypadku doręczenia przesyłki pod wskazany adres (tj. nie można zmienić miejsca odbioru).

Wszystkie klucze opróczcompany są obowiązkowe.

Prawidłowe wartości dla kluczastate Czycz (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" }