Developer Portal

EmpikPlace Developer Portal

Zintegruj własny sklep z EmpikPlace lub zacznij tworzyć aplikacje dla tysięcy sprzedawców EmpikPlace. Zasoby API EmpikPlace odzwierciedlają faktyczne funkcjonalności serwisu produkcyjnego. Poprzez wykorzystanie API EmpikPlace możesz zbudować rozwiązania, które pozwolą na optymalizację i automatyzację procesów sprzedażowych oraz równoczesne zwiększenie wyników prowadzonego sklepu.

API sprzedawcy

EmpikPlace API to zintegrowana usługa, która umożliwia sprzedawcom wymianę danych dotyczących ich oferty magazynowej i cen, zarządzanie zamówieniami, wiadomości z klientami oraz wiele innych.

Dzięki EmpikPlace API sprzedawcy mogą zwiększyć efektywność sprzedaży, zmniejszyć zapotrzebowanie na realizacje dodatkowych procesów, poprawić czas odpowiedzi dla klientów.

Generowanie klucza API

Jeśli na Twoim koncie sklepu w EmpikPlace nie ma jeszcze wygenerowanego klucza API:

Zaloguj się do panelu EmpikPlace.
Na pasku menu w panelu EmpikPlace, w prawym górnym rogu, kliknij swoją nazwę użytkownika.
Kliknij zakładkę Klucz API.
Kliknij przycisk Wygeneruj nowy klucz.
EmpikPlace tworzy klucz API sklepu.

Uzyskanie klucza API

Jeśli na Twoim koncie sklepu w EmpikPlace jest już wygenerowany klucz API:

Na pasku menu w panelu EmpikPlace, w prawym górnym rogu, kliknij swoją nazwę użytkownika.
Kliknij zakładkę Klucz API.
Kliknij przycisk Kopiuj do schowka.
EmpikPlace skopiuje Twój klucz API do schowka.

Możesz teraz wkleić swój klucz tam, gdzie chcesz go użyć.

URL do autoryzacji API

Metoda uwierzytelniania API wykorzystująca nagłówki do wysyłania klucza API zostanie wycofana 10 października 2023 r.

Po wprowadzeniu zmian, żądania API uruchamiane przez wklejenie klucza API bezpośrednio w adresie URL przeglądarki nie będą obsługiwane. W przypadku braku wprowadzenia zmian zostanie wyświetlony następujący komunikat:


{
"code": 401,
"message": "Unauthorized, you are not allowed to perform this call"
}

Aby uniknąć tego problemu, zalecamy użycie nagłówka HTTP Authorization, aby wszystkie żądania były zgodne z powszechnie wykorzystywaną metodą:


curl -H "Authorization: 123456" https://[HOSTNAME]/api/[API-URL]

Środowisko produkcyjne: https://marketplace.empik.com/

Środowisko testowe: https://stg1.marketplace.empik.com/

Informacje o kompatybilności wstecznej

Rozwiązania interfejsu EmpikPlace są aktualizowane, aby zapewnić nowe funkcje, poprawki bezpieczeństwa i poprawki pojawiąjących się błędów.

Nowe wdrożone wersje są kompatybilne wstecz, co gwarantuje trwałość integracji po aktualizacji rozwiązania EmpikPlace, pod warunkiem że Twoja integracja będzie zgodna z tymi wytycznymi:

Twoja integracja musi umożliwiać dodawanie nowych pól w odpowiedziach API. Od czasu do czasu są dodawane nowe pola w ramach nowych funkcji.
Istnieje możliwość, że pola będą miały inną kolejność w wywołaniach API. Kolejność może się zmienić, gdy pola są dodawane do interfejsu API.
Twoja integracja musi umożliwiać dodawanie nowych wartości w polach wyliczeniowych. Mogą zostać dodane nowe wartości w polach wyliczeniowych, aby wspierać nowe funkcje. Zalecane jest używanie ciągów do deserializacji pól wyliczeniowych. Alternatywnie można skonfigurować swój deserializator, aby zaakceptować nieznane wartości wyliczeniowe.
Chociaż większość interfejsów API obsługuje format XML, zdecydowanie zalecamy używanie formatu JSON, ponieważ najnowsze interfejsy API są dostępne tylko w formacie JSON.

Jeśli zdecydujesz się na walidację wyjścia interfejsów API za pomocą plików XSD, pamiętaj, że Twój XSD powinien uwzględniać wytyczne zdefiniowane powyżej. EmpikPlace nie udostępnia plików XSD dla swoich interfejsów API i nie oferuje pomocy w pisaniu plików XSD.

Typ zawartości żądania

Jeśli API obsługuje wiele typów zawartości, dodaj nagłówek Content-Type, aby wybrać format do użycia w żądaniu API. Dokumentacja API wymienia formaty, które API może obsługiwać.

Typ zawartości odpowiedzi

Jeśli API obsługuje wiele typów zawartości, dodaj nagłówek Accept, aby wybrać format akceptowany w odpowiedzi API. Dokumentacja API zawiera listę formatów, które może stworzyć API.

HTTPS

Wszystkie żądania muszą korzystać z protokołu HTTPS.

Metody HTTP

Każdy z zasobów API korzystać może z następujących metod HTTP:

GET: Używana do pobierania danych. Metody GET mogą być wywoływane wielokrotnie, gdyż nie wprowadzają żadnych zmian w zasobach EmpikPlace.

POST: Używana do stworzenia lub edycji zasobu.

PUT: Używana do edycji zasobu.

DELETE: Używana do usuwania zasobów.

Kodowanie UTF-8

Dane tekstowe są zakodowane w UTF-8.

Formaty dat

Interfejsy API mogą używać różnych formatów daty (zgodnych z ISO8601):

date-time o wzorze YYYY-MM-DDThh:mm:ss±hh:mm.

Przesunięcie +00:00 może być zastąpione przez Z (zerowe przesunięcie UTC).

Wszystkie interfejsy API podają czas w UTC, z końcowym Z.

date-time-without-timezone ze wzorcem YYYY-MM-DDThh:mm:ss. Strefa czasowa nie jest wyświetlana.

Czas ze wzorcem hh:mm[:ss]±hh:mm. Tylko czas, ze strefą czasową

Przesunięcie +00:00 może być zastąpione przez Z (zerowe przesunięcie UTC).

Sekundy mogą być pominięte, jeśli są równe :00.

We wzorach:

YYYY: lata (czterocyfrowe)
MM: miesiące, 01-12 (dwucyfrowe)
DD: dni, 01-31 (dwucyfrowe)
T jest delimiterem pomiędzy datą a czasem
hh: godziny, 00-23 (dwucyfrowe)
mm: minuty, 00-59 (dwucyfrowe)
ss: sekundy, 00-60 (dwucyfrowe)
±hh:mm: odnosi się do przesunięcia względem UTC

W przypadku żądań GET użyj kodowania URL (na przykład, 2019-08-29T02:34:00+02:00 staje się 2019-08-29T02%3A34%3A00%2B02%3A00).

Paginacja & Sortowanie

Dla lepszej wydajności i doświadczenia użytkownika, niektóre API obsługują paginację "szukaj". Oznacza to, że użytkownik nie może przejść bezpośrednio do N-tej strony.

Użyj opcjonalnego parametru zapytania limit, aby wskazać maksymalną liczbę elementów zwracanych na stronę. Domyślną wartością jest 10. Maksymalna wartość to 100.

Jeśli istnieje więcej wyników do zwrócenia, odpowiedź zawiera pole next_page_token. Przekaż tę wartość w parametrze zapytania page_token, aby zwrócić następną stronę wyników.

API zwraca również previous_page_token, gdy wynik nie jest pierwszą stroną. Użyj go w taki sam sposób jak next_page_token.

Wartości next_page_token i previous_page_token zawierają wszystkie wymagane parametry, aby uzyskać dostęp do następnej i poprzedniej strony. Podczas korzystania z parametru page_token wszystkie inne parametry są ignorowane, niezależnie od wartości podanej do page_token.

Gdy dostępny jest parametr sort, musi on być zgodny z formatem sort=kryterium,kierunek, gdzie:

kryterium to nazwa kryterium, według którego ma być sortowane (np.: date_created, title, ...)
kierunek to kierunek sortowania. Może to być jeden z ASC, DESC

Lista wartości jako parametry URL

Pola typu array wskazują listę wartości jako parametry URL. Możesz dodać więcej elementów parameter=value do adresu URL. Odwołaj się do przykładu w prawym panelu.

Limity zapytań API

W przypadku wykonania zbyt wielu połączeń, możesz otrzymać błąd HTTP 429 "Too Many Requests". Odpowiedź będzie zawierać nagłówek Retry-After określający liczbę sekund, które należy odczekać przed wykonaniem nowego żądania.

Limit wielkości i obsługiwane formaty plików

EmpikPlace obsługuje import i wysyłanie dokumentów następujących typów:

csv,
doc,
docx,
xls,
xlsx,
ppt,
pdf,
odt,
ods,
odp,
txt,
rtf,
png,
jpg,
gif,
zpl.

Maksymalny limit wielkości przesyłanych w plików wynosi 100 MB. Podczas importu pliku maksymalna dopuszczalna liczba linii w komórce wynosi 2000. Po przekroczeniu tego limitu podczas importu pliku pojawi się błąd.

Obsługiwane formaty plików w obszarze ofertowym:

OF01 – csv, xml

OF24 – csv, xml, xlsx

Obsługiwane formaty plików w obszarze produktowym:

P41 – csv, xml, xlsx

Kody zwrotne interfejsu API

API EmpikPlace używa standardowych kodów zwrotnych HTTP.

Podczas wykonywania żądań HTTP można sprawdzić stan powodzenia lub niepowodzenia żądania za pomocą kodów stanu HTTP (np. 200).

Nie zaleca się używać komunikatów stanu HTTP ani zwrotów przyczyny (np. OK), ponieważ są one opcjonalne i nie mogą być zwracane w odpowiedziach HTTP (więcej informacji można znaleźć w RFC2616).

Dokumentacja API nie dokumentuje Reason-Phrases, ale zapewnia krótki kontekstowy opis HTTP Status Codes.

Ograniczenie liczby zapytań

Limit API to maksymalna liczba wywołań API EmpikPlace, które mogą być wykonane w ciągu godziny.

Jeśli sklep przekroczy którykolwiek z tych limitów, interfejs API zwraca komunikat o błędzie wraz z licznikiem czasu. Licznik wskazuje czas, jaki pozostał do momentu, gdy sklep będzie mógł ponownie wywołać odpowiedni interfejs API. Po upływie czasu "timeout" sklep może wznowić wykonywanie tych połączeń API.

Kody powodzenia

200 OK – Żądanie zakończyło się sukcesem.

201 Created – Żądanie powiodło się i zasób został utworzony.

202 Accepted – Wniosek przyjęty do realizacji.

204 No Content – Żądanie zakończyło się sukcesem, ale nie zwraca żadnej zawartości.

Kody błędów

400 Bad Request – Błędy w parametrach lub złe użycie metody.

Złe wykorzystanie zasobu. Na przykład: brak wymaganego parametru, niektóre parametry używają nieprawidłowego formatu, zapytanie o dane nie jest w oczekiwanym stanie.

401 Nieautoryzowany – Wywołanie API bez uwierzytelnienia.

Dodaj informacje o uwierzytelnieniu lub użyj ważnego tokena uwierzytelniającego.

403 Forbidden – Dostęp do zasobu jest zabroniony.

Bieżący użytkownik nie może uzyskać dostępu do zasobu.

404 Not Found – Zasób nie istnieje.

URI zasobu lub żądany zasób nie istnieją dla bieżącego użytkownika.

405 Method Not Allowed – Metoda HTTP (GET, POST, PUT, DELETE) nie jest dozwolona dla tego zasobu.

Lista akceptowanych metod znajduje się w dokumentacji.

406 Not Acceptable – Żądany typ zawartości odpowiedzi nie jest dostępny dla tego zasobu.

Lista poprawnych wartości nagłówka Accept dla tego żądania znajduje się w dokumentacji.

410 Gone – Zasób został trwale usunięty.

Żądany zasób nie jest już dostępny i nie będzie dostępny ponownie.

415 Unsupported Media Type – Typ zawartości wysłany do serwera nie jest obsługiwany.

Sprawdź w dokumentacji listę poprawnych wartości nagłówka Content-type, aby wysłać dane.

429 Zbyt wiele żądań – Przekroczenie limitów żądań.

Użytkownik wysłał zbyt wiele żądań w ciągu ostatniej godziny. Informacje na temat maksymalnej liczby połączeń na godzinę znajdują się w dokumentacji.

500 Wewnętrzny błąd serwera – Serwer napotkał nieoczekiwany błąd.

Workflow ofert

Tworzenie, jak i aktualizacja ofert jest możliwe dzięki zastosowaniu dwóch API: OF01 oraz OF24. Zalecamy używanie metody OF01. Weryfikacja błędów zaistniałych podczas importu ofert jest możliwa dzięki pobraniu raport błędów (OF03).

W poniższej tabeli zostało zawarte zestawienie najczęściej używanych parametrów w pliku ofertowym. Parametry oznaczone jako wymagane są niezbędne do utworzenia oferty. Do jej aktualizacji nie jest wymagany zestaw parametrów używany do jej utworzenia np. można aktualizować jedynie stan magazynowy (w tej sytuacji plik ofertowy powinien zawierać parametry: sku, product-id, product-id-type, quantity).

Poniżej została przedstawiona struktura pliku ofertowego w formacie XML, która tworzy nową ofertę. Oferta zostanie utworzona z unikalnym numerem sku 79306, identyfikatorem łączenia ofert EAN o wartości 5900017072234. Cena wynosi 42.53 zł, natomiast stan magazynowy 27 sztuk. State określa stan produktu – nowy oraz klasa logistyczna została przyporządkowana do domyślnej wartości– kod 2. Czas do wysyłki został określony jako 48h (2 dni).


<import>
   <offers>
     <offer>
        <sku>79306</sku>
        <product-id>5900017072234</product-id>
        <product-id-type>EAN</product-id-type>
        <price>42.53</price>
        <quantity>27</quantity>
        <state>11</state>
        <logistic-class>2</logistic-class>
        <leadtime-to-ship>2</leadtime-to-ship>
     </offer>
   </offers>
</import>

Podczas importu ofert mogą zdarzyć się błędy, które można pobrać za pomocą API OF03. Po pobraniu pliku należy zweryfikować kolumnę errors, w której znajdują się komunikaty błędów. W każdej kolumnie zostaną wskazane identyfikatory ofert, które umożliwią ich identyfikację i poprawę.

Kluczowe metody API z obszaru ofertowego wraz z ich charakterystyką zostały opisane poniżej.

Workflow zamówień

Interfejs API pozwala na przetwarzanie zamówienia od jego otrzymania, wysłania po końcowe odebranie przez klienta wraz z wprowadzeniem numeru listu przewozowego.

Workflow zamówienia z płatnością z góry

Proces obsługi zamówienia złożonego z płatnością z góry rozpoczyna się od statusu Przyjęcie w toku (WAITING_ACCEPTANCE). Na przyjęcie lub odrzucenie zamówienia Sprzedawca ma 5 dni. W tym czasie klient również może zrezygnować z zamówienia (anulować je ze swojego panelu).

Po akceptacji zamówienia otrzymuje ono status Obciążenie w trakcie realizacji (WAITING_DEBIT_PAYMENT), który informuje o tym, że system weryfikuje realizację płatności – w przypadku, gdy zamówienie nie zostanie opłacone w ciągu 10 dni, system automatycznie anuluje zamówienie. Ważne! Po tym czasie zarezerwowany stan magazynowy z zamówienia powraca do oferty (lub ją wznawia).

Po opłaceniu zamówienia zamówienie otrzymuje status Wysyłka w trakcie realizacji (SHIPPING) – jest to informacja dla Sprzedawcy, aby rozpocząć realizację zamówienia.

Status Wysłano (SHIPPED) oznacza, że przesyłka została wysłana (klient otrzymuje wiadomość o postępie realizacji zamówienia). Jeśli status Wysłano nie został zmieniony w czasie określonym w ofercie (leadtime-to-ship), pojawi się informacja o opóźnieniu zamówienia.

Jeśli podczas zmiany statusu na Wysłano został uzupełniony numer listu przewozowego, system automatycznie zmieni status zamówienia na Otrzymano (RECEIVED) (po odebraniu przez klienta). W przypadku braku uzupełnienia listu bądź braku obsługiwania danego dostawcy (weryfikacji po API statusu odbioru) system automatycznie zmieni status zamówienia na Otrzymano (po 10 dniach).

Lista aktualnych integracji z dostawcami (weryfikacja dostarczonych paczek poprzez API) znajduje się poniżej:

InPost,
DPD,
UPS
DHL,
Poczta Polska,
FedEx.

Workflow zamówienia z płatnością za pobraniem

Proces obsługi zamówienia złożonego z płatnością za pobraniem rozpoczyna się od statusu Przyjęcie w toku (WAITING_ACCEPTANCE). Na przyjęcie lub odrzucenie zamówienia Sprzedawca ma 5 dni. W tym czasie klient może zrezygnować z zamówienia (anulować je ze swojego panelu).

Po akceptacji zamówienia, otrzymuje ono status Wysyłka w trakcie realizacji (SHIPPING) – jest to informacja dla Sprzedawcy, aby rozpocząć realizację zamówienia.

Jeśli podczas zmiany statusu na Wysłano został uzupełniony numer listu przewozowego, system automatycznie zmieni status zamówienia na Otrzymano (RECEIVED) (po odebraniu przez klienta).

Lista aktualnych integracji z dostawcami (weryfikacja dostarczonych paczek poprzez API) znajduje się poniżej.

InPost,
DPD,
UPS,
DHL,
Poczta Polska,
FedEx.

Realizacja zwrotu i zgłoszenie incydentu przez klienta jest możliwe w obrębie statusów Wysyłka w trakcie realizacji, Wysłano, Otrzymano. Zamówienie zmieni status na Zamknięte (CLOSED) po 60 dniach od zmiany statusu na Otrzymano.

Kluczowe metody API z obszaru zamówień wraz z ich charakterystyką zostały opisane poniżej.

Przykład zamówienia pobranego poprzez API

{
    "orders": [
        {
            "acceptance_decision_date": "2022-07-22T10:50:01Z",
            "can_cancel": false,
            "can_shop_ship": false,
            "channel": null,
            "commercial_id": "40100377379445",
            "created_date": "2022-07-22T10:48:20Z",
            "currency_iso_code": "PLN",
            "customer": {
                "billing_address": {
                    "city": "Warszawa",
                    "company": "TESTOWA FIRMA",
                    "country": "Polska",
                    "country_iso_code": null,
                    "lastname": "TESTOWA FIRMA",
                    "phone": "555666777",
                    "state": null,
                    "street_1": "Marszałkowska 1 / 2",
                    "street_2": null,
                    "zip_code": "00-017"
                },
                "civility": null,
                "customer_id": "e18337080",
                "firstname": "Jan",
                "lastname": "Kowalczyk",
                "locale": null,
                "shipping_address": {
                    "additional_info": "PACZKOMANI (PRZY PLACU ZABAW)",
                    "city": "Warszawa",
                    "company": null,
                    "country": "Poland",
                    "country_iso_code": null,
                    "lastname": "POP-WAR123",
                    "phone": "666555533",
                    "state": null,
                    "street_1": "Pancera 10",
                    "street_2": null,
                    "zip_code": "03-187"
                }
            },
            "customer_debited_date": "2022-07-22T10:50:50.528Z",
            "customer_directly_pays_seller": false,
            "customer_notification_email": "rnd2tib19es.grby3j2t2@preprod.notification.mirakl.net",
            "delivery_date": null,
            "fulfillment": {
                "center": {
                    "code": "DEFAULT"
                }
            },
            "fully_refunded": false,
            "has_customer_message": false,
            "has_incident": false,
            "has_invoice": false,
            "last_updated_date": "2022-10-01T18:00:00Z",
            "leadtime_to_ship": 2,
            "order_additional_fields": [
                {
                    "code": "customer-email",
                    "type": "STRING",
                    "value": "jan.kowalczyk@ox.com"
                },
                {
                    "code": "delivery-point-name",
                    "type": "STRING",
                    "value": "POP-WAR123"
                },
                {
                    "code": "nip",
                    "type": "STRING",
                    "value": "5365975627"
                },
                {
                    "code": "order-type",
                    "type": "LIST",
                    "value": "Standard"
                }
            ],
            "order_id": "40100377379445-A",
            "order_lines": [
                {
                    "can_refund": false,
                    "cancelations": [],
                    "category_code": "21-16-8-3",
                    "category_label": "Baterie do laptopów",
                    "commission_fee": 301.95,
                    "commission_rate_vat": 23.0000,
                    "commission_taxes": [
                        {
                            "amount": 69.45,
                            "code": "TAXDEFAULT",
                            "rate": 23.0000
                        }
                    ],
                    "commission_vat": 69.45,
                    "created_date": "2022-07-22T10:48:20Z",
                    "debited_date": "2022-07-22T10:50:50Z",
                    "description": null,
                    "last_updated_date": "2022-10-01T18:00:00Z",
                    "offer_id": 23509057,
                    "offer_sku": "8715946489414",
                    "offer_state_code": "11",
                    "order_line_additional_fields": [],
                    "order_line_id": "40100377379445-A-1",
                    "order_line_index": 1,
                    "order_line_state": "CLOSED",
                    "order_line_state_reason_code": "AUTO_CLOSED",
                    "order_line_state_reason_label": "Zamknięto automatycznie",
                    "price": 1998.00,
                    "price_additional_info": null,
                    "price_unit": 999.00,
                    "product_medias": [],
                    "product_sku": "1176777671",
                    "product_title": "Projektor EPSON EB-1860, USB",
                    "promotions": [],
                    "quantity": 2,
                    "received_date": "2022-08-02T14:15:06Z",
                    "refunds": [],
                    "shipped_date": "2022-07-22T10:56:51Z",
                    "shipping_price": 15.00,
                    "shipping_price_additional_unit": null,
                    "shipping_price_unit": null,
                    "shipping_taxes": [],
                    "taxes": [],
                    "total_commission": 371.40,
                    "total_price": 2013.00
                }
            ],
            "order_state": "CLOSED",
            "order_state_reason_code": "AUTO_CLOSED",
            "order_state_reason_label": "Zamknięto automatycznie",
            "order_tax_mode": "TAX_INCLUDED",
            "paymentType": "Płatność z góry",
            "payment_type": "Płatność z góry",
            "payment_workflow": "PAY_ON_ACCEPTANCE",
            "price": 1998.00,
            "promotions": {
                "applied_promotions": [],
                "total_deduced_amount": 0
            },
            "quote_id": null,
            "shipping_carrier_code": "dhl",
            "shipping_company": "DHL",
            "shipping_deadline": "2022-07-24T22:00:19.429Z",
            "shipping_price": 15.00,
            "shipping_pudo_id": null,
            "shipping_tracking": "62121111111111111111111111",
            "shipping_tracking_url": "https://twoj.inpost.pl/pl/znajdz-przesylke?parcel=62121111111111111111111111",
            "shipping_type_code": "PACKSTATION",
            "shipping_type_label": "Paczkomaty InPost",
            "shipping_zone_code": "POLAND",
            "shipping_zone_label": "Polska",
            "total_commission": 371.40,
            "total_price": 2013.00,
            "transaction_date": "2022-07-22T10:50:50.482Z",
            "transaction_number": "M9988-18298"
        }
    ],
    "total_count": 1
}

Parametry z zamówienia pobrane przez API zostały wylistowane i opisane w poniższej tabeli.

Parametr	Opis
acceptance_decision_date	Data i godzina akceptacji zamówienia
commercial_id	Numer zamówienia komunikowany klientowi w powiadomieniach
created_date	Data i godzina utworzenia zamówienia
currency_iso_code	Waluta transakcji
billing_address: "city"	Adres rozliczeniowy: Miasto
billing_address: "company"	Adres rozliczeniowy: Nazwa firmy
billing_address: "country"	Adres rozliczeniowy: Kraj firmy
billing_address: "lastname"	Adres rozliczeniowy
billing_address: "phone"	Adres rozliczeniowy: Telefon
billing_address: "street_1"	Adres rozliczeniowy: Ulica
billing_address: "zip_code"	Adres rozliczeniowy: Kod pocztowy
customer_id	Wewnętrzny numer identyfikacyjny klienta
firstname	Imię klienta
lastname	Nazwisko klienta
shipping_address: "additional_info"	Adres wysyłki: Dodatkowe informacje (np. informacje dotyczące umiejscowienia punktu odbioru/dostarczenia)
shipping_address: "city"	Adres wysyłki: Miasto
shipping_address: "country"	Adres do wysyłki: Kraj
shipping_address: "firstname"	Adres do wysyłki: Imię odbiorcy (widoczne w przypadku wybrania opcji dostawy Kurierem)
shipping_address: "lastname"	Adres do wysyłki: Nazwisko odbiorcy(w przypadku wybrania kuriera)/*w przypadku wyboru paczkomatu lub punktu odbioru Żabka zostanie podany numer punktu - zalecamy pobieranie wskazanej informacji z parametru delivery-point-name
shipping_address: "phone"	Adres do wysyłki: Telefon
shipping_address: "street_1"	Adres do wysyłki: Ulica
shipping_address: "zip_code"	Adres do wysyłki: Kod pocztowy
customer_debited_date	Data i godzina pobrania płatności od klienta
fully_refunded	Status pełnego zwrotu zamówienia (true/false)
has_customer_message	Informacja o wiadomości w zamówieniu (true/false)
has_incident	Informacja o incydencie w zamówieniu (true/false)
has_invoice	Informacja o załączonej fakturze w zamówieniu (true/false)
last_updated_date	Data i godzina ostatniej aktualizacji zamówienia
leadtime_to_ship	Czas realizacji zamówienia
order_additional_fields: "customer-email"	Adres email klienta składającego zamówienie
order_additional_fields: "delivery-point-name"	Numer punktu doręczenia (Paczkomat/Punkt odbioru ŻABKA)
order_additional_fields: "order-type"	Typ zamówienia (Standard, Premium, PremiumFree)
order_id	Numer zamówienia EmpikPlace
can_refund	Staus możliwości realizacji zwrotu zamówienia
category_code	Kod kategorii produktu
category_label	Nazwa kategorii produktu
commission_fee	Prowizja
commission_rate_vat	Stawka VAT prowizji
commission_taxes: "amount"	Wartość podatku z kwoty prowizji
commission_vat	Wartość podatku z kwoty prowizji
offer_id	Wewnętrzny numer identyfikacyjny oferty
offer_sku	SKU Oferty
product_sku	SKU produktu (Indeks MDM)
product_title	Nazwa produktu
quantity	Ilość zamówinego produktu
received_date	Data i godzina zmiany statusu zamówienia na "Otrzymano"
shipping_price	Kwota dostawy
total_commission	Pełna kwota prowizji
total_price	Łączna kwota zamówienia
order_state	Status zamówienia
order_tax_mode	Forma podatkowa zamówienia (aktualnie EmpikPlace działa w oparciu o podatek wliczony - wysyłana kwota produktu zawiera podatek)
payment_workflow	Forma płatności za zamówienie
price	Łączna cena produktów
shipping_tracking	Numer listu przewozowego
shipping_tracking_url	Link do śledzenia paczki
shipping_type_code	Wewnętrzny kod identyfikacyjny formy dostawy
shipping_type_label	Nazwa formy dostawy
shipping_zone_code	Wewnętrzny kod identyfikacyjny kraju dostawy
shipping_zone_label	Nazwa kraju dostawy
total_commission	Pełna kwota prowizji za zamówienie
total_price	Pełna kwota za zamówienie
transaction_date	Data i godzina dokonania płatności
transaction_number	Numer transakcji płatniczej w systemie DOTPAY

Produkty

Wyszczególniamy dwie ścieżki zaimportowania produktów do panelu EmpikPlace pozwalające na utworzenie nowych kart produktów.

Ścieżka nr 1

Proces zakładania nowych kart produktów może rozpocząć się od pobrania struktury kategorii (H11), konfiguracji atrybutów (PM11) oraz listy wartości dla konkretnych atrybutów (VL11). Po ich odpowiednim przyporządkowaniu do swoich produktów należy przesłać plik zawierający niezbędne dane do założenia kart produktów (P41). W celu weryfikacji importu zalecane jest pobranie raportu błędów (P44).

Ścieżka nr 2

Istnieje możliwość zmapowania własnej struktury pliku w kreatorze konfiguracji. Proces rozpoczyna się od zaimportowania pliku do narzędzia pozwalającego na zmapowanie struktury pliku (kreator konfiguracji). Kolejnym krokiem jest przejście przez mapowanie kategorii, atrybutów oraz wartości. Finalne zaimportowanie pliku do systemu EmpikPlace jest realizowane przez przycisk „Importuj moje produkty” w ostatnim etapie procesu mapowania. Po wykonanym imporcie należy zweryfikować, czy powstały błędy. Jeśli błędy nie wystąpiły lub nie umożliwiają one dodanie wybranych przez siebie produktów można rozpocząć ustawienie cyklicznych importów przez P41. Wszystkie pliki przesłane ze strukturą zmapowaną w poprzednich krokach zostaną odczytane i produkty zaimportują się do systemu EmpikPlace.

Ważne! Jeśli struktura w pliku została zmieniona np.:

Została dodana nowa kategoria.
Został dodany nowy atrybut.
Została dodana nowa wartość słownikowa.

Należy wykonać proces mapowania jeszcze raz. Proces należy powtórzyć jedynie dla nowych struktur/atrybutów/wartości. Dotychczasowe mapowanie zostało zapisane w systemie.

Kluczowe metody API z obszaru produktów wraz z ich charakterystyką zostały opisane poniżej.

API

Metoda HTTP

Opis

H11

GET

Listowanie kategorii katalogu EmpikPlace

PM11

GET

Pobieranie wszystkich atrybutów dla żądanej kategorii

VL11

GET

Pobieranie listy wartości dla żądanego atrybutu

Przykład struktury pliku produktowego (XML)


<import>
<products>
<product>
<attribute>
<value>Filtr płaski fi 150</value>
<code>PELNY_TYTUL</code>
</attribute>
<attribute>
<value><p>Filtr płaski służy do oczyszczenia gorącego powietrza z zanieczyszczeń mechanicznych. Montowany jest niedaleko zakończeń kanałów w systemie dystrybucji gorącego powietrza.</p> <p></p> <p>Filtr wykonany jest z blachy ocynkowanej, która chroni go przed korozją. W środku znajduje się specjalny wkład, kilkuwarstwowa perforowana blaszana siatka, która dzięki swej konstrukcji, zatrzymuje znaczną ilość zanieczyszczeń. Stosowanie filtra zapobiega gromadzeniu się kurzu bezpośrednio w kratkach kominkowych. Dzięki temu nie zachodzi zjawisko przypalania się kurzu, co w znacznym stopniu wpływa korzystnie na nasze zdrowie. Dodatkowo ogranicza konieczności częstego mycia kratek. Ze względów bezpieczeństwa filtrów nie należy stosować w obudowie kominka.</p> <p></p> <p><strong>WYMIARY:</strong></p> <p>- szerokość: 5,5 cm</p> <p>- wysokość: 15 cm.</p></value>
<code>OPIS_PRODUKTU_PELNY</code>
</attribute>
<attribute>
<value>16-25-5-1</value>
<code>STR_GOLD</code>
</attribute>
<attribute>
<value>5901350017258</value>
<code>EAN</code>
</attribute>
<attribute>
<value>https://obrazek1.jpg</value>
<code>ZDJECIE_OKLADKI_PRZOD_DUZY</code>
</attribute>
<attribute>
<value>7</value>
<code>VAT_VALUE</code>
</attribute>
<attribute>
<value>FP150</value>
<code>CATALOG_CODE</code>
</attribute>
<attribute>
<value>AAAM8D</value>
<code>600</code>
</attribute>
<attribute>
<value>200</value>
<code>SZEROKOSC</code>
</attribute>
<attribute>
<value>300</value>
<code>WYSOKOSC</code>
</attribute>
<attribute>
<value>400</value>
<code>GLEBOKOSC</code>
</attribute>
<attribute>
<value>610</value>
<code>WAGA_PRODUKTU</code>
</attribute>
<attribute>
<value>AAX<value/>
<code>621</code>
</attribute>
<attribute>
<value>AAAAAT</value>
<code>602</code>
</attribute>
<attribute>
<value>https://obrazek2.jpg</value>
<code>DODATKOWE_ZDJECIA_1</code>
</attribute>
<attribute>
<value>2 lata</value>
<code>2114</code>
</attribute>
<attribute>
<value>AAAMBU</value>
<code>34</code>
</attribute>
<attribute>
<value>FP150</value>
<code>2119</code>
</attribute>
</product>
</products>
</import>

Wiadomości

EmpikPlace umożliwia wymianę wiadomości pomiędzy klientem, sprzedawcą oraz operatorem. Operatorzy mogą komunikować się ze sprzedawcami na temat oferowanych przez nich ofert, natomiast klienci mają możliwość poproszenia sprzedawcę o informacje na temat jego oferty, a także zgłosić wszelkie problemy, jakie napotkali przy składaniu zamówienia lub na późniejszym jego etapie.

Wiadomości są organizowane w wątkach dyskusyjnych. Każdy wątek dyskusyjny jest ograniczony do maksymalnej liczby 1000 wiadomości.

Zamówienie może mieć kilka wątków (dyskusji).

Wątek zawsze zawiera następujące informacje:

Temat: temat oryginalnej wiadomości
Data i godzina ostatniej wysłanej wiadomości
Osoby uczestniczące w wątku
Link: Oznacz jako nieprzeczytany, aby oznaczyć wątek jako nieprzeczytany

Poszczególne wiadomości wątku z: nazwa nadawcy, data i godzina wysłania wiadomości, ewentualne załączniki

Kluczowe metody API z obszaru wiadomości wraz z ich charakterystyką zostały opisane poniżej.

Do wiadomości można dołączyć dokumenty o maksymalnym rozmiarze 10 MB. Maksymalna liczba załączników w zamówieniu wynosi 50. Obsługiwane formaty to:

PDF,
JPEG,
GIF,
PNG,
TIFF,
ZIP,
MOV,
MP4,
pliki tekstowe,
formaty MS Office,
formaty Open Office.

Środowisko testowe

Założenie konta na platformie testowej możesz zrealizować poprzez wypełnienie formularza pod linkiem. Po prawidłowym wypełnieniu danych konto zostanie utworzone automatycznie.

Testowe platforma pozwoli Ci:

Poznanie panelu EmpikPlace
Poznanie podstawowych procesów sprzedażowych w EmpikPlace
Dodawanie testowych ofert
Dodawanie testowych produktów
Konfigurację panelu EmpikPlace

W przypadku chęci zweryfikowania procesu obsługi zamówień prosimy o skontaktowanie się z naszym suportem poprzez formularz kontaktowy. Aktualnie zamówienia testowe mogą być składane jedynie przez pracowników EmpikPlace.

Link do środowiska testowego:

stg1.marketplace.empik.com

Środowisko testowe - regulamin

Zasady korzystania z testowej wersji platformy EmpikPlace [stg1]

W ramach strony stg1.marketplace.empik.com użytkownik ma możliwość nieodpłatnego testowania testowej wersji platformy EmpikPlace w ramach jednego środowiska (dalej “Usługa”).
Usługa świadczona jest przez Empik S.A. z siedzibą w Warszawie (00-017) przy ulicy Marszałkowskiej 104/122, wpisana do rejestru przedsiębiorców Krajowego Rejestru Sądowego prowadzonego przez Sąd Rejonowy dla m.st. Warszawy w Warszawie, Wydział XII Gospodarczy Krajowego Rejestru Sądowego, pod numerem KRS 0000636785, kapitał zakładowy 275 388 578,00 złotych, opłacony w całości (dalej “Spółka”).
Rozpoczęcie korzystania przez użytkownika z Usługi jest równoznaczne z akceptacją poniższych Zasad.
Celem Usługi jest umożliwienie użytkownikowi zapoznania się ze sposobem jej świadczenia przez Spółkę.
Dane w ramach Usługi nie podlegają żadnej formie kopii zapasowych.
Spółka ma prawo usunąć wszelkie przetwarzane przez użytkownika przy wykorzystaniu Usługi dane, w szczególności jeżeli użytkownik naruszy Zasady.
Użytkownik nie może wykorzystywać Usługi do przetwarzania materiałów zawierających treści o charakterze bezprawnym, w szczególności materiałów stanowiących lub zawierających wirusy komputerowe lub jakiekolwiek inne oprogramowanie, którego działanie skutkuje naruszeniem prawa.
Użytkownik nie może podejmować jakichkolwiek działań mających wpływ na systemy zabezpieczeń systemów informatycznych Serwisu EmpikPlace lub osób trzecich, a także działać w sposób powodujący utratę stabilności pracy lub przeciążenie systemów informatycznych bezpośrednio lub pośrednio zaangażowanych przy świadczeniu Usługi.
Użytkownik ponosi pełną odpowiedzialność za działania własne oraz osób, którym udostępnił w sposób celowy lub wskutek zaniedbania dane niezbędne do korzystania z Usługi.
Spółka zastrzega, że nie gwarantuje i nie ponosi jakiejkolwiek odpowiedzialności za jakiekolwiek szkody spowodowane utrudnieniem lub brakiem możliwości korzystania z Usługi, w tym także za utratę lub zniekształcenie jakichkolwiek danych przez użytkownika przetwarzanych przy wykorzystaniu Usługi.
Z uwagi na specyfikę i charakter przedmiotowej Usługi, prosimy, aby w formularzu rejestracyjnym nie podawać prawdziwych danych osobowych.

Related Articles
Klucz API
Co to jest klucz API? Klucz API (ang. API key) to unikalny identyfikator używany do uwierzytelniania i autoryzacji dostępu do usług lub danych udostępnianych poprzez interfejs API (Interfejs Programowania Aplikacji). Interfejs API umożliwia ...
Integracje w EmpikPlace
Jak mogę zintegrować swój sklep z usługą marketplace na platformie Empik.com? EmpikPlace posiada gotowe rozwiązania dla najbardziej popularnych platform e-commerce w Polsce. Przejdź do naszej strefy integracji i sprawdź dostępne możliwości. Dodatkowo ...
SkyShop
Instrukcja aplikacji ShyShop Zautomatyzuj już teraz dodawanie produktów, synchronizację cen i stanów magazynowych oraz obsługę zamówień w EmpikPlace. Aplikacja pozwala na eksport produktów do EmpikPlace, synchronizację ich stanów magazynowych i cen, ...
Jak zmienić klasę logistyczną?
Klasę logistyczną możemy zmienić na 3 sposoby: Pojedynczo Grupowo Za pomocą pliku .xml lub API POJEDYNCZA ZMIANA KLASY LOGISTYCZNEJ Zaloguj się do Panelu Sprzedawcy EmpikPlace. Po lewej stronie wybierz zakładkę "Cena i zapas"-> „Oferty", aby przejść ...
Jak zmienić czas wysyłki?
Czas realizacji do wysyłki jest jednym z kluczowych elementów podczas wyboru oferty przez klienta. Im szybszy czas realizacji do wysyłki, tym Twoja oferta jest bardziej atrakcyjna wśród konkurencji. Czas wysyłki możemy zmienić na 3 sposoby: ...

Developer Portal

Developer Portal

API sprzedawcy

Generowanie klucza API

Uzyskanie klucza API

URL do autoryzacji API

Informacje o kompatybilności wstecznej

Typ zawartości żądania

Typ zawartości odpowiedzi

HTTPS

Metody HTTP

Kodowanie UTF-8

Formaty dat

Paginacja & Sortowanie

Lista wartości jako parametry URL

Limity zapytań API

Limit wielkości i obsługiwane formaty plików

Kody zwrotne interfejsu API

Ograniczenie liczby zapytań

Kody powodzenia

Kody błędów

Workflow ofert

Workflow zamówień

Workflow zamówienia z płatnością z góry

Workflow zamówienia z płatnością za pobraniem

Produkty

Wiadomości

Środowisko testowe

Środowisko testowe - regulamin

Related Articles

Klucz API

Integracje w EmpikPlace

SkyShop

Jak zmienić klasę logistyczną?

Jak zmienić czas wysyłki?