One Fulfillment by Allegro
One Fulfillment by Allegro to usługa kompleksowej obsługi logistycznej dla e-commerce. W ramach niej sprzedawcy wyślą do centrum logistycznego Allegro swoje towary, a my zajmiemy się ich przechowywaniem oraz obsługą zamówień i zapytań posprzedażowych ich klientów.
Więcej informacji o One Fulfillment by Allegro oraz o tym, jak z skorzystać z tej usługi, znajdziesz na naszej stronie.
Aby wystawiać oferty w ramach One Fulfillment oraz korzystać z dedykowanych zasobów, muszą zostać spełnione odpowiednie warunki:
- konto sprzedawcy musi być powiązane z usługą One Fulfillment. Skorzystaj z GET /me i upewnij się, że w sekcji ”features” zwracamy wartość “ONE_FULFILLMENT”. Więcej informacji, jak założyć konto One Fulfillment, znajdziesz w tym artykule;
- token sprzedawcy musi mieć uwzględnione scope’y allegro:api:fulfillment:read i allegro:api:fulfillment:write. Więcej o zarządzadniu scope’ami w API Allegro znajdziesz w naszym poradniku.
Jak wystawić ofertę
Aby wystawić ofertę w usłudze One Fulfillment, musisz połączyć ją z produktem. Zrobisz to za pomocą POST /sale/product-offers - w żądaniu przekaż dane produktu, cenę i liczbę sztuk, aby utworzyć ofertę powiązaną z produktem:
- który istnieje w naszej bazie - jeśli na podstawie przekazanych danych rozpoznamy, że produkt istnieje w naszej bazie, to weźmiemy jego dane i uwzględnimy je w wystawionej ofercie;
którego nie ma w naszej bazie - w żądaniu musisz przekazać komplet danych, które opisują sprzedawany produkt. Na tej podstawie stworzymy propozycję nowego produktu i powiążemy z nim ofertę sprzedawcy.
Pozostałe informacje potrzebne do wystawienia oferty uzupełnimy wartościami domyślnymi. Więcej informacji na ten temat znajdziesz w naszym poradniku - Jak jednym requestem wystawić ofertę powiązaną z produktem.
Aby utworzyć ofertę typu fulfillment należy:
- typ oferty określić jako Kup Teraz;
- parametr “stan” określić jako “nowy”;
- ustawić parametr EAN/ISBN/ISSN (jeśli korzystasz z POST /sale/product-offers i chcesz połączyć ofertę z istniejącym produktem, to ta wartość musi pochodzić z danych produktu z naszej bazy. Nie możesz wpisać własnego numeru EAN, innego niż ten, który jest przypisany do produktu. Jeżeli produkt nie ma żadnego EAN, to nie utworzysz dla niego oferty);
- wybrać opcję "do wyczerpania przedmiotów";
- czas wysyłki ustawić na 24 godziny;
- pole "dodatkowe informacje o dostawie" pozostawić puste;
- w polu “location” przekazać dokładnie poniższe wartości:
{ "countryCode": "PL", "province": "MAZOWIECKIE", "city": "Adamów 50", "postCode": "05-825" } - liczbę dostępnych sztuk ustawić na równą zero i określić w sztukach;
- wybrać kategorię dopuszczoną do wystawiania w One Fulfillment. Jeśli w danej kategorii nie umożliwiamy obsługi One Fulfillment, to w odpowiedzi na próbę wystawienia oferty zwrócimy błąd;
- do oferty musisz przypisać cennik dostawy - wybierz jeden z dwóch dostępnych:
- “One Fulfillment PL” - oferty udostępnimy tylko na allegro.pl;
- “One Fulfillment International“ - udostępnimy oferty na allegro.pl i zgłosimy do udostępnienia na rynkach zagranicznych. Jeśli oferty przejdą pozytywnie weryfikację, udostępnimy je na tych rynkach.
- wybrać opcję faktura VAT oraz określić wysokość stawki VAT.
Dodatkowo:
- dla jednego produktu możesz utworzyć tylko jedną ofertę;
- nie możesz wybrać:
- opcji wznawiania oferty;
- opcji przedsprzedaży;
- żadnych usług dodatkowych (np. zapakowania na prezent).
Poniżej znajdziesz przykładowe struktury żądania dla poszczególnych zasobów.
POST /sale/product-offers - tworzenie oferty powiązanej z produktem, który istnieje w naszej bazie:
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d ‘{
"payments": {
"invoice": "VAT"
},
"sellingMode": {
"format": "BUY_NOW",
"price": {
"amount": "85",
"currency": "PLN"
},
"minimalPrice": null,
"startingPrice": null,
"netPrice": null
},
"location": {
"city": "Adamów 50",
"countryCode": "PL",
"postCode": "05-825",
"province": "MAZOWIECKIE"
},
"images": [
"https://a.allegroimg.pl/original/118b8e/25f2bbcd40ba9447b29160c00312"
],
"description": {
"sections": [{
"items": [{
"type": "TEXT",
"content": "<p>Oferta testowa</p>"
}]
}]
},
"name": "Test Offer",
"external": null,
"productSet": [{
"product": {
"id": "55a77307-d13c-4c6b-ae67-29726de17ed9"
}
}],
"stock": {
"available": "0",
"unit": "UNIT"
},
"delivery": {
"shippingRates": {
"id": “{ID cennika dostawy o nazwie “One Fulfillment” predefiniowanego przez Allegro One Fulfillment na koncie sprzedawcy}"
},
"handlingTime": "PT24H"
},
"sizeTable": null,
"parameters": []
}’-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d ‘{
"payments": {
"invoice": "VAT"
},
"sellingMode": {
"format": "BUY_NOW",
"price": {
"amount": "85",
"currency": "PLN"
},
"minimalPrice": null,
"startingPrice": null,
"netPrice": null
},
"location": {
"city": "Adamów 50",
"countryCode": "PL",
"postCode": "05-825",
"province": "MAZOWIECKIE"
},
"images": [
"https://a.allegroimg.pl/original/118b8e/25f2bbcd40ba9447b29160c00312"
],
"description": {
"sections": [{
"items": [{
"type": "TEXT",
"content": "<p>Oferta testowa</p>"
}]
}]
},
"name": "Test Create Offer",
"external": null,
"productSet": [{
"product": {
"name": "Przykładowy produkt fulfilment E2E",
"category": {
"id": "79155"
},
"images": [
"https://a.allegroimg/original/118b8e/25f2bbcd40ba9447b29160c00312"
],
"parameters": [{
"id": "223545",
"values": [
"Świat Lodu i Ognia"
]
},
{
"id": "223489",
"values": [
"Elio M. García. Jr.",
"George R. R. Martin",
"Linda Antonsson"
]
},
{
"id": "75",
"valuesIds": [
"75_2"
]
},
{
"id": "74",
"values": [
"2014"
]
},
{
"id": "24648",
"valuesIds": [
"24648_1",
"24648_2"
]
},
{
"id": "223333",
"values": [
"20.5"
]
},
{
"id": "245669",
"values": [
"7860275839780"
]
},
{
"id": "223541",
"valuesIds": [
"223541_303061"
]
}
]
}
}],
"stock": {
"available": "0",
"unit": "UNIT"
},
"delivery": {
"shippingRates": {
"id": “{ID cennika dostawy o nazwie “One Fulfillment” predefiniowanego przez Allegro One Fulfillment na koncie sprzedawcy}"
},
"handlingTime": "PT24H"
},
"sizeTable": null,
"parameters": []
}’Jak zarządzać ofertą w One Fulfillment
Po tym, gdy wystawisz ofertę dla produktu, zakończymy ją automatycznie ze stanem “stock.available: 0”. Podobnie sytuacja będzie wyglądać w przypadku oferty, dla której skończyły się produkty na magazynie - również automatycznie ją zakończymy z powodu braku stanu magazynowego. W API taka oferta będzie widoczna jako publication.status: “ENDED” oraz publication.endedBy: EMPTY_STOCK, natomiast po zalogowaniu do platformy, na ekranie Mój Asortyment oferty będą widniały ze statusem oczekująca.
Po tym, gdy awizujesz produkt, z którym była powiązana dana oferta i awizo zostanie przyjęte na magazynie, stan oferty zwiększy się o liczbę przyjętego towaru i automatycznie ją aktywujemy. Jeśli spróbujesz zmienić liczbę sztuk w ofercie na własną wartość, to otrzymasz komunikat błędu, że dla tego typu ofert nie możliwa jest zmiana liczby sztuk.
Pamiętaj, że możesz modyfikować dane oferty (oprócz liczby sztuk), ale nie możesz zmieniać danych produktu.
Jak zarządzać awizo
Awizo to zbiór informacji o produktach zapakowanych w kartony, palety lub kontener, które następnie wyślesz do naszego magazynu.
Możliwe statusy dla awizo to:
- DRAFT - szkic, na tym etapie możesz jeszcze edytować dane w awizo;
- IN_TRANSIT - w drodze do magazynu;
- UNPACKING - na magazynie, w trakcie rozpakowywania;
- COMPLETED - rozpakowane na magazynie.
Sprawdź dostępne produkty do awizacji
Awizować możesz tylko te produkty, z którymi powiązane są twoje wcześniej utworzone oferty. Pełną listę dostępnych produktów pobierzesz za pomocą GET /fulfillment/available-products. Jeśli chcesz wyszukać informacje o produkcie według jego ID, skorzystaj z GET /sale/products/{productId}. Gdy utworzysz nową ofertę i powiążesz ją z nowym produktem, zaktualizujemy listę i zwrócimy w niej ten produkt. Gdy oferta zostanie usunięta lub zarchiwizowana, przestaniemy zwracać produkt powiązany z daną ofertą.
W odpowiedzi dla GET /fulfillment/available-products zwrócimy listę 50 produktów uporządkowanych alfabetycznie na podstawie nazwy produktu. Listę możesz dostosować do swoich potrzeb za pomocą parametrów:
- limit - określ liczbę produktów, jaką chcesz otrzymać w odpowiedzi. Maksymalna wartość to 100;
- offset - wskaż miejsce, od którego chcesz pobrać następną porcję danych.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/fulfillment/available-products’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' Przykładowy response:
200 OK
{
"products": [
{
"id": "4b215fa1-0cba-4a2a-9fb3-db740de4bbe3", - ID produktu
“name”: “nazwa”, - nazwa produktu
"gtins": [ - numery GTIN przypisane
do produktu
"2746650558857",
"1859832948337"
],
“image”: “http://image-url” - adres zdjęcia produktu
} …
],
“count”: 3, - liczba zwróconych wyników
“totalCount”: 3 - łączna liczba dostępnych
wyników
}Utwórz draft awizo
Za pomocą POST /fulfillment/advance-ship-notices utworzysz szkic awizo. W odpowiedzi otrzymasz m.in. ID awizo, co pozwoli ci w kolejnych krokach edytować informacje na jego temat za pomocą metody PUT, np.:
- dodawać nowe produkty,
- aktualizować liczbę sztuk danego produktu,
- uzupełnić informacje o sposobie pakowania,
- uzupełnić informacje o sposobie dostawy.
Adres nowo utworzonego awizo otrzymasz także w nagłówku Location.
Zwróć uwagę także na nagłówek etag w odpowiedzi, który oznacza wersję danego awizo. Tą wartość przekażesz podczas edycji awizo w nagłówku if-match.
Przykładowy request:
curl -X POST \
'https://api.allegro.pl/fulfillment/advance-ship-notices’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d ‘{
"items": [{
"product": {
"id": "4b215fa1-0cba-4a2a-9fb3-db740de4bbe1" - ID nadawanego produktu
},
"quantity": 100 - liczba sztuk produktu
},
{
"product": {
"id": "ae2ab1f4-ad6b-4203-939e-37feb63e2a8c"
},
"quantity": 1000
}]
}’Przykładowy response:
201 Created
Location: https://api.allegro.pl/fulfillment/advance-ship-notices/fa6743f7-5674-4919-a51e-ef7ae0b441f5
etag: 123456
{
"id": "fa6743f7-5674-4919-a51e-ef7ae0b441f5", - ID awizo w
formacie UUID
"displayNumber": "A-210310-0000002", - numer awizo,
który będzie
widoczny na
oznaczeniach dla
magazynu
"status": "DRAFT", - aktualny status
awizo
"createdAt": "2021-03-03T09:15:21.198480Z", - data utworzenia
awizo
"updatedAt": "2021-03-03T09:15:21.198480Z", - data modyfikacji
awizo
"items": [ - zawartość awizo
{
"product": {
"id": "4b215fa1-0cba-4a2a-9fb3-db740de4bbe1", - ID produktu
},
"quantity": 1 - liczba sztuk
produktu
},
{
"id": "26cae403-60d0-4df1-953c-6f44d1e0aedc",
"product": {
"id": "ae2ab1f4-ad6b-4203-939e-37feb63e2a8c"
},
"quantity": 1
}
],
"handlingUnit": null, - informacje o nośnikach, w których zostaną wysłane
produkty. Opis, jak wypełnić tę sekcję, znajdziesz w
punkcie “Uzupełnij dane o awizo”
"labels": null, - informacje o oznaczeniach dla magazynu, sekcję
uzupełnimy automatycznie po wygenerowaniu oznaczeń w
jednym z kolejnych kroków
"shipping": null - informacje o dostawie. Opis, jak wypełnić tę sekcję,
znajdziesz w punkcie “Uzupełnij dane o awizo”
}Jak przeglądać utworzone awizo
Za pomocą GET /fulfillment/advance-ship-notices możesz przeglądać wcześniej utworzone awizo. W odpowiedzi otrzymasz domyślnie listę 50-ciu awizo, uporządkowanych od najstarszych do najnowszych. Listę możesz dostosować do swoich potrzeb za pomocą parametrów:
- limit - określ liczbę awizo, jaką chcesz otrzymać w odpowiedzi. Maksymalna wartość to 200;
- offset - wskaż miejsce, od którego chcesz pobrać następną porcję danych;
- status - wybierz status awizo, dla którego chcesz otrzymać wyniki. Możesz przekazać więcej niż jedną wartość, np. GET /fulfillment/advance-ship-notices?status=DRAFT&status=IN_TRANSIT.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/fulfillment/advance-ship-notices’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' Przykładowy response:
200 OK
{
"advanceShipNotices": [
{
"id": "14dc70aa-3aa6-4914-af41-aa3bc306f074",
"displayNumber": "A-210310-0000002"
"status": "DRAFT",
"createdAt": "2021-03-02T13:39:12.739Z",
"updatedAt": "2021-03-02T13:39:12.739Z",
"items": [
{
"product": {
"id": "4b215fa1-0cba-4a2a-9fb3-db740de4bbe1"
},
"quantity": 1000
}
],
"handlingUnit": {
"unitType": "PALLET",
"amount": 5,
"labelsType": "ONE_FULFILMENT"
},
"labels": : {
"fileUrl": "https://allegro.pl/fulfillment/advance-ship-notices/14dc70aa-3aa6-4914-af41-aa3bc306f074/labels"
},
"shipping": : {
"method": "THIRD_PARTY_DELIVERY",
"estimatedTimeOfArrival": "2023-02-10T10:55:50.550672Z",
"thirdParty": : {
"name": "TOYS",
"orderNumber": "123456678"
},
"countryCode": "PL"
},
"submittedAt": null
},
…
]
"count": 24,
"totalCount": 24
},Jeśli chcesz pobrać informacje na temat wskazanego awizo, skorzystaj z GET /fulfillment/advance-ship-notices/{id}, gdzie jako id przekaż identyfikator danego awizo.
Jak usunąć awizo
Za pomocą DELETE /fulfillment/advance-ship-notices/{id} usuniesz awizo, które wskazałeś w żądaniu. Pamiętaj, że możesz usunąć awizo tylko w statusie “DRAFT.”
Przykładowy request:
curl -X DELETE \
'https://api.allegro.pl/fulfillment/advance-ship-notices/aade3739-2fee-48e2-b284-6425ee1d6690’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' Przykładowy response:
204 No ContentUzupełnij dane o awizo
Za pomocą PUT /fulfillment/advance-ship-notices/{id} uzupełnij pozostałe dane potrzebne do wysyłki awizo. Jako id przekaż identyfikator, który otrzymałeś w odpowiedzi dla POST /fulfillment/advance-ship-notices. Możesz też go pobrać za pomocą GET /fulfillment/advance-ship-notices.
Informacje o sposobie dostawy w polu "shipping" możesz uzupełnić już teraz lub dopiero, gdy wydrukujesz i nakleisz oznaczenia dla magazynu na paczki/palety (ten proces opisaliśmy w następnym punkcie). Podobnie jest z polem “handlingUnit” - możesz je uzupełnić już teraz lub po naklejeniu oznaczeń.
Zwróć uwagę na nagłówek if-match w przykładowym żądaniu. Nagłówek jest wymagany, dotyczy wersji awizo i służy do zakładania tzw. optimistic-lock. Jeżeli sprzedawca ma dwóch pracowników, którzy zaczną aktualizować awizo w tym samym momencie (z numerem wersji etag = np. 25) to tylko jednemu pracownikowi operacja się powiedzie. Drugi dostanie błąd, który będzie informować o tym, że musi najpierw zaktualizować dane (czyli musi pobrać wartość z nagłówka etag przez GET /fulfillment/advance-ship-notices/{id} i przekazać go następnie w if-match) i ponownie wprowadzić swoje zmiany.
Przykładowy request:
curl -X PUT \
'https://api.allegro.pl/fulfillment/advance-ship-notices/33dd66df-20e2-4b92-9c76-700f4c8fc185’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H if-match: 123456' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d ‘{
"items": [
{
"product": {
"id": "4b215fa1-0cba-4a2a-9fb3-db740de4bbe1"
},
"quantity": 1000
}
],
"handlingUnit": {
"unitType": "BOX", - nośnik, w którym/których zostanie
wysłany towar. Dopuszczalne wartości to
BOX, PALLET, CONTAINER
"amount": 5, - w przypadku, gdy unitType to ‘BOX’ lub
‘PALLET’, amount oznacza ilość
odpowiednio kartonów lub palet.
W przypadku unitType równego
‘CONTAINER’, amount oznacza ilość
nośników w kontenerze.
"labelsType": "ONE_FULFILMENT" - sposób oznaczenia nośników.
Dopuszczalne wartości to
‘ONE_FULFILMENT’ oraz ‘NONE.
ONE_FULFILMENT oznacza, że merchant sam
generuje oznaczenia. NONE oznacza, że
oznaczenia zostaną wygenerowane przez
Magazyn Allegro. Jeśli unitType to
‘CONTAINER’, to labelsType powinno mieć
wartość ‘NONE’.
},
"shipping": : {
"method": "THIRD_PARTY_DELIVERY", - metoda dostawy, dostępne wartości
to “OWN_TRANSPORT” (wysyłka własnym
transportem)
lub “COURIER_BY_SELLER” (wysyłka towaru
kurierem)
lub “THIRD_PARTY_DELIVERY” (wysyłka od
producenta)
"estimatedTimeOfArrival": "2023-02-10T10:55:50.550672Z", - przewidywalny termin dostawy
"thirdParty": : { - dane producenta
"name": "TOYS", - nazwa producenta
"orderNumber": "O-123456678" - nr zamówienia producenta
},
"countryCode": "PL" - kod kraju z którego odbędzie się
dostawa
}
}’
Przykładowy response:
200 OK
etag: 123457
{
"id": "14dc70aa-3aa6-4914-af41-aa3bc306f074",
"displayNumber": "A-210310-0000002"
"status": "DRAFT",
"createdAt": "2021-03-02T13:39:12.739Z",
"updatedAt": "2021-03-02T13:39:12.739Z",
"items": [
{
"product": {
"id": "4b215fa1-0cba-4a2a-9fb3-db740de4bbe1"
},
"quantity": 1000
}
],
"handlingUnit": {
"unitType": "BOX",
"amount": 5,
"labelsType": "ONE_FULFILMENT"
},
"labels": : {
"fileUrl": "https://allegro.pl/fulfillment/advance-ship-notices/14dc70aa-3aa6-4914-af41-aa3bc306f074/labels"
},
"shipping": : {
"method": "THIRD_PARTY_DELIVERY",
"estimatedTimeOfArrival": "2023-02-10T10:55:50.550672Z",
"thirdParty": : {
"name": "TOYS",
"orderNumber": "O-123456678"
},
"countryCode": "PL"
},
"submittedAt": null
}’Pobierz oznaczenia na awizo
Aby pobrać oznaczenia na kartony, pobierz dostępne awizo za pomocą GET /fulfillment/advance-ship-notices i GET /fulfillment/advance-ship-notices/{id}. Link do etykiet znajdziesz w polu labels.fileUrl.
Zakończ edycję i wyślij awizo
Za pomocą PUT /fulfillment/submit-commands/{commandId} zakończ edycję awizo. Po prawidłowym żądaniu awizo otrzyma status “IN_TRANSIT”, a magazyn zostanie powiadomiony o planowanej dostawie. Od tego momentu możliwość edycji awizo zostaje ograniczona do wybranych pól (więcej informacji znajdziesz tutaj). Jako commandId przekaż wygenerowany we własnym zakresie numer UUID.
Przykładowy request:
curl -X PUT \
'https://api.allegro.pl/fulfillment/advance-ship-notices/74c605e4-482e-42e2-b5f5-2b1340944fa2’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d ‘{
"input": {
"advanceShipNoticeId":"89bdbddf-8b00-47c5-b4c1-798201222e51" - ID awizo
}
}’Przykładowy response:
201 Created
Location: https://api.allegro.pl/fulfillment/submit-commands/71a78649-5b17-4d0d-86f3-284a0d062faf
{
"id": "71a78649-5b17-4d0d-86f3-284a0d062faf", - ID komendy
"input": {
"advanceShipNoticeId": "89bdbddf-8b00-47c5-b4c1-798201222e51" - ID awizo
},
"output": {
"status": "RUNNING", - status wykonania komendy
"errors": []
}
}Zasób działa asynchronicznie, dlatego odpowiedź 201 nie jest tożsama prawidłowym zakończeniem edycji awizo. Aby otrzymać końcowy status komendy musisz użyć metody GET na adresie, który otrzymałeś w nagłówku location. W niektórych przypadkach nie będzie to koniecznie - status “SUCCESSFUL” otrzymasz już po wykonaniu żądania za pomocą metody PUT.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/fulfillment/advance-ship-notices/0c49029d-9352-401e-9188-eefb15df1976’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' Przykładowy response:
{
"id": "71a78649-5b17-4d0d-86f3-284a0d062faf",
"input": {
"advanceShipNoticeId": "89bdbddf-8b00-47c5-b4c1-798201222e51"
},
"output": {
"status": "SUCCESSFUL",
"errors": []
}
}W kolejnych etapach awizo zmieni status na “UNPACKING”, co oznacza, że awizo dojechało na magazyn i poprawnie rozpoznaliśmy pierwsze z oklejonych kartonów. Statusem końcowym jest “COMPLETED” - magazyn rozpakował awizo oraz zidentyfikował, czy produkty są w dobrym stanie. Po tym, jak produkty zostaną odłożone na półki, pojawią się w aktualnych stanach magazynowych.
Edytuj zakończone awizo
Do momentu rozpoczęcia rozpakowywania przez magazyn towarów zadeklarowanych w awizo, możliwa jest, ograniczona w zakresie, edycja danych zakończonego awizo o statusie “IN_TRANSIT”,
Za pomocą PUT /fulfillment/advance-ship-notice/{id}/submitted zmodyfikujesz dane zakończonego awizo. Jako “id” przekaż identyfikator, który otrzymałeś w odpowiedzi dla POST /fulfillment/advance-ship-notices lub GET /fulfillment/advance-ship-notices.
Modyfikacje zakończonego awizo ograniczone są do:
- zmiany liczby sztuk produktu,
- usunięcia produktu,
- zmiany liczby nośników, w których zostaną wysłane produkty,
- zmiany szczegółów dostawy:
- numeru rejestracyjnego pojazdu (gdy w zakończonym awizo, w polu “shipping.method” zadeklarowano metodę dostawy OWN_TRANSPORT),
- numeru listu przewozowego (gdy w zakończonym awizo, w polu “shipping.method” zadeklarowano metodę dostawy COURIER_BY_SELLER),
- nazwy oraz numeru zamówienia (gdy w zakończonym awizo, w polu “shipping.method” zadeklarowano metodę dostawy THIRD_PARTY_DELIVERY).
curl -X PUT \
'https://api.allegro.pl/fulfillment/advance-ship-notices/33dd66df-20e2-4b92-9c76-700f4c8fc185/submitted’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H if-match: 123456' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d ‘{
"items": [
{
"product": {
"id": "4b215fa1-0cba-4a2a-9fb3-db740de4bbe1"
},
"quantity": 1000
}
],
"handlingUnit": {
"amount": 8 - w przypadku, gdy unitType to ‘BOX’ lub
‘PALLET’, amount oznacza ilość
odpowiednio kartonów lub palet.
W przypadku unitType równego
‘CONTAINER’, amount oznacza ilość
nośników w kontenerze.
},
"shipping": : {
"thirdParty": : { - dane producenta
"name": "TOYS", - nazwa producenta
"orderNumber": "O-1234566789" - nr zamówienia producenta
}
}
}’200 OK
etag: 123457
{
"id": "33dd66df-20e2-4b92-9c76-700f4c8fc185",
"displayNumber": "A-210302-0000002"
"status": "IN_TRANSIT",
"createdAt": "2021-03-02T13:39:12.739Z",
"updatedAt": "2021-03-02T13:40:12.739Z",
"items": [
{
"product": {
"id": "4b215fa1-0cba-4a2a-9fb3-db740de4bbe1"
},
"quantity": 1000
}
],
"handlingUnit": {
"unitType": "BOX",
"amount": 8,
"labelsType": "ONE_FULFILMENT"
},
"labels": null,
"shipping": : {
"method": "THIRD_PARTY_DELIVERY",
"estimatedTimeOfArrival": "2023-02-10T10:55:50.550672Z",
"thirdParty": : {
"name": "TOYS",
"orderNumber": "O-1234566789"
},
"countryCode": "PL"
},
"submittedAt": "2021-03-02T13:45:12.739Z"
}’Zwróć uwagę na nagłówek if-match w przykładowym żądaniu. Nagłówek jest wymagany, dotyczy wersji awizo i służy do zakładania tzw. optimistic-lock. Jeżeli sprzedawca ma dwóch pracowników, którzy zaczną aktualizować awizo w tym samym momencie (z numerem wersji etag = np. 25) to tylko jednemu pracownikowi operacja się powiedzie. Drugi dostanie błąd, który będzie informować o tym, że musi najpierw zaktualizować dane (czyli musi pobrać wartość z nagłówka etag przez GET /fulfillment/advance-ship-notices/{id} i przekazać go następnie w if-match) i ponownie wprowadzić swoje zmiany.
Anuluj awizo
Za pomocą PUT /fulfillment/advance-ship-notices/{id}/cancel anulujesz awizo o statusie “IN_TRANSIT” - czyli do momentu rozpoczęcia rozpakowywania przez magazyn zadeklarowanych towarów.
Jako “id” przekaż identyfikator, który otrzymałeś w odpowiedzi dla POST /fulfillment/advance-ship-notices lub GET /fulfillment/advance-ship-notices.
Przykładowy request:
curl -X PUT \
'https://api.allegro.pl/fulfillment/advance-ship-notices/33dd66df-20e2-4b92-9c76-700f4c8fc185/cancel \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \Sprawdź postęp odbioru awizo przez magazyn
Za pomocą GET /fulfillment/advance-ship-notices/{id}/receiving-state sprawdzisz postęp odbioru awizo przez magazyn. Odpowiedź uwzględnia aktualny etap odbioru oraz informację o produktach - przyjętej liczbie oraz stanie. Jeśli awizo jest w statusie UNPACKING, raport generowany jest dynamicznie, co może wpływać na różne odpowiedzi, nawet w krótkich odstępach czasowych.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/fulfillment/advance-ship-notices/0c49029d-9352-401e-9188-eefb15df1976/receiving-state’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \ Przykładowy respone:
{
"updatedAt": "2020-08-26T12:50:04Z", - czas ostatniej aktualizacji raportu odbioru awizo
"stage": "COMPLETED", - aktualny etap odbioru, dostępne wartości to:
“IN_PROGRESS” i “COMPLETED”
"displayNumber": "A-210310-0000002", - numer awizo widoczny na oznaczeniach
"content": [ - informacje o zawartości awizo
{
"expected": 10, - spodziewana liczba sztuk danego produktu
"product": {
"id": "a1520fab-7801-4832-9ccd-fb068c707a74" - ID produktu
},
"received": [
{
"quantity": 10, - przyjęta liczba sztuk produktu
"receivedType": "SELLABLE" - stan przyjętego produktu. Dostępne wartości to:
“SELLABLE” (nadaje się do sprzedaży), “DAMAGE”
(uszkodzony) lub “REJECT” (odrzucony, zawsze
wraca do sprzedawcy).
"reasonCode": "SELLABLE", - kod stanu produktu po rozpakowaniu. Jeśli produkt
nadaje się do sprzedaży i w polu “receivedType”
zwróciliśmy “SELLABLE”, to taką samą wartość
zwrócimy również w tym polu. Dla produktu, który
nie nadaje się do sprzedaży, zwrócimy kod, który
określa szczegółową przyczynę odrzucenia
Pełną listę wartości znajdziesz w naszej
dokumentacji.
}
]
}
]
}Jak pobrać aktualne stany magazynowe
Za pomocą GET /fulfillment/stock pobierzesz aktualne stany magazynowe twoich produktów. Lista uwzględnia tylko te sztuki produktów, dla których zakończono proces przyjęcia na magazyn. W odpowiedzi domyślnie otrzymasz do 50 produktów, domyślnie posortowanych według nazw produktów. Listę możesz dostosować do swoich potrzeb za pomocą parametrów:
- limit - określ liczbę produktów, jaką chcesz otrzymać w odpowiedzi. Maksymalna wartość to 1000;
- offset - wskaż miejsce, od którego chcesz pobrać następną porcję danych;
- outOfStockInFrom - określ minimalną przewidywaną liczbę dni, po których zapasy produktu zostaną wyprzedane;
- outOfStockInTo - określ maksymalną przewidywaną liczbę dni, po których zapasy produktu zostaną wyprzedane;
- phrase - podaj nazwę wyszukiwanego produktu,
- productId - podaj identyfikator wyszukiwanego produktu;
- productAvailability - wskaż dostępność produktów. Możesz przekazać jedną lub więcej wartości: “SUFFICIENT” (wystarczająca liczba zapasów), “LOW” (niska liczba zapasów), “UNAVAILABLE” (produkt niedostępny);
- productStatus - określ statusu produktu. Aktualnie wspieramy tylko wartość “UNFULFILLABLE” (produkt niezdatny do sprzedaży);
- sort - wybierz rodzaj sortowania:
- available - rosnąco według liczby sztuk na ofercie;
- -available - malejąco według liczby sztuk na ofercie;
- unfulfillable - rosnąco według liczby sztuk niezdatnych;
- -unfulfillable - malejąco według liczby sztuk niezdatnych;
- name - według nazwy produktu, od A - Z;
- -name - według nazwy produktu, od Z - A;
- lastWeekSalesAverage - rosnąco według sprzedaży produktów w ciągu ostatniego tygodnia;
- -lastWeekSalesAverage - malejąco według sprzedaży produktów w ciągu ostatniego tygodnia;
- lastThirtyDaysSalesSum - rosnąco według sprzedaży produktów w ciągu ostatnich 30 dni;
- -lastThirtyDaysSalesSum - malejąco według sprzedaży produktów w ciągu ostatnich 30 dni;
- reserve - rosnąco według przewidywanej liczby dni, po których zapasy produktów zostaną wyprzedane. Jako pierwsze zwrócimy produkty sprzedawcy, których aktualnie nie ma na magazynie oraz te, dla których widnieje wartość “NOT_ENOUGH_DATA“ w reserve.status - bez rozróżnienia na przyczynę aktualnej predykcji;
- -reserve - malejąco według przewidywanej liczby dni, po których zapasy produktów zostaną wyprzedane;
- storageFee - sortowanie według opłaty za przechowywanie (rosnąco); jako pierwsze zwrócimy wszystkie opłaty ze statusem: NOT_APPLICABLE (nie pobraliśmy opłaty za dzień wskazany w “feeStatusAt” i nie ma już dostępnych zapasów produktu), następnie INCLUDED_IN_STORAGE_FEE (nie pobraliśmy opłaty za dzień wskazany w “feeStatusAt”, podczas gdy są jeszcze dostępne zapasy produktu), następnie PREDICTION (przewidywana data naliczenia opłaty za magazynowanie, na podstawie ilości i średniej sprzedaży), następnie CHARGED (naliczyliśmy opłatę i jest już widoczna w rozliczeniach z Allegro) uporządkowane rosnąco według kwoty brutto;
- -storageFee - sortowanie według opłaty za przechowywanie (malejąco); jako pierwsze zwrócimy wszystkie opłaty ze statusem: CHARGED uporządkowana malejąco według kwoty brutto, następnie PREDICTION, INCLUDED_IN_STORAGE_FEE, a następnie NOT_APPLICABLE,
- asnStatus - określ status awizo dla produktów. Możliwe wartości: NOT_FOUND (tylko produkty, do których nie znaleźliśmy aktualnie utworzonego awizo, jest ono przedawnione lub produkty zostały już przyjęte do magazynu), SUBMITTED (tylko produkty, do których utworzone jest aktualne awizo - na tej podstawie dla zwróconych produktów w najbliższym czasie spodziewamy się uzupełnienia stanów magazynowych).
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/fulfillment/stock’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' Przykładowy response:
200 OK
{
"stock": [ - informacje o stanach magazynowych
produktów
{
"product": { - informacje o danym produkcie
"id": "7152gtf2-2265-4e15-b76b-c17025d84ft7", - ID produktu
"name": "iPhone 5s", - nazwa produktu
"gtins": [ - numery GTIN przypisane do
produktu
"2746650558857",
"1859832948337"
],
"image": "https://5.allegroimg.com/original/003358/a4f5dbb14d24971aff2ca5afb5d5"
}, - adres zdjęcia produktu
"quantity": {
“onOffer”: 5, - liczba sztuk produktu w aktywnej ofercie
"available": 5, - liczba sztuk produktu dostępna w magazynie
“onOrder”: 3, - liczba produktów zakupionych,
które nie zostały jeszcze wysłane
z magazynu.
“onHold”: 1 - towary, które znajdują się w
magazynie Allegro, ale nie mogą
trafić do sprzedaży
}
"sellingStats": { - statystyki sprzedaży
"lastWeekAverage": 4, - średnia sprzedaż w ciągu ostatniego tygodnia
"lastThirtyDaysSum": 200 - średnia sprzedaż w ciągu ostatnich 30 dni
},
"reserve": { - informacje o zapasach produktu
"outOfStockIn": 13, - przewidywana liczba dni, po których zapasy
produktu zostaną wyprzedane
"status": "LOW_STOCK" - aktualny status zapasów produktu. Listę dostępnych
wartości znajdziesz w naszej dokumentacji.
},
"storageFee": {
"status": "NOT_APPLICABLE", - status opłaty za przechowywanie; dostępne
wartości: NOT_APPLICABLE ,INCLUDED_IN_STORAGE_FEE, CHARGED,
PREDICTION
"feeStatusAt": "2023-02-17", - data naliczenia opłaty za przechowywanie
"details": { - szczegółowe informacje dotyczące opłaty za
przechowywanie (dostępne tylko w sytuacji,
gdy storageFee.status: “CHARGED”.
"feePayableAt": null, - przewidywana data naliczenia opłaty za magazynowanie,
na podstawie ilości i średniej sprzedaży
"chargedItemsQuantity": 3, - liczba sztuk produktów, za które została pobrana opłata
"amountGross": 123.45, - łączna pobrana opłata
"currency": "PLN" - waluta, w której została pobrana opłata
}
"offerId": "10000000015" - numer oferty powiązany z produktem
},
],
"count": 1, - liczba zwróconych wyników
"totalCount": 10 - całkowita liczba dostępnych
wyników
}Stany magazynowe możesz pobrać także jako plik CSV.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/fulfillment/stock’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: text/csv' \
-H 'Content-Type: text/csv' Przykładowy response:
Status 200 OK
"id_produktu","nazwa","na_ofercie","w_realizacji","niezdatne","url_obrazka","data_ostatniej_aktualizacji","data_wygenerowania_pliku","numery_seryjne"
"64325855-8201-4414-9b72-6ad9bad4906e","iPhone 8s","10","0","0","https://a.allegroimg-test.qxlint/original/11bc53/b6d1540c4350b8a5198906015478","2021-06-22 11:48","2021-07-05 07:57",""
"bcec6dfd-38a0-48c5-aec6-40849fa8d739","iPad Pro 2021","10","0","0","https://a.allegroimg-test.qxlint/original/11bc53/b6d1540c4350b8a5198906015478","2021-06-23 09:08","2021-07-05 07:57","KMsUzO,SJVdfu,Znmiym,ZodkNm,fbXLIv,fwndsn,jBVYMo,jSUtlE,mXMjAp,zXJLfR"Jak zarządzać sposobami usunięcia towaru z magazynu
Pobierz aktualne ustawienia sposobu usunięcia towaru z magazynu
Za pomocą GET /fulfillment/removal/preferences pobierzesz aktualne ustawienia sposobu usunięcia towaru z magazynu.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/fulfillment/removal/preferences’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \Przykładowy response:
{
"operation": "WITHDRAWAL", // sposób usunięcia towaru, dostępne wartości: WITHDRAWAL - wycofanie, DISPOSAL - utylizacja
"address": { // dane adresowe do zwrotu towaru, pole dostępne tylko dla operacji WITHDRAWAL
"company": "Company Warehouse Ltd", // nazwa firmy
"street": "Uliczna 7", // ulica
"postalCode": "60-166", // kod pocztowy
"city": "Poznań", // miasto
"countryCode": "PL", // kod kraju
"phone": { // telefon
"countryCode": "48", // numer kierunkowy kraju
"number": "123123123" // numer
},
"additionalInfo": "Left doors in the warehouse." // dodatkowe informacje dla kuriera
}
}Utwórz lub edytuj ustawienia sposobu usunięcia towaru z magazynu
Aby utworzyć lub edytować ustawienia sposobu usunięcia towaru z magazynu skorzystaj z PUT /fulfillment/removal/preferences.
Przykładowy request:
curl -X PUT \
'https://api.allegro.pl/fulfillment/removal/preferences’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d ‘{
"operation": "WITHDRAWAL", // sposób usunięcia towaru, dostępne wartości: WITHDRAWAL - wycofanie, DISPOSAL - utylizacja
"address": { // dane adresowe do zwrotu towaru, pole wymagane tylko dla operacji WITHDRAWAL
"company": "Company Warehouse Ltd", // nazwa firmy
"street": "Uliczna 7", // ulica
"postalCode": "60-166", // kod pocztowy
"city": "Poznań", // miasto
"countryCode": "PL", // kod kraju
"phone": { // telefon
"countryCode": "48", // numer kierunkowy kraju
"number": "123123123" // numer
},
"additionalInfo": "Left doors in the warehouse." // dodatkowe informacje dla kuriera
}
}'Przykładowy response:
{
"operation": "WITHDRAWAL",
"address": {
"company": "Company Warehouse Ltd",
"street": "Uliczna 7",
"postalCode": "60-166",
"city": "Poznań",
"countryCode": "PL",
"phone": {
"countryCode": "48",
"number": "123123123"
},
"additionalInfo": "Left doors in the warehouse."
}
}Jak obsługiwać zamówienia
Dla zamówień w ramach One Fulfilliment otrzymasz wszelkie dane w odpowiedzi GET /order/checkout-forms i GET /order/events, ale nie musisz ich procesować, ponieważ ich obsługą w pełni zajmie się nasz magazyn. Nie będziesz mógł także samodzielnie modyfikować statusu realizacji zamówienia w polu “fulfillment.status”.
Za pomocą GET /fulfillment/orders/{orderId}/parcels pobierzesz informacje o produktach, które magazyn wysłał do odbiorcy. W odpowiedzi zasobu znajdziesz takie dane, jak np. numer seryjny oraz data ważności produktów - informacje, które są potrzebne do wystawienia faktury.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/fulfillment/orders/{orderId}/parcels' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json'Przykładowy response:
{
"orderId": "dd4bbba0-d692-11ec-9eac-2d3687b9fed8", - numer zamówienia
"parcels": [ - informacje o przesyłkach nadanych
przez magazyn do odbiorcy w ramach
wskazanego zamówienia
{
"waybill": "1Z8332YF6895912532", - numer przesyłki
"items": [ - informacje o produktach zawartych w
przesyłce
{
“productId”: “0e810d4a-bbee-495c-8979-866bb06d3904”, - ID produktu
"quantity": 1, - liczba sztuk produktu
"serialNumbers": ["4CE0460D0G"], - numer seryjny produktu
"expirationDate": "2020-05-01", - data ważności. Jeśli produkt jej nie posiada,
zwrócimy null
"offerId": "10000000003" - ID powiązanej oferty
}
]
}
]
}