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

API Towary stron trzecich

Ten artykuł został przetłumaczony maszynowo.

API służy do przekazywania informacji o zamówieniach pomiędzy Dyskontomatem a systemem partnera handlowego. API wymaga implementacji dwustronnej komunikacji komunikacji – system Dyskontomat wywołuje API partnera, a partner wywołuje API Dyskontomat.

W przypadku zleceń eksportowanych do API partnera nie jest już możliwe można manipulować w interfejsie partnera, a jedynie je przeglądać. Manipulacja wyeksportowanymi zleceniami może odbywać się tylko poprzez API.

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

Dostępność API

Możesz uzyskać dostęp do API z zakładki Ustawienia w swoim Interfejsu Partnera. Aby uzyskać dane, należy wprowadzić kod główny URL partnerskiej części API do użycia w kierunku Zlevomat → Partner, np.

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

Dane dostępowe będą wyświetlane tylko w przypadku dostępu do API, przeczytaj je uważnie. przechowuj je starannie.

Po uzyskaniu dostępu do API, nowo utworzone zamówienia są do niego wprowadzane przez system rozpocznie eksport zleceń do systemu.

Początkowy eksport danych

W celu przepełnienia istniejących zleceń w momencie udostępnienia API Można skorzystać z jednorazowego eksportu do CSV w interfejsie partnera.

W momencie, gdy masz istniejące zamówienia (utworzone przed API) we własnym systemie i chcesz rozpocząć pracę z nimi poprzez API, użyj funkcji "Rozpocznij pracę z zaznaczonymi zamówieniami przez API" w "Zbiorczych działaniach z zamówieniami". w menu "Masowe akcje ze zleceniami".

Opis typowych odpowiedzi HTTP

  • 200 OK – wniosek został zrealizowany pomyślnie
  • 204 No Content – zapytanie zostało przetworzone pomyślnie, odpowiedź nie ma treści
  • 400 Bad Request – żądanie nie jest prawidłowe – może może brakować parametrów lub mogą być one nieprawidłowe w stosunku do specyfikacji
  • 403 Forbidden – autoryzacja klienta nie powiodła się
  • 404 Not Found – punkt końcowy lub żądane dane nie zostały znalezione
  • 405 Method Not Allowed – punkt końcowy nie obsługuje tej metody protokołu HTTP. metodę protokołu HTTP
  • 422 Unprocessable Entity – spodziewany błąd podczas przetwarzania żądania (patrz rozdział Warunki błędów )
  • 500 Internal Server Error – wystąpił błąd na stronie serwer
  • 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 serwer

Odpowiedzi HTTP 5×x nie mogą wykorzystywać formatu JSON.

W przypadku błędów 4xx, błąd znajduje się w wychodzącym żądaniu i i należy go poprawić przed ponowieniem próby.

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

Stany zamówień

Zlecenie jest zawsze w jednym z poniższych stanów:

Wartość stanu Opis
1 Nowe opłacone zlecenie
2 W trakcie realizacji
3 W drodze (zamówienia tylko z wysyłką)
4 W przygotowaniu do odbioru osobistego – np. w tranzycie do oddziału
5 Gotowe do odbioru osobistego
6 Dostarczony do klienta – oczekuje na potwierdzenie przez klienta
7 Dostarczony i potwierdzony przez klienta
8 Klient odmówił potwierdzenia przyjęcia zamówienia
9 Zamówienie anulowane

O każdej zmianie statusu klient jest informowany e‑mailem.

Zamówienie nie musi przechodzić przez wszystkie statusy, aby zostało pomyślnie dostawy, możliwe jest przejście od razu ze statusu "Nowe opłacone zamówienie" do statusu "W drodze" / "Gotowe do wysyłki". do "W drodze" / "Gotowe do odbioru", a następnie do "Dostarczono do klienta – oczekiwanie na potwierdzenie przez klienta". Korzystanie z wszystkich statusów prowadzi jednak do lepszego informowania klienta o postępie zamówienia i zalecamy to.

Stany błędów

W przypadku kodów HTTP 4×x, odpowiedź zawsze zawiera klucz status (patrz lista kodów poniżej) oraz pole messages z tekstowym opisem błędów.

Wartość stanu Opis
1 Nieprawidłowy wniosek – brak lub nieprawidłowe wartości
2 Nieprawidłowe dane uwierzytelniające
3 Nieistniejące zamówienie
4 Nieistniejąca pozycja zamówienia
5 Przejście zlecenia do stanu niedozwolonego
6 Nieprawidłowe anulowanie – anulowanie większej ilości pozycji niż istnieje
7 Inny błąd
8 Zamówienie nie zostało jeszcze wyeksportowane do API partnera – nie jest nie może być obsługiwane przez API
9 Aby automatycznie ustawić status "Towar dostarczony do klienta" konieczne jest, aby przesyłka automatycznie miała status "Towar gotowy gotowy do odbioru"

Przykład:

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

Typy danych.

Typy danych poszczególnych kluczy w zapytaniach i odpowiedziach są są zawsze opisane dla określonych punktów końcowych. O ile nie podano inaczej, wartość w cudzysłowie "" jest zawsze obowiązkowym łańcuchem znaków. Jeżeli nie określono inaczej wartość liczbowa jest zawsze obowiązkową liczbą całkowitą.

Dyskomat komunikacyjny ⇒ Partner

Ta część API jest zaimplementowana po stronie partnera i jest używana przez Zlevomat połączenia.

Wymagany główny adres URL API jest udostępniany przez partnera, powinien mieć postać

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

Autoryzacja żądania

Kiedy API jest włączone, partner otrzymuje partner_api_se­cret, który przychodzące żądania są weryfikowane, czy rzeczywiście pochodzą od Rabat.

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

Interfejs testowy

Dyskontomat zawiera funkcjonalność pozwalającą na wywołanie API po stronie partnera i wyświetlania odpowiedzi. Do głównego adresu URL określonego przez partnera podczas dostępu do API -test jest dołączony do adresu URL partnera, tak że w testach jest on nazywany API np.

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

aby uniknąć mieszania się danych testowych z rzeczywistymi zleceniami.

Testowanie API partnera odbywa się za pomocą żądań POST na następujące adresy:

Część adresu URL <orderId> należy zastąpić dowolną liczbą numer zamówienia, z tym numerem zamówienia żądania są przekazywane do Partnera API.

Żądania do tego interfejsu testowego muszą być autoryzowane z nagłówkami X-PartnerToken i X-ApiSecret.

Kiedy testowe wywołanie jest wykonywane do API partnera, system wysyła nagłówek X-PartnerApiSecret nagłówek tak samo jak w przypadku pracy na żywo.

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

W przypadku wysyłania anulowania zamówienia, w treści POST żądania, zawiera w polu JSON nagłówek items (w takim samym formacie jak wysłane przez API), które zostanie zweryfikowane przez interfejs testowy i wysłane do partnerskiego API. API przekaże je w tym samym formacie.

Nowe zamówienie

Żądanie zawiera dane nowo utworzonego zamówienia.

Zlecenia mają zawsze unikalny adres zlavomatId. Jeśli do API pojawi się duplikat zlavomatId, żądanie powinno zostać go zignorować (pierwsze skonwertowane żądanie zostało ocenione przez Dyskontomat jako nieudane i więc powtarzamy je) i odpowiedzieć również HTTP 204.

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

productId zawiera identyfikator zdarzenia, variantId identyfikator zakupionego wariantu.

Opcjonalny internalId oznacza wewnętrzny identyfikator wprowadzony podczas wariantu działania, gdy jest on tworzony w interfejsie partnera. Służy do identyfikacji produktu w systemie partnera.

W billingAddress (adres rozliczeniowy) obowiązkowe jest tylko nazwisko (name) klienta.

W shippingAddress (adres dostawy) firma jest opcjonalna (company). W przypadku dostawy do shippingAddress zawiera adres klienta, w przypadku dostawy osobistej przy dostawie osobistej adres placówki, w której klient odbiera towar.

Klucz delivery.type może przyjmować wartości address (dostawa na adres) lub pickup (odbiór osobisty). odbiór osobisty). delivery.name zawiera nazwę transportu lub nazwę operacji.

delivery.expec­tedShippingDa­te (przewidywana data wysyłki) oraz delivery.expec­tedDeliveryDa­te (przewidywana data doręczenia) to dane w formacie YYYY-MM-DD .

Klucz weight zawiera wagę zamówienia w kilogramach. W przypadku, gdy nie znamy wagi wszystkich pozycji w zamówieniu, przyjmuje on 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śli menedżer transakcji, na prośbę partnera, przesuwa dane masowe daty wysyłki dla wybranych zamówień, system informuje API partnera o tej aktualizacji. aktualizacji.

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

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

Anulacje

Anulacje można tworzyć zarówno po stronie Rabatu jak i partnera systemu. Ten punkt końcowy obsługuje tworzenie anulacji po stronie Zlavomat i jej przeniesienie do systemu partnera.

Tworzy on anulowanie pozycji zamówienia w podanej ilości. Jeśli całe zamówienie zostanie anulowane, wszystkie pozycje zostaną wymienione z odpowiednią ilością. ilością.

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

Informacja o anulowaniu zamówienia (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 "Dostarczono do klienta" ty my poprosimy klienta o potwierdzenie, e zamówienie zostao dostarczone. Kiedy zamówienie jest zostanie oznaczone jako odebrane, zostanie wywołany ten punkt końcowy.

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

Odmowa przyjęcia zamówienia

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

Zmień status zamówienia na "Gotowe do odbioru"

Ten punkt końcowy zostanie wywołany, jeśli punkt końcowy previous. Ustawiono status "Gotowe do odbioru osobistego" z autoMarkRea­dyForPickuptrue i na stronie rabatu zamówienie zostało automatycznie przełączone do statusu "Gotowe do odbioru osobistego"

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

Zmień status zamówienia na "Dostarczono do klienta – czekamy na potwierdzenie klienta"

Ten punkt końcowy zostanie wywołany, jeśli previous status "W drodze", "Gotowe do odbioru osobistego" lub "Gotowe do odbioru osobistego" został ustawiony z autoMarkDeli­veredtrue i na stronie rabatu zamówienie zostało automatycznie przełączone na status "Dostarczone do klienta – oczekuje na potwierdzenie klienta".

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

Partner komunikacyjny ⇒ Zľavomat

Ta część API jest zaimplementowana po stronie Dyskontomat i wywołuje system partnerski.

Główny adres URL API to

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

Biblioteka PHP

Do implementacji tej strony API można wykorzystać przygotowaną bibliotekę PHP. library. Biblioteka wymaga obecnie PHP w wersji 5.4 lub wyższej i zakłada użycie narzędzia Composer.

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

Żądania autoryzacji

Kiedy API jest włączone, partner otrzymuje partner_token oraz api_secret , które są używane do uwierzytelnienia wywołania API Zlavomat.

Parametry te są przekazywane w nagłówkach X-PartnerToken oraz X-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 samo jak na pozostałych interfejsach.

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

Jednak interfejs testowy nie pracuje z rzeczywistymi zamówieniami. Nie waliduje więc, czy zamówienie przechodzi pomiędzy poprawnymi stanami i czy zawiera elementy o podanych identyfikatorach. Po przejściu autoryzacji i walidacji formularzy żądania, interfejs testowy zawsze odpowiada z kodem powodzenia 200 lub 204.

Tworzenie anulowania

Utwórz anulowanie pozycji zamówienia w podanej ilości. Jeżeli ma zamówienie ma zostać anulowane w całości, to wszystkie pozycje są wymienione z odpowiednią ilością.

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

Uwaga dotycząca anulowania (note) jest opcjonalna.

POST /order/$slevomatId/cancel

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

Zmiana statusu zamówienia na "W trakcie realizacji".

POST /order/$slevomatId/mark-pending

{}

Zmiana statusu zamówienia na "W trakcie realizacji".

Podczas składania zamówienia parametr autoMarkDelivered jest używany do określenia, czy po upływie ustawionego okresu wysyłki ("Czas od wysyłki do dostawy") powinno automatycznie przejść do statusu "Dostarczono do klienta – czekam na potwierdzenie klienta".

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".

Gdy zamówienie przechodzi przez stronę autoMarkReady­ForPickup parametr pozwalający określić, czy czas od wysłania do doręczenia dla danego typu punktu odbioru powinno być automatycznie przełączane na status "Gotowe do odbioru". do odbioru osobistego".

Przy zamówieniu parametr autoMarkDelivered określa, czy po upływie zadanej ilości dni na odbiór dla danego typu punktu odbioru punkt odbioru ma być automatycznie przełączany ze statusu "Gotowy do odbioru osobistego na "Dostarczony do klienta – oczekuje na potwierdzenie przez klienta".

Kombinacja parametrów autoMarkReady­ForPickup false oraz autoMarkDelivered true jest niedozwolone. W tym przypadku odsyłany 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".

Podczas składania zamówienia parametr autoMarkDelivered jest używany do określenia, czy po określonej liczbie dni na odbiór dla danego typu odbioru punkt odbioru powinien zostać automatycznie przełączony na status "Dostarczono do klienta – oczekujący na potwierdzenie klienta".

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

Zmiana statusu zamówienia na "Dostarczono do klienta – oczekuje na klienta".

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

Zmiana adresu dostawy

Adres dostawy można zmienić tylko przy dostawie na adres (tzn. Nie można zmienić miejsca odbioru).

Wszystkie klucze oprócz company są wymagane.

Prawidłowe wartości dla klucza state to cz (Czechy) i (Słowacja). 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" }
Powrót do listy artykułów

Súvisiace články
Nahoru