Dziennik zdarzeń
Jak znaleźć najnowsze zdarzenie
Jak pobrać dziennik zdarzeń dla zamówień
Szczegóły zamówienia
Zmiana statusu realizacji zamówienia
Lista zamówień
Nadpłaty i niedopłaty
Dopłaty
Jak rozpoznać zamówienie złożone w ramach programu Allegro Ceny
Przykładowe response'y dla różnych sytuacji
Sandbox
FAQ
Lista zasobów
Zamówienia w Allegro REST API
Dowiedz się, jak zrealizować zamówienia przez Allegro REST API.
Schemat procesu obsługi zamówień:
Dziennik zdarzeń
Za pomocą GET /order/events pobierzesz zdarzenia, które pozwolą Ci monitorować akcje takie jak:
- zakup,
- wypełnienie formularza opcji dostawy (FOD),
- anulowanie płatności,
- realizacja dopłaty,
- anulowanie zamówienia,
- zmiana statusu zamówienia.
Zdarzenia mogą mieć odpowiednie wartości w polu “type”, dzięki którym poznasz, na jakim etapie realizacji jest zamówienie. Wyróżniamy typy zdarzeń:
- BOUGHT - klient kupił, ale jeszcze nie zapłacił za zamówienie.
- FILLED_IN - zdarzenie z takim typem może pojawić się więcej niż raz, jeśli klient wypełni FOD kilka razy np. gdy nie zakończy płatności lub doszło do jej anulowania. Pamiętaj, że przy tym statusie mogą zmienić się dane, aż do czasu zakończenia płatności.
- READY_FOR_PROCESSING - klient wypełnił FOD i sfinalizował płatność (status: zakończona), albo wybrał płatność przy odbiorze lub odbiór osobisty. Dopiero w tym statusie zobaczysz adres dostawy jaki klient podał na FOD. Jeśli otrzymasz ten status, masz pewność, że w danych na FOD nic się już nie zmieni. Dlatego możesz:
- pobrać jego szczegóły,
- sprawdzić czy zgadza się kwota płatności,
- przejść do kolejnych kroków realizacji zamówienia.
- BUYER_CANCELLED - kupujący anulował zamówienie.
- FULFILLMENT_STATUS_CHANGED - oznacza zmianę statusu realizacji zamówienia przez sprzedającego.
- AUTO_CANCELLED - zamówienie zostało automatycznie anulowane przez Allegro.
- Dla każdego zamówienia musi wystąpić przynajmniej jedno zdarzenie (np. wypełnienie formularza opcji dostawy [FILLED_IN]).
- Może występować wiele zdarzeń dla jednego zamówienia (np. zakup, wypełnienie formularza opcji dostawy, wpłata).
- Możesz np. otrzymać kilka zdarzeń READY_FOR_PROCESSING, dlatego zwróć uwagę na identyfikator zamówienia w obiekcie checkoutForm i to właśnie na nim oprzyj swoją logikę obsługi zamówień.
- Zdarzenie “BUYER_CANCELLED” może pojawić się przed lub po READY_FOR_PROCESSING.
- Możesz pobrać zdarzenia z ostatnich 60 dni.
- Duplikaty zdarzeń możesz ustalić na podstawie typu zdarzenia i pola occurredAt.
- Z uwagi na uwarunkowania techniczne, w pojedynczych przypadkach zdarzenia mogą pojawić się w nieoczekiwanej kolejności; to znaczy, że jest możliwość by np. zdarzenie ze statusem READY_FOR_PROCESSING pojawiło się przed FILLED_IN; nie traktujemy tego jako błąd.
- Jeśli kupujący zrobi dwa oddzielne zakupy u tego samego sprzedającego, a następnie np. zaznaczy je do wspólnej zapłaty otrzymasz nowe zdarzenie z nowym checkoutForm.id. W zamówieniach zobaczysz tylko ostateczne zamówienie z nowym checkoutForm.id - poprzednie usuniemy. Aby zidentyfikować taką sytuację można np. oprzeć się na pojedynczym akcie zakupowym - lineItem.id (jeżeli jeden lineItem.id występuje w kilku zamówieniach oznacza to, że mamy do czynienia z połączeniem zakupów przez kupującego).
Jak znaleźć najnowsze zdarzenie
Za pomocą GET /order/event-stats pobierzesz informacje o ostatnim zdarzeniu zautoryzowanego sprzedającego.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/order/event-stats' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json'Przykładowy response:
{
"latestEvent": {
"id": "1532603898317497", - identyfikator najnowszego zdarzenia
"occurredAt": "2018-07-26T11:18:06.715Z" - data wystąpienia tego zdarzenia
}
}Jak pobrać dziennik zdarzeń dla zamówień
Za pomocą GET /order/events pobierzesz listę zdarzeń jako zalogowany sprzedawca. Domyślnie otrzymasz 100 najstarszych zdarzeń. Możesz także zawęzić otrzymane wyniki korzystając z filtrów:
- Identyfikatorów zdarzeń możesz użyć, aby pobrać kolejne porcje zdarzeń - wywołaj GET /order/events?from={last_seen_event_id}.
- Możesz też określić liczbę zdarzeń - określ na zasobie parametr limit w zakresie 1-1000 np. GET /order/events?limit=1000.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/order/events' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json'W response otrzymasz listę zdarzeń i ich identyfikatory, dzięki którym możesz otrzymać szczegóły zamówienia. Poniżej przykłady wywołań:
- pobierz 500 najnowszych zdarzeń po danym zdarzeniu: GET /order/events?limit=500&from={last_seen_event_id},
- pobierz 500 najstarszych zdarzeń danego typu (możliwe typy BOUGHT, FILLED_IN, READY_FOR_PROCESSING): GET /order/events?limit=500&type=READY_FOR_PROCESSING.
Kliknij, aby zobaczyć response
{
"events": [
{
"id": "1531736019951454", - identyfikator zdarzenia
"order": {
"seller": {
"id": "42334554" - identyfikator sprzedającego
},
"buyer": {
"id": "1424041", - identyfikator kupującego
"email": "example@mail.pl, - adres e-mail kupującego
"guest": false, - przyjmuje dwie wartości:
false (zalogowany klient)
i true (zakup przez
niezalogowanego)
"login": "example_login", - login kupującego
"preferences": {
"language": "pl-PL" - preferowany język kupującego
},
},
"lineItems": [
{
"offer": {
"id": "7458058360", - numer oferty
"name": "Telewizor Sony '21", - tytuł oferty
"external": {
"id": "extid_1234" - zewnętrzny identyfikator oferty
}
},
"price": {
"amount": "2999", - cena w chwili zakupu
uwzględniająca ewentualne
zniżki np. rabat ilościowy,
zestawy, itp.)
"currency": "PLN"
},
"id": "d0f7e940-88e0-11e8-81ae-4d76b42da07e", - identyfikator pozycji
zamówienia
"quantity": 1, - liczba przedmiotów kupionych
w zamówieniu przez kupującego
"originalPrice": {
"amount": "2999", - pierwotna cena w ofercie, przed
zastosowaniem jakichkolwiek zniżek
(rabatów ilościowych, zestawów
itp.)
"currency": "PLN"
},
"boughtAt": "2018-07-16T10:13:28.147Z" - data zakupu
}
],
"checkoutForm": {
"id": "d0f7e942-88e0-11e8-81ae-4d76b42da07e", - identyfikator zamówienia
"revision": "d8e8fca2" - wersja zamówienia
},
"marketplace": {
"id": "allegro-pl" - identyfikator serwisu
}
},
"type": "BOUGHT", - status zdarzenia
"occurredAt": "2018-07-16T10:13:28.147Z" - data wystąpienia zdarzenia
},
{
"id": "1531736028695867",
"order": {
"seller": {
"id": "42334554"
},
"buyer": {
"id": "1424041",
"email": "example1@mail.pl/",
"guest": false,
"login": "example_login1",
"preferences": {
"language": "pl-PL"
}
},
"lineItems": [
{
"offer": {
"id": "7458058360",
"name": "Telewizor Sony '21",
"external": null,
"productSet": null
},
"price": {
"amount": "2999",
"currency": "PLN"
},
"id": "d0f7e940-88e0-11e8-81ae-4d76b42da07e",
"quantity": 1,
"originalPrice": {
"amount": "2999",
"currency": "PLN"
},
"boughtAt": "2018-07-16T10:13:28.147Z"
}
],
"checkoutForm": {
"id": "d0f7e942-88e0-11e8-81ae-4d76b42da07e",
"revision": "d8e8fca2"
}
"marketplace": {
"id": "allegro-pl"
}
},
"type": "FILLED_IN",
"occurredAt": "2018-07-16T10:13:37.925Z"
},
]
}Szczegóły zamówienia
Wywołaj GET /order/checkout-forms/{id}, aby otrzymać szczegóły zamówienia takie jak:
dane dotyczące zakupionych ofert,
dane klienta,
status zamówienia,
informacje o płatności,
dane do wysyłki,
dane do faktury,
informacje o wybranych opcjach dodatkowych.
Identyfikatory zamówień pobierzesz za pomocą GET /order/events (pole ‘events_checkoutForm’) lub GET /order/checkout-forms.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/order/checkout-forms/{id}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}' Kliknij, aby zobaczyć response
{
"id": "ffc396b0-9584-11e8-8d53-07c966f77738", - identyfikator zamówienia
"buyer": {
"id": "1424041", - identyfikator kupującego
"email": "ymu1woaqq+54111a037@allegrogroup.pl",
- adres e-mail kupującego
"login": "example_login", - login kupującego
"firstName": "Tomasz", - imię
"lastName": "Nowak", - nazwisko
"companyName": null, - nazwa firmy
"guest": false, - czy kupujący jest zarejestrowanym użytkownikiem
"personalIdentity": null, - numer PESEL
"phoneNumber": "+48 11 1111111", - numer telefonu z ustawień konta kupującego
"preferences": {
"language": "pl-PL" - preferowany język kupującego
},
"address": { - dane adresowe z ustawień konta
"street": "Bułgarska 69", - ulica
"city": "Poznań", - miasto
"postCode": "18-282", - kod pocztowy
"countryCode": "PL", - kod kraju
}
},
"payment": {
"id": "1e5c8911-9585-11e8-96ed-27298c74ae02", - identyfikator płatności
"type": "CASH_ON_DELIVERY", - rodzaj płatności, przyjmuje wartości:
“ONLINE”, "CASH_ON_DELIVERY", "SPLIT_PAYMENT",
"EXTENDED_TERM"
"provider": null,
"finishedAt": "2019-07-23T12:58:58.609Z", - data przekazania formularza do
realizacji
"paidAmount": null
},
"status": "READY_FOR_PROCESSING", - status płatności
"fulfillment": { - status realizacji zamówienia
"status": "PROCESSING"
"shipmentSummary": {
"lineItemsSent": "ALL" - informacja, czy do przedmiotów w
zamówieniu dołączono numery przesyłek.
Listę wartości znajdziesz w naszej dokumentacji.
}
}
"delivery": { - dane adresowe klienta z formularza
dostawy
"address": {
"firstName": "Tomasz", - imię
"lastName": "Nowak", - nazwisko
"street": "Bułgarska 69", - ulica
"city": "Poznań", - miasto
"zipCode": "18-282", - kod pocztowy
"countryCode": "PL", - kod kraju
"phoneNumber": "000333666" - numer telefonu kupującego z formularza dostawy
"modifiedAt": null - data modyfikacji adresu przez kupującego
},
"method": {
"id": "85c3ad2f-4ec1-446c-866e-63473ed10e26", - identyfikator metody dostawy
"name": "Allegro Kurier24 InPost" - nazwa metody dostawy
},
"cost": {
"amount": "15.87", - koszt dostawy
"currency": "PLN"
},
"smart": false - przyjmuje dwie wartości:
true (kupujący skorzystał z opcji
smart), false (kupujący nie skorzystał
z opcji smart)
"time": {
"from": "2023-04-28T14:59:59.999Z", - czas dostawy od godz.
"to": "2023-04-28T22:59:59.999Z", - czas dostawy do godz.
"dispatch": {
"from": "2023-04-27T16:00:00Z", - czas wysyłki od godz.
"to": "2023-04-27T18:00:00Z" - czas wysyłki do godz.
},
"guaranteed": { - gwarantowany czas dostawy (deprecated)
"from": "2019-07-31T16:00:00Z", - czas dostawy od godz.
"to": "2019-07-31T18:00:00Z" - czas dostawy do godz.
}
},
"calculatedNumberOfPackages": null - łączna liczba przesyłek w zamówieniu
(zwracamy dla zamówień
utworzonych po 07.10.2019)
"cancellation": { - informacja o odstąpieniu od dostawy
(dotyczy tylko zakupu z kategorii Alkohole);
null - brak odstąpienia od dostawy
"date": "2025-04-01T10:15:30.133Z"
}
},
"invoice": { - informacja o danych do faktury
"required": true,
"address": {
"street": "Grunwaldzka 166",
"city": "Poznan",
"zipCode": "60-166",
"countryCode": "PL",
"company": {
"name": "Allegro",
"taxId": "5252674798"
},
"naturalPerson": null
},
"dueDate": null
},
"lineItems": [ - przedmioty wchodzące w skład
zamówienia
{
"id": "ffc36fa0-9584-11e8-8d53-07c966f77738",
"offer": {
"id": "6205584023", - numer oferty
"name": "Koło ratunkowe", - tytuł oferty
"external": {
"id": "ext_2018_08_17" - zewnętrzny identyfikator oferty
},
"productSet": { - zestawy produktów
"products": [ - lista produktów w zestawie
{
"id": "9d689aa5-f2ad-4bdc-bb97-6b196854e6c7", - ID produktu
"quantity": 1 - liczba produktów w danym zestawie
},
{
"id": "280ee7f4-7b69-4a71-84dd-c88f95594402",
"quantity": 1
}
]
}
},
"quantity": 2, - liczba przedmiotów kupionych w
ofercie
"originalPrice": {
"amount": "76.00", - koszt przedmiotu przed ew. rabatem
"currency": "PLN"
},
"price": {
"amount": "76.00", - koszt przedmiotu po rabacie
"currency": "PLN"
},
"selectedAdditionalServices": [ - informacja o zakupionych usługach
{
"definitionId": "GIFT_WRAP", - identyfikator usługi dodatkowej
"name": "Zapakuj na prezent", - nazwa usługi dodatkowej
"price": {
"amount": "10.00", - jednostkowy koszt usługi
"currency": "PLN"
},
"quantity": 2 - liczba wykupionych usług dodatkowych
}
],
"boughtAt": "2018-08-01T12:18:33.434Z", - data zakupu
"discounts": [ - informacja o rabacie i zniżce dla pozycji zakupowej
{
"type": "CAMPAIGN"
}
]
}
],
"surcharges": [], - informacje o ew. dopłatach
"discounts": [ - zniżki z których skorzystał
kupujący podczas zakupów, pole oznaczone jako "deprecated"
{
"type": "CROSSMULTIPACK" - niektóre przedmioty z zamówienia
zostały kupione z rabatem ilościowym
na wielu ofertach
},
{
"type": "MULTIPACK" - co najmniej jeden przedmiot
w zamówieniu został kupiony
z rabatem ilościowym
},
{
"type": "BUNDLE" - niektóre przedmioty z zamówienia
zostały kupione w zestawie
},
{
"type": "COUPON" - podczas płatności użyto kuponu
}
],
"note": null,
"marketplace": {
"id": "allegro-pl" - identyfikator serwisu
},
"summary": {
"totalToPay": {
"amount": "187.87", - całkowita wartość zamówienia
"currency": "PLN"
}
},
"updatedAt": "2018-08-01T12:18:33.763Z", - data ostatniej zmiany zamówienia
"revision": "dc0f896f" - wersja zamówienia
}Zmiana statusu realizacji zamówienia
Za pomocą PUT /order/checkout-forms/{id}/fulfillment zmienisz status realizacji zamówienia widoczny w polu fulfillment.status. Jako id przekaż numer zamówienia, który otrzymasz w odpowiedzi dla GET /order/checkout-forms.
Przykładowy request:
curl -X PUT \
'https://api.allegro.pl/order/checkout-forms/{checkoutFormId}/fulfillment' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d '{
"status": "SENT" - przykładowe wartości: NEW (nowe),
PROCESSING (w realizacji), etc.
Pełną listę znajdziesz w naszej dokumentacji.
}'Do wywołania możesz dodać także opcjonalny parametr checkoutForm.revision.
Przykładowy request:
curl -X PUT \
'https://api.allegro.pl/order/checkout-forms/29738e61-7f6a-11e8-ac45-09db60ede9d6/fulfillment?checkoutForm.revision=dc0f896f' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d '{
"status": "PROCESSING"
}'Jeżeli wartość pola “checkoutForm.revision”:
będzie równa aktualnej wersji zamówienia w naszym systemie, to zmienimy status realizacji zamówienia;
będzie różna od aktualnej wersji zamówienia w naszym systemie (np. kupujący wykonał zmianę statusu zamówienia, płatności, danych adresowych, danych do faktury, itp.), to zwrócimy błąd ze statusem 409 CONFLICT. Błąd oznacza, że musisz pobrać nowszą wersję zamówienia, ponieważ zaszły w nim zmiany, po czym spróbować ponownie zmienić status z nową wartością pola “checkoutForm.revision”.
Jeśli sprzedawca korzysta z abonamentu, w zakładce Zamówienia może ustawić automatyczną:
- zmianę statusu na “SENT”, gdy doda numer przesyłki,
- wysyłkę wiadomości do kupującego po zmianie statusu.
Anulowanie zamówienia
Jeżeli masz konto Firma oraz nie zmieniłeś statusu realizacji zamówienia (na status “PROCESSING”, “READY_FOR_SHIPMENT”, “SENT”, “READY_FOR_PICKUP”, “PICKED_UP”) lub nie dodałeś numeru przesyłki do zamówienia, to Kupujący może anulować zamówienie w ciągu 3 dni od zakupu. Dlatego, gdy rozpoczynasz obsługę zamówienia, każdorazowo zmień status realizacji (“fulfillment.status”). Jeżeli kupujący anulował opłacone już zamówienie, zwróć otrzymaną wpłatę za pomocą POST /payments/refunds.
Kliknij, aby zobaczyć response
{
"id": "c6287a22-57b5-31ea-93bf-4dbbe06503ca",
"messageToSeller": null,
"buyer": {
"id": "111222333",
"email": "yuxwjq25z4+52353b6a2@allegromail.pl",
"login": "TestABC",
"firstName": "Jan",
"lastName": "Nowak",
"companyName": null,
"guest": false,
"personalIdentity": null,
"phoneNumber": "+48 700 700 700",
"preferences": {
"language": "pl-PL"
},
"address": {
"street": "Grunwaldzka 182",
"city": "Poznań",
"postCode": "60-166",
"countryCode": "PL"
}
},
"payment": {
"id": "2dae8362-57b6-11ea-97c2-b71e91a5aa42",
"type": "ONLINE",
"provider": "PAYU",
"finishedAt": "2020-05-05T10:06:39.065Z", - data otrzymania płatności
"paidAmount": { - kwota wpłaty (jeśli zamówienie zostało
"amount": "1.00", anulowane zwróć wpłatę przez
"currency": "PLN" POST /payments/refunds)
}
},
"status": "CANCELLED", - status zamówienia
"fulfillment": {
"status": "NEW",
"shipmentSummary": {
"lineItemsSent": "NONE"
}
},
"delivery": {
"address": {
"firstName": "Jan",
"lastName": "Nowak",
"street": "Grunwaldzka 182",
"city": "Poznań",
"zipCode": "60-166",
"countryCode": "PL",
"companyName": null,
"phoneNumber": "700700700"
},
"method": {
"id": "7203cb90-864c-4cda-bf08-dc883f0c78ad",
"name": "Przesyłka kurierska"
},
"pickupPoint": null,
"cost": {
"amount": "0.00",
"currency": "PLN"
},
"smart": false,
"time": {
"guaranteed": null
},
"calculatedNumberOfPackages": 1
},
"invoice": {
"required": false,
"address": null
},
"lineItems": [
{
"id": "c6287a20-57b5-11ea-93bf-4dbbe06503ca",
"offer": {
"id": "8969787034",
"name": "Test",
"external": null
},
"quantity": 1,
"originalPrice": {
"amount": "1.00",
"currency": "PLN"
},
"price": {
"amount": "1.00",
"currency": "PLN"
},
"selectedAdditionalServices": [],
"boughtAt": "2020-05-05T10:01:53.657Z"
}
],
"surcharges": [],
"discounts": [],
"marketplace": {
"id": "allegro-pl"
},
"summary": {
"totalToPay": {
"amount": "1.00",
"currency": "PLN"
}
},
"updatedAt": "2020-05-05T10:06:39.065Z",
"revision": "dc0f896f"
}Automatyczne anulowanie zamówienia
Jeżeli kupujący wybierze opcję płatności z góry i nie opłaci zamówienia w ciągu 7 dni to zamówienie zostanie automatycznie anulowane przez Allegro. W ustawieniach zakładki Zamówienia sprzedający może ustawić własny termin, po którym automatycznie anulujemy nieopłacone zamówienia we wszystkich ofertach na jego koncie. Nie może on być jednak krótszy niż 7 dni ani dłuższy niż 30 dni.
Lista zamówień
GET /order/checkout-forms - pozwoli ci pobrać listę zamówień. W takiej formie zapytanie zwróci maksymalnie 100 najnowszych zamówień. Lista zawiera zamówienia z ostatnich 12 miesięcy, z takim samym zestawem danych, jakie możesz zobaczyć w szczegółach zamówienia.
Dane zawracane w response sortujemy na podstawie daty z pola "boughtAt". Jeśli użytkownik zapłaci za zakupione towary później informacja o takim zamówieniu nie pojawi się jako najnowsza, tylko zgodnie z datą zakupu. Dlatego korzystaj z dziennika zdarzeń, by monitorować sprzedaż i poprawnie pobierać informacje o najnowszych zamówieniach.
Możesz również pobrać listę zamówień dostosowaną do twoich potrzeb używając parametrów:
- limit - określ liczbę zamówień, jaką mamy zwrócić w odpowiedzi (przyjmuje wartości w zakresie 1-100),
offset - wskaż miejsce, od którego chcesz pobrać kolejną porcję danych (przyjmuje wartości od 0 do liczba zamówień -1).
np. GET /order/checkout-forms?limit=10&offset=9 - zwróci listę 10 zamówień od podanego punktu. Suma offset i limit nie może przekroczyć 10 000.
Skorzystaj z filtrów:
- Status zamówienia - może zawierać jedną lub więcej wartości, np. GET /order/checkout-forms?status=BOUGHT&status=FILLED_IN;
- Status realizacji - może zawierać jedną lub więcej wartości, np. GET /order/checkout-forms?fulfillment.status=NEW&fulfillment.status=PROCESSING;
- Identyfikator płatności - GET /order/checkout-forms?payment.id=682c64b2-3108-11e9-b62a-6d16ee003b16;
- Identyfikator dopłaty - GET /order/checkout-forms?surcharges.id=21f96ba2-714f-11e9-a1f2-5b017850bf22;
- Data zamówienia - zakres czasu przekazujesz zgodnie z przyjętym standardem, ale chcąc przekazać datę w url, pamiętaj, aby wykorzystać encode, np. GET /order/checkout-forms?lineItems.boughtAt.lte=2018-07-31T08%3A48%3A14.889Z&lineItems.boughtAt.gte=2018-07-31T08%3A48%3A14.888Z;
- Data ostatniej zmiany zamówienia - np. GET /order/checkout-forms?updatedAt.lte=2018-07-31T08%3A48%3A14.889Z&updatedAt.gte=2018-07-31T08%3A48%3A14.888Z;
- Informacja o załączonych numerach przesyłek - np. GET /order/checkout-forms?fulfillment.shipmentSummary.lineItemsSent=ALL - zwróci zamówienia, gdzie dla wszystkich przedmiotów, które wchodzą w jego skład, dodano numer przesyłki;
- Serwis, w którym złożone zostało zamówienie - np. GET /order/checkout-forms?marketplace.id=allegro-pl.
Jeśli kupujący zrobił np. dwa oddzielne zakupy przez koszyk lub Kup Teraz, a następnie postanowił zapłacić za nie wspólnie (wypełnił wspólny FOD), to dostaniesz nowe zamówienie z nowym identyfikatorem id. Poprzednie zamówienia, oddzielne dla każdego z tych zakupów usuniemy - pozostanie tylko to ostatnie.
Kliknij, aby zobaczyć response
{
"checkoutForms": [
{
"id": "a8f086f0-9583-11e8-8d53-07c966f77738", - identyfikator zamówienia
"messageToSeller": "wiadomość", - wiadomość od kupującego
"buyer": {
"id": "43544044", - identyfikator kupującego
"email": "ymuwoaqq+54111a037@allegrogroup.pl/",
- adres e-mail kupującego
"login": "example_login", - login kupującego
"firstName": "Tomasz", - imię
"lastName": "Nowak", - nazwisko
"companyName": null, - nazwa firmy
"guest": false, - czy kupujący jest zarejestrowanym
użytkownikiem
"personalIdentity": null, - numer PESEL
"phoneNumber": "+48 11 1111111", - numer telefonu z ustawień konta kupującego
"preferences": {
"language": "pl-PL" - preferowany język kupującego
},
"address": { - dane adresowe z ustawień konta
"street": "Bułgarska 6990", - ulica
"city": "Poznań", - miasto
"postCode": "18-282", - kod pocztowy
"countryCode": "PL", - kod kraju
}
},
"payment": { - informacje o płatności
"id": "abd30d72-9583-11e8-96ed-27298c74ae02", - numer płatności
"type": "ONLINE", - rodzaj płatności, przyjmuje wartości:
“ONLINE”, “CASH_ON_DELIVERY", "SPLIT_PAYMENT"
"provider": "PAYU" - pośrednik płatności, przyjmuje wartości:
“PAYU”, "P24”, "OFFLINE"
},
"status": "FILLED_IN", - status zamówienia
"fulfillment": { - status realizacji zamówienia
"status": "PROCESSING"
"shipmentSummary": {
"lineItemsSent": "NONE" - informacja, czy do przedmiotów w
zamówieniu dołączono numery przesyłek.
Listę wartości znajdziesz
w naszej dokumentacji.
}
}
"delivery": { - informacje o dostawie
"method": {
"id": "5d9c7838-e05f-4dec-afdd-58e884170ba7", - identyfikator metody dostawy
"name": "Allegro Kurier24 InPost" - nazwa metody dostawy
},
"cost": {
"amount": "13.41", - koszt dostawy
"currency": "PLN"
},
"smart": false - przyjmuje dwie wartości:
true (kupujący skorzystał z opcji
smart), false (kupujący nie
skorzystał z opcji smart)
"time": {
"from": "2023-04-28T14:59:59.999Z", - czas dostawy od godz.
"to": "2023-04-28T22:59:59.999Z", - czas dostawy do godz.
"dispatch": {
"from": "2023-04-27T16:00:00Z", - czas wysyłki od godz.
"to": "2023-04-27T18:00:00Z" - czas wysyłki do godz.
},
"guaranteed": { - gwarantowany czas dostawy (deprecated)
"from": null, - czas dostawy od godz.
"to": "2019-07-31T18:00:00Z" - czas dostawy do godz.
}
},
"calculatedNumberOfPackages": null - łączna liczba przesyłek w zamówieniu
(zwracamy dla zamówień
utworzonych po 07.10.2019)
"cancellation": { - informacja o odstąpieniu od dostawy
(dotyczy tylko zakupu z kategorii Alkohole);
null - brak odstąpienia od dostawy
"date": "2025-04-01T10:15:30.133Z"
}
},
"invoice": { - informacje o danych do faktury
"required": false
},
"lineItems": [ - informacja o przedmiotach
wchodzących w skład zamówienia
{
"id": "38h7b340-8583-12e8-9d53-08c966f55539",
"offer": {
"id": "6205584020", - numer oferty
"name": "Perkusja dęta", - tytuł oferty
"external": {
"id": "ext_2018_08_17" - zewnętrzny identyfikator oferty
},
"productSet": { - zestawy produktów
"products": [ - lista produktów w zestawie
{
"id": "9d689aa5-f2ad-4bdc-bb97-6b196854e6c7", - ID produktu
"quantity": 1 - liczba produktów w danym zestawie
},
{
"id": "280ee7f4-7b69-4a71-84dd-c88f95594402",
"quantity": 1
}
]
}
},
"quantity": 1, - liczba przedmiotów kupionych
w ramach oferty
"originalPrice": {
"amount": "240.00", - koszt przedmiotu przed ew.
rabatem
"currency": "PLN"
},
"price": {
"amount": "240.00", - koszt przedmiotu po uwzględnieniu
ew. rabatu, kuponu
"currency": "PLN"
},
"selectedAdditionalServices": [ - informacja o zakupionych usługach
{
"definitionId": "GIFT_WRAP", - identyfikator usługi dodatkowej
"name": "Zapakuj na prezent", - nazwa usługi dodatkowej
"price": {
"amount": "10.00", - jednostkowy koszt usługi
"currency": "PLN"
},
"quantity": 1 - liczba wykupionych usług dodatkowych
}
],
"boughtAt": "2018-08-01T12:09:30.044Z",
"discounts": [ - informacja o rabacie i zniżce dla pozycji zakupowej
{
"type": "CAMPAIGN"
}
]
}
],
"surcharges": [],
"discounts": [ - zniżki z których skorzystał
kupujący podczas zakupów, pole oznaczone jako "deprecated"
{
"type": "CROSSMULTIPACK" - niektóre przedmioty z zamówienia
zostały kupione z rabatem ilościowym
na wielu ofertach
},
{
"type": "MULTIPACK" - co najmniej jeden przedmiot
w zamówieniu został kupiony
z rabatem ilościowym
},
{
"type": "BUNDLE" - niektóre przedmioty z zamówienia
zostały kupione w zestawie
},
{
"type": "COUPON" - podczas płatności użyto kuponu
}
],
"note": null,
"marketplace": {
"id": "allegro-pl" - identyfikator serwisu
},
"summary": {
"totalToPay": {
"amount": "263.41",
"currency": "PLN"
}
},
"updatedAt": "2018-08-01T12:09:33.763Z"
"revision": "dc0f896f"
},
{
"id": "39f6cc51-9583-11e8-8d53-07c966f77738",
"buyer": {
"id": "43544033",
"email": "ymuwoaqq+54221a037@allegrogroup.pl",
"login": "example_login",
"firstName": "Andrzej",
"lastName": "Nowak",
"companyName": null,
"guest": false,
"personalIdentity": null,
"phoneNumber": "+381 11 1111111",
"preferences": {
"language": "pl-PL"
},
"address": {
"street": "Bułgarska 6991",
"city": "Poznań",
"postCode": "18-282",
"countryCode": "PL",
}
},
"status": "BOUGHT",
"fulfillment": {
"status": "NEW"
"shipmentSummary": {
"lineItemsSent": "NONE" - informacja, czy do przedmiotów w
zamówieniu dołączono numery przesyłek.
Listę wartości znajdziesz
w naszej dokumentacji.
}
}
"lineItems": [
{
"id": "39f6a540-9583-11e8-8d53-07c966f77738",
"offer": {
"id": "6205584018",
"name": "Laptop Lenovo",
"productSet": null
},
"quantity": 1,
"originalPrice": {
"amount": "3300.00",
"currency": "PLN"
},
"price": {
"amount": "3300.00",
"currency": "PLN"
},
"selectedAdditionalServices": [ - informacja o zakupionych usługach
{
"definitionId": "GIFT_WRAP", - identyfikator usługi dodatkowej
"name": "Zapakuj na prezent", - nazwa usługi dodatkowej
"price": {
"amount": "10.00", - jednostkowy koszt usługi
"currency": "PLN"
},
"quantity": 1 - liczba wykupionych usług dodatkowych
}
],
"boughtAt": "2018-08-01T12:05:53.027Z",
"discounts": null
}
],
"surcharges": [],
"discounts": [],
"note": null,
"marketplace": {
"id": "allegro-pl"
},
"summary": {
"totalToPay": {
"amount": "3310.00",
"currency": "PLN"
}
},
"updatedAt": "2018-08-01T12:05:53.763Z"
"revision": "dc0f896g"
},
{
"id": "4db701f0-7e9b-11e8-a346-0ff9a46a7007",
"buyer": {
"id": "43544066",
"email": "ymuwoaqq+54221a037@allegrogroup.pl/",
"login": "example_login",
"firstName": "Jan",
"lastName": "Nowak",
"companyName": null,
"guest": false,
"personalIdentity": null,
"phoneNumber": "+381 11 1111111",
"preferences": {
"language": "pl-PL"
},
"address": {
"street": "Bułgarska 6900",
"city": "Poznań",
"postCode": "18-282",
"countryCode": "PL",
}
},
"payment": {
"id": "abd30d72-9583-11e8-96ed-27298c74ae02", - numer płatności
"type": "ONLINE", - rodzaj płatności, przyjmuje wartości:
“ONLINE”, “CASH_ON_DELIVERY", "SPLIT_PAYMENT"
"finishedAt": "2018-07-03T08:31:34.731Z", - data zakończenia płatności
"paidAmount": { - kwota do zapłaty
"amount": "4351.60", - wysokość wpłaty
"currency": "PLN"
}
},
"status": "READY_FOR_PROCESSING",
"fulfillment": {
"status": "PROCESSING"
"shipmentSummary": {
"lineItemsSent": "ALL" - informacja, czy do przedmiotów w
zamówieniu dołączono numery przesyłek.
Listę wartości znajdziesz
w naszej dokumentacji.
}
}
"delivery": { - adres klienta z formularza
dostawy
"address": {
"firstName": "Jan", - imię klienta
"lastName": "Nowak", - nazwisko klienta
"street": "Rynek 8938", - ulica
"city": "Poznań", - miasto
"zipCode": "61-208", - kod pocztowy
"countryCode": "PL", - kod kraju
"phoneNumber": "+48 793 666 808" - numer telefonu kupującego
z formularza dostawy
},
"method": {
"id": "2488f7b7-5d1c-4d65-b85c-4cbcf253fd93",
"name": "Allegro Paczkomaty InPost"
},
"pickupPoint": {
id”: “POZ08A”,
"name": "Paczkomat POZ22N",
"description": "Przy sklepie Społem PSS",
"address": {
"street": "Oświecenia 59",
"zipCode": "61-208",
"city": "Poznań",
"countryCode": "PL"
}
},
"cost": {
"amount": "8.60",
"currency": "PLN"
},
"smart": false,
"calculatedNumberOfPackages": null - łączna liczba przesyłek w zamówieniu
(zwracamy dla zamówień
utworzonych po 07.10.2019)
"cancellation": null // - informacja o odstąpieniu od dostawy
(dotyczy tylko zakupu z kategorii Alkohole);
null - brak odstąpienia od dostawy
},
"invoice": {
"required": false
},
"lineItems": [
{
"id": "4db6dae0-7e9b-11e8-a346-0ff9a46a7007",
"offer": {
"id": "6205387764",
"name": “podręczniki do 1 klasy",
"productSet": null
},
"quantity": 1,
"originalPrice": {
"amount": "4343.00",
"currency": "PLN"
},
"price": {
"amount": "4343.00",
"currency": "PLN"
},
"selectedAdditionalServices": [ - informacja o zakupionych usługach
{
"definitionId": "GIFT_WRAP", - identyfikator usługi dodatkowej
"name": "Zapakuj na prezent", - nazwa usługi dodatkowej
"price": {
"amount": "10.00", - jednostkowy koszt usługi
"currency": "PLN"
},
"quantity": 1 - liczba wykupionych usług dodatkowych
}
],
"boughtAt": "2018-07-03T08:31:15.615Z",
"discounts": null
}
],
"surcharges": [],
"discounts": [],
"note": null,
"marketplace": {
"id": "allegro-pl"
},
"summary": {
"totalToPay": {
"amount": "4361.60",
"currency": "PLN"
}
},
"updatedAt": "2018-07-03T08:31:15.763Z"
"revision": "dc0f896h"
}
],
"count": 3, - liczba zamówień w tej odpowiedzi
"totalCount": 3 - liczba wszystkich dostępnych zamówień
dla sprzedającego
}Nadpłaty i niedopłaty
W niektórych przypadkach klient może wpłacić nieodpowiednią kwotę za zakupione przedmioty. Wtedy w zamówieniu może wystąpić nadpłata lub niedopłata. Można ją w łatwy sposób wyliczyć np. poprzez porównanie wartości z pól summary.totalToPay.amount i payment.paidAmount.amount. Jak wyeliminować niedopłaty/nadpłaty:
Dopłaty
W przypadku dopłaty, w szczegółach zamówienia ze statusem "READY_FOR_PROCESSING" znajdziesz dodatkowy blok "surcharges". Strukturę dopłaty znajdziesz poniżej.
Dopłata - w sytuacji, gdy kupujący nie zakończył płatności:
"surcharges": [
{
"id": "5b1f4a62-6969-11e8-b090-8b2d9f391430", - identyfikator dopłaty
"type": "ONLINE",
"provider": "PAYU"
}
],
Dopłata - kupujący zakończył płatność:
"surcharges": [
{
"id": "5b1f4a62-6969-11e8-b090-8b2d9f391430", - identyfikator dopłaty
"type": "ONLINE",
"provider": "PAYU"
"finishedAt": "2018-06-06T11:11:23.351", - data wpłaty (dopłaty)
"paidAmount": {
"amount": “12.00”, - wartość dopłaty
"currency": "PLN"
}
}
],Jak rozpoznać zamówienie złożone w ramach programu Allegro Ceny
Odpytując GET /order/checkout-forms oraz GET /order/checkout-forms/{id} rozpoznasz zamówienia, w ramach których partycypowaliśmy w częściowym pokryciu ceny i wyrównaliśmy wartości obniżki w ramach programu Allegro Ceny. W takich przypadkach w polu discounts zwrócimy typ obniżki: "ALLEGRO_PRICES".
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/order/checkout-forms/4fceac60-71c6-11eb-bb0e-5f505b61d1dc' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}' Kliknij, aby zobaczyć response
{
...
"payment": {
"id": "677d4ba1-71c6-11eb-a259-c766517115fd",
"type": "ONLINE",
"provider": "PAYU",
"finishedAt": "2021-03-15T12:18:33.434Z",
"paidAmount": {
"amount": "80",
"currency": "PLN"
},
"reconciliation": null
},
"status": "READY_FOR_PROCESSING",
...
"lineItems": [
{
"id": "ffc36fa0-9584-11e8-8d53-07c966f77738",
"offer": {
"id": "6205584023",
"name": "Koło ratunkowe",
"external": {
"id": "ext_2018_08_17"
},
"productSet": null
},
"quantity": 1,
"originalPrice": {
"amount": "80.00",
"currency": "PLN"
},
"price": {
"amount": "80.00",
"currency": "PLN"
},
"reconciliation": {
"value": {
"amount": "20.00", - kwota, którą wyrównuje Allegro za
pojedynczy przedmiot
"currency": "PLN"
},
"quantity": 1, - liczba przedmiotów, do których
przyznaliśmy wyrównanie
"type": "BILLING" - typ wyrównania, przyjmuje jedną z wartości:
BILLING (wyrównanie w ramach zapisu bilingowego);
WALLET (wyrównanie w ramach wpłaty).
},
"selectedAdditionalServices": [ ],
"boughtAt": "2021-03-15T12:18:33.434Z"
}
],
"surcharges": [],
"discounts": [
{
"type": "ALLEGRO_PRICES" - typ obniżki ALLEGRO_PRICES oznacza,
że w ramach zamówienia obniżyliśmy cenę
przyznaliśmy wyrównanie
}
],
"summary": {
"totalToPay": {
"amount": "80.00",
"currency": "PLN"
}
},
"updatedAt": "2021-03-15T12:18:33.434Z",
"revision": "dc0f896f"
}Typ obniżki dla danego przedmiotu rozpoznasz dzięki polu lineItems[].reconciliation.type, które może zwrócić następujące wartości:
- "BILLING" - wyrównanie wartości obniżki w postaci zapisu bilingowego,
- "WALLET" - wyrównanie wartości obniżki w postaci środków dodanych do płatności od Kupującego.
Sumę wyrównania dla danego przedmiotu sprawdzisz niezależnie od typu obniżki w obiekcie lineItems[].reconciliation.value.
W przypadku obniżki typu "WALLET", zwrócimy także sumę wyrównania płatności w obiekcie payment.reconciliation. Sprzedający otrzyma wpłatę, której wartość sprawdzisz sumując payment.paidAmount.amount oraz payment.reconciliation.amount.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/order/checkout-forms/4fceac60-71c6-11eb-bb0e-5f505b61d2dd' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}' Kliknij, aby zobaczyć response
{
...
"payment": {
"id": "677d4ba1-71c6-11eb-a259-c766517115fd",
"type": "ONLINE",
"provider": "PAYU",
"finishedAt": "2021-03-15T12:18:33.434Z",
"paidAmount": {
"amount": "80", - suma płatności, którą zapłacił
kupujący
"currency": "PLN"
},
"reconciliation": {
"amount": "20", - kwota, którą wyrównaliśmy w płatności
(dodaliśmy do płatności kupującego)
"currency": "PLN"
}
},
"status": "READY_FOR_PROCESSING",
...
"lineItems": [
{
"id": "ffc36fa0-9584-11e8-8d53-07c966f77738",
"offer": {
"id": "6205584023",
"name": "Koło ratunkowe",
"external": {
"id": "ext_2018_08_17"
}
"productSet": null
},
"quantity": 1,
"originalPrice": {
"amount": "80.00",
"currency": "PLN"
},
"price": {
"amount": "80.00",
"currency": "PLN"
},
"reconciliation": {
"value": {
"amount": "20.00",
"currency": "PLN"
},
"quantity": 1,
"type": "WALLET"
},
"selectedAdditionalServices": [ ],
"boughtAt": "2021-03-15T12:18:33.434Z"
}
],
"surcharges": [],
"discounts": [
{
"type": "ALLEGRO_PRICES"
}
],
"marketplace": {
"id": "allegro-pl"
},
"summary": {
"totalToPay": {
"amount": "80.00",
"currency": "PLN"
}
},
"updatedAt": "2021-03-15T12:18:33.434Z",
"revision": "dc0f896f"
}Gdy w zamówieniu zwróciliśmy w polu lineItems[].reconciliation.type wartość: "BILLING", w odpowiedzi na GET /billing/billing-entries zwrócimy odpowiedni zapis bilingowy, którego wartość w polu id w obiekcie billingEntries[].type to "PS1".
Przykładowe response'y dla różnych sytuacji
Dostawa z odbiorem w punkcie:
"delivery": {
"address": { - adres kupującego
"firstName": "Jan",
"lastName": "Testowy",
"street": "Zielona 900",
"city": "Poznań”,
"zipCode": "62-111",
"countryCode": "PL",
"phoneNumber": "+48 11 1111111"
},
"method": {
"id": "2488f7b7-5d1c-4d65-b85c-4cbcf253fd93", - identyfikator metody dostawy
"name": "Allegro Paczkomaty InPost 24/7" - nazwa metody dostawy
},
"pickupPoint": { - dane punktu odbioru
"id:" “POZ08A”, - identyfikator punktu odbioru
"name": "Paczkomat POZ22A", - nazwa punktu odbioru
"description": "Stacja paliw BP", - opis punktu odbioru (jeśli jest)
"address": { - adres punktu odbioru
"street": "Przybyszewskiego 39A",
“zipCode”:”61-166”,
"city": "Poznań",
"countryCode": "PL"
}
},
"cost": {
"amount": "6.00", - koszt dostawy
"currency": "PLN"
},
"smart": false
},Płatność przy odbiorze:
"payment": {
"id": "2c952542-6967-11e8-b090-8b2d9f391430", - identyfikator płatności
"type": "CASH_ON_DELIVERY", - rodzaj płatności
"provider": null,
"finishedAt": "2019-07-23T12:58:58.609Z", - data przekazania formularza do
realizacji
"paidAmount": null
},Faktura na firmę:
"invoice": {
"required": true,
"address": {
"street": "Zielona 90",
"city": "Poznań",
"zipCode": "62-111",
"countryCode": "PL",
"company":
{
"name": "Nazwa Firmy Sp. z o.o.", - nazwa firmy
"taxId": "525-26-74-798" - numer identyfikacji podatkowej (NIP)
}
}
},Faktury
Jak dodać fakturę do zamówienia
Fakturę dodasz do zamówienia w dwóch krokach - najpierw, za pomocą POST /order/checkout-forms/{id}/invoices utwórz obiekt faktury.
Przykładowy request:
curl -X POST \
'https://api.allegro.pl/order/checkout-forms/a8320af2-5f01-11eb-bbeb-112e13b418c5/invoices' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}' \
-d '{
"file": {
“name”: "faktura.pdf" - wymagane, nazwa pliku
},
"invoiceNumber": "FV 01/2020" - niewymagane, nr faktury
}'Przykładowy response:
{
"id": "56ae349d-8045-4bb3-adcc-7cf6fb420f61" - identyfikator faktury
} Następnie, użyj PUT /order/checkout-forms/{id}/invoices/{invoiceId}/file, aby przesłać plik .pdf z fakturą. Jako “invoice.id” przekaż wartość id, którą otrzymałeś w odpowiedzi dla metody POST. Możesz dodać maksymalnie do 5 faktur do każdego zamówienia. Rozmiar pliku nie może przekroczyć 3 MB.
Przykładowy request:
curl -X PUT \
'https://api.allegro.pl/order/checkout-forms/a8320af2-5f01-11eb-bbeb-112e13b418c5/invoices/56ae349d-8045-4bb3-adcc-7cf6fb420f61/file' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/pdf' \
-H 'Authorization: Bearer {token}' \
-d 'data=@faktura.pdf'Jak pobrać informacje o fakturach dodanych do zamówienia
Aby pobrać informacje o fakturach dodanych do zamówienia, skorzystaj z GET /order/checkout-forms/{id}/invoices.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/order/checkout-forms/a8320af2-5f01-11eb-bbeb-112e13b418c5/invoices' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}'Przykładowy response:
{
"invoices": [
{
"id": "56ae349d-8045-4bb3-adcc-7cf6fb420f61", - identyfikator faktury
"invoiceNumber": "FV 01/2020", - nr faktury
"createdAt": "2021-01-07T15:50:00.000Z", - data dodania faktury
"file": {
"name": "faktura.pdf", - nazwa pliku
"uploadedAt": "2021-01-07T15:50:00.000Z", - data dodania pliku
"securityVerification": {
"status": "ACCEPTED", - status weryfikacji antywirusowej pliku,
dostępne wartości: WAITING, ACCEPTED,
REJECTED
"verifiedAt": "2021-01-07T15:51:00.000Z" - data weryfikacji
}
}
}
],
"hasExternalInvoices": false - czy faktura została wysłana
poza Allegro
} Obsługa przesyłek
Jak dodać numer przesyłki do przedmiotu w zamówieniu
Za pomocą POST /order/checkout-forms/{id}/shipments możesz dodać numer przesyłki do zamówienia. Jeżeli nie przekażesz w żądaniu kolejnych lineItem.id to numer przesyłki automatycznie przypiszemy do każdego lineItem.id z zamówienia.
Przykładowy request:
curl -X POST \
'https://api.allegro.pl/order/checkout-forms/31896452-2de1-11e9-bced-352ab82ad9cd/shipments' \
-H 'Authorization: Bearer {token}' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-d '{
"carrierId": "DHL", - wymagane, identyfikatory dostępnych przewoźników
otrzymasz przy pomocy zasobu GET /order/carriers
w polu carriers.id
"waybill": "12345678910PL", - wymagane, numer przesyłki
"carrierName": null, - wymagane tylko w przypadku
wartości “OTHER” w polu carrierId.
Nazwa przewoźnika spoza listy.
"lineItems": [ - niewymagane, lista id przedmiotów z zamówienia,
które będą w paczce
{
"id": "31896450-2de1-11e9-bced-352ab82ad9cd"
},
{
"id": "5b1f4a62-6969-11e8-b090-8b2d9f391430"
}
]
}'Przykładowy response:
{
"waybill": "12345678910PL",
"carrierId": "DHL",
"carrierName": null,
"lineItems": [
{
"id": "31896450-2de1-11e9-bced-352ab82ad9cd"
},
{
"id": "5b1f4a62-6969-11e8-b090-8b2d9f391430"
}
],
"createdAt": "2019-02-18T11:46:48.264Z", - data dodania numeru przesyłki
do zamówienia
"id": "REhMOjEyMzQ1Njc4OTEwUEw=" - identyfikator przesyłki
}Jak pobrać numery przesyłek dodane do zamówienia
Aby pobrać dodane numery przesyłek, skorzystaj z GET /order/checkout-forms/{id}/shipments. CheckoutForm.id pobierzesz zasobami do obsługi zamówień.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/order/checkout-forms/31896452-2de1-11e9-bced-352ab82ad9cd/shipments' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json'Przykładowy response:
{
"shipments": [ - lista przesyłek
{
"waybill": "12345678910PL", - numer przesyłki
"carrierId": "DHL", - identyfikator przewoźnika
"lineItems": [ - lista id przedmiotów, które
znajdują się w paczce
{
"id": "ed6b4380-3108-11e9-96bc-5f220d078cf7"
}
],
"createdAt": "2019-02-18T12:07:03.353Z", - data dodania numeru przesyłki do
zamówienia
"id": "REhMOjEyMzQ1Njc4OTEwUEw=" - identyfikator przesyłki
},
},
{
"waybill": "25825896-32343-55",
"carrierId": "OTHER",
"carrierName": "Kurier_express",
"lineItems": [
{
"id": "ed6b4380-3108-11e9-96bc-5f220d078cf7"
}
],
"createdAt": "2019-02-26T07:13:08.585Z",
"id": "T1RIRVI6MjU4MjU4OTYtMzIzNDNfaW5uYQ=="
}
]
}Jak pobrać historię statusów przesyłek
Za pomocą GET /order/carriers/{carrierId}/tracking?waybill={waybill} pobierzesz historię statusów wskazanych przesyłek. Jako {carrierId} wskaż ID wybranego przewoźnika (dostępne wartości sprawdzisz w odpowiedzi dla GET /shipment-management/delivery-services), a jako waybill przekaż numer przesyłki, który otrzymasz w odpowiedzi dla GET /shipment-management/shipments/{shipmentId} w polu “packages.waybill”.
Możesz przekazać więcej niż jeden numer, maksymalnie 20, np. GET /order/carriers/{carrierId}/tracking?waybill=waybill1&waybill=waybill2&waybill=waybill3.
Możliwe statusy przesyłek to:
- PENDING - przesyłka została przygotowana przez nadawcę, oczekuje na nadanie;
- IN_TRANSIT - w drodze. Status obejmuje zdarzenia takie jak:
- nadanie przesyłki w punkcie,
- odebranie jej przez kuriera,
- przyjęcie na sortownie,
- przekierowanie do innego punktu.
- RELEASED_FOR_DELIVERY - w trakcie doręczenia przez kuriera (na adres odbiorcy lub do punktu odbioru);
- AVAILABLE_FOR_PICKUP - oczekuje na odbiór w punkcie;
- NOTICE_LEFT - kurier wystawił awizo, przesyłka będzie do odbioru pod adresem podanym na awizo;
- ISSUE - wystąpił problem z przesyłką. Status obejmuje zdarzenia takie jak:
- odmowa przyjęcia przesyłki,
- zagubienie przesyłki.
- DELIVERED - przesyłka została doręczona do odbiorcy lub odebrana z punktu odbioru;
- RETURNED - przesyłka została zwrócona do nadawcy.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/order/carriers/{carrierId}/tracking?waybill=ALE0000000E5D200' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' Kliknij, aby zobaczyć response
{
"carrierId": "ALLEGRO", -- ID przewoźnika
"waybills": [ -- informacje o statusach dla
poszczególnych przesyłek
{
"waybill": "ALE0000000E5D200", -- numer listu przewozowego
"trackingDetails": { -- informacje o statusach przesyłki.
Przyjmuje wartość null, w przypadku, gdy
waybill nie został rozpoznany w systemie
(np. z powodu braku zarejestrowanego
jakiegokolwiek statusu albo dotyczy paczki
sprzed ponad 60 dni)
"statuses": [ -- lista statusów
{
"occurredAt": "2021-01-22T11:30:21.092Z", -- czas wystąpienia zdarzenia
"code": "PENDING" -- status przesyłki
}, {
"occurredAt": "2021-01-22T11:30:34.710Z",
"code": "IN_TRANSIT"
}, {
"occurredAt": "2021-01-24T08:33:27.219Z",
"code": "ISSUE",
"description": "Possible delay in delivery" -- opcjonalny opis dla danego statusu
}, {
"occurredAt": "2021-01-24T16:11:31.829Z",
"code": "AVAILABLE_FOR_PICKUP"
}, {
"occurredAt": "2021-01-25T11:35:01.859Z",
"code": "DELIVERED"
}
],
"createdAt": "2021-01-22T11:30:22.163Z", -- czas rozpoczęcia rejestrowania
trackingu przesyłki
"updatedAt": "2021-01-25T11:36:02.217Z" -- czas zarejestrowania ostatniej zmiany
w trackingu przesyłki
}
}
]
}
Zwroty klienckie
Jak pobrać listę zwrotów
Za pomocą GET /order/customer-returns pobierzesz listę zwrotów klienckich dostępnych na twoim koncie. Domyślnie zwrócimy 100 rekordów. Możesz również pobrać listę zwrotów dostosowaną do twoich potrzeb, używając parametrów:
- limit - określ liczbę zwrotów, jaką mamy zwrócić w odpowiedzi (przyjmuje wartości od 1 do 1000),
- offset - wskaż miejsce, od którego chcesz pobrać kolejną porcję danych (przyjmuje wartości od 0 do 1000).
Udostępniliśmy także filtry, które pozwolą ci sprecyzować otrzymane wyniki:
- customerReturnId - identyfikator zwrotu,
- referenceNumber - numer zwrotu,
- orderId - identyfikator zamówienia,
- buyer.email - adres email kupującego,
- buyer.login - login kupującego,
- items.offerId - numer oferty,
- items.name - tytuł oferty,
- parcels.waybill - numer listu przewozowego,
- parcels.carrierId - nazwa przewoźnika,
- parcels.sender.phoneNumber - numer telefonu nadawcy przesyłki zwrotnej,
- from - identyfikator ostatnio pobranego zwrotu,
- createdAt.gte - najwcześniejsza data utworzenia zwrotu,
- createdAt.lte - najpóźniejsza data utworzenia zwrotu,
- marketplaceId - identyfikator serwisu związanego z danym zwrotem,
- status - status zwrotu.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/order/customer-returns' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.beta.v1+json' Kliknij, aby zobaczyć response
{
"count": 2, - łączna liczba zwrotów
"customerReturns": [
{
"id": "8228462e-dc5f-4cae-80f6-88b320b2565a", - identyfikator zwrotu
"createdAt": "2021-07-08T12:13:53.464Z", - data utworzenia zwrotu
"referenceNumber": "XGQX/2021", - numer zwrotu
"orderId": "4a0a6511-dfd7-11eb-b6c4-d37454079c02", - identyfikator zamówienia
"buyer": {
"email": "xp8f9zypt5@allegro.pl", - adres email kupującego
"login": "Client:44300636" - login kupującego
},
"items": [ - lista zwracanych przedmiotów
{
"offerId": "7680560740", - numer oferty
"quantity": 1, - liczba sztuk
"name": "Apple iPhone 12 Pro pacyfic blue 128 GB", - tytuł oferty
"price": {
"amount": "1234", - cena jednostkowa
"currency": "PLN"
},
"url": "https://allegro.pl/oferta/apple-iphone-12-pro-pacyfic-blue-128-gb-7680560740?snapshot=MjAyMS0wNy0wOFQxMDoyOToyNS44O", - snapshot oferty z momentu sprzedaży
"reason": {
"type": "NOT_AS_DESCRIBED", - powód zwrotu
"userComment": "Niewłaściwy kolor." - komentarz kupującego
}
}
],
"refund": { - dane do zwrotu wpłaty
"bankAccount": {
"owner": "Adam Adamowski", - imię i nazwisko
"accountNumber": "90051670524612733466440893", - numer rachunku
"iban": "PL90051670524612733466440893", - numer iban
"swift": "ALBPPLPW", - kod swift tylko dla zagranicznych numerów konta
"address": { - adres
"street": "Grunwaldzka 182",
"city": "Poznań",
"postCode": "60-166",
"countryCode": "PL"
}
}
},
"rejection": null, - powód odmowy zwrotu wpłaty
"parcels": [ - dane przesyłki zwrotnej
{
"createdAt": "2021-07-08T12:13:59.001Z", - data utworzenia przesyłki
"waybill": null, - numer listu przewozowego
"carrierId": null, - nazwa przewoźnika
"sender": {
"phoneNumber": "+48600600600" - numer telefonu nadawcy
}
}
],
"marketplaceId": "allegro-pl" - identyfikator serwisu związanego z danym zwrotem
"status": "DELIVERED" - status zwrotu (zwracane wartości:
CREATED, IN_TRANSIT, DELIVERED,
FINISHED, FINISHED_APT, REJECTED,
COMMISSION_REFUND_CLAIMED,
COMMISSION_REFUNDED,
WAREHOUSE_DELIVERED,
WAREHOUSE_VERIFICATION).
},
{
"id": "4fb9ad4a-a19b-4c08-a6f1-895cb8741258",
"createdAt": "2021-07-08T12:19:47.132Z",
"referenceNumber": "XNLX/2021",
"orderId": "aef2baa1-dfe5-11eb-b6c4-d37454079c02",
"buyer": {
"email": "xp8f9zypt7@allegro.pl",
"login": "Client:44300637"
},
"items": [
{
"offerId": "7680560740",
"quantity": 2,
"name": "Apple iPhone 12 Pro pacyfic blue 128 GB",
"price": {
"amount": "11",
"currency": "PLN"
},
"url": "https://allegro.pl/oferta/apple-iphone-12-pro-pacyfic-blue-128-gb-7680560740?snapshot=MjAyMS0wNy0wOFQxMjoxMjoxNS4wMzNaO2J1eW",
"reason": {
"type": "NONE",
"userComment": ""
}
}
],
"refund": {
"bankAccount": {
"owner": "Jan Kowalski",
"accountNumber": "90051670524612733466440893",
"iban": "PL90051670524612733466440893",
"swift": "ALBPPLPW",
"address": {
"street": "Grunwaldzka 182",
"city": "Poznań",
"postCode": "60-166",
"countryCode": "PL"
}
}
},
"rejection": null,
"parcels": [
{
"createdAt": "2021-07-08T12:19:48.838Z",
"waybill": null,
"truckingWaybill": null,
"carrierId": null,
"truckingCarrierId": null,
"sender": {
"phoneNumber": "+48777888999"
}
}
]
}
],
"marketplaceId": "allegro-pl",
"status": "DELIVERED"
}Jak pobrać szczegółowe informacje o zwrocie
Skorzystaj z GET /order/customer-returns/{customerReturnId}, aby pobrać szczegółowe dane wybranego zwrotu.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/order/customer-returns/8228462e-dc5f-4cae-80f6-88b320b2565a' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.beta.v1+json' Kliknij, aby zobaczyć response
{
"id": "8228462e-dc5f-4cae-80f6-88b320b2565a", - identyfikator zwrotu
"createdAt": "2021-07-08T12:13:53.464Z", - data utworzenia zwrotu
"referenceNumber": "XGQX/2021", - numer zwrotu
"orderId": "4a0a6511-dfd7-11eb-b6c4-d37454079c02", - identyfikator zamówienia
"buyer": {
"email": "xp8f9zypt5@allegro.pl", - adres email kupującego
"login": "Client:44300636" - login kupującego
},
"items": [ - lista zwracanych przedmiotów
{
"offerId": "7680560740", - numer oferty
"quantity": 1, - liczba sztuk
"name": "Apple iPhone 12 Pro pacyfic blue 128 GB", - tytuł oferty
"price": {
"amount": "1234", - cena jednostkowa
"currency": "PLN"
},
"url": "https://allegro.pl/oferta/apple-iphone-12-pro-pacyfic-blue-128-gb-7680560740?snapshot=MjAyMS0wNy0wOFQxMDoyOToyNS44O", - snapshot oferty z momentu sprzedaży
"reason": {
"type": "NOT_AS_DESCRIBED", - powód zwrotu
"userComment": "Niewłaściwy kolor." - komentarz kupującego
}
}
],
"refund": { - dane do zwrotu wpłaty
"bankAccount": {
"owner": "Adam Adamowski", - imię i nazwisko
"accountNumber": "90051670524612733466440893", - numer rachunku
"iban": "PL90051670524612733466440893", - numer iban
"swift": "ALBPPLPW", - kod swift tylko dla zagranicznych numerów konta
"address": { - adres
"street": "Grunwaldzka 182",
"city": "Poznań",
"postCode": "60-166",
"countryCode": "PL"
}
}
},
"rejection": null, - powód odmowy zwrotu wpłaty
"parcels": [ - dane przesyłki zwrotnej
{
"createdAt": "2021-07-08T12:13:59.001Z", - data utworzenia przesyłki
"waybill": null, - numer listu przewozowego
"truckingWaybill": null, - numer listu przewozowego od przewoźnika fizycznie dostarczającego paczkę, jeśli jest inny niż w "waybill", w innym wypadku zwrócimy null
"carrierId": null, - nazwa przewoźnika
"truckingCarrierId": null, - nazwa przewoźnika fizycznie dostarczającego paczkę, jeśli jest inny niż w "carrierId", w innym wypadku zwrócimy null
"sender": {
"phoneNumber": "+48600600600" - numer telefonu nadawcy
}
}
],
"marketplaceId": "allegro-pl", - identyfikator serwisu związanego z danym zwrotem
"status": "DELIVERED" - status zwrotu
}Jak odmówić zwrotu wpłaty
Skorzystaj z POST /order/customer-returns/{customerReturnId}/rejection, aby odmówić zwrotu wpłaty. W polu “rejection.code” przekaż jedną z poniższych wartości:
- REFUND_REJECTED - zwrot został odrzucony,
- NEW_ITEM_SENT - nowy towar został już wysłany,
- ITEM_FIXED - towar został naprawiony,
- MISSING_PART_SENT - brakująca część została wysłana.
Jeśli w polu “rejection.code” przekażesz wartość REFUND_REJECTED - w polu "rejection.reason" uzasadnij odmowę zwrotu środków.
Przykładowy request:
curl -X POST \
'https://api.allegro.pl/order/customer-returns/8228462e-dc5f-4cae-80f6-88b320b2565a/rejection' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.beta.v1+json' \
-H 'Content-Type: application/vnd.allegro.beta.v1+json' \
-d '{
"rejection": {
"reason": "Przedmiot jest uszkodzony.",
“code”: “REFUND_REJECTED”
}
}' Kliknij, aby zobaczyć response
{
"id": "8228462e-dc5f-4cae-80f6-88b320b2565a", - identyfikator zwrotu
"createdAt": "2021-07-08T12:13:53.464Z", - data utworzenia zwrotu
"referenceNumber": "XGQX/2021", - numer zwrotu
"orderId": "4a0a6511-dfd7-11eb-b6c4-d37454079c02", - identyfikator zamówienia
"buyer": {
"email": "xp8f9zypt5@allegro.pl", - adres email kupującego
"login": "Client:44300636" - login kupującego
},
"items": [ - lista zwracanych przedmiotów
{
"offerId": "7680560740", - numer oferty
"quantity": 1, - liczba sztuk
"name": "Apple iPhone 12 Pro pacyfic blue 128 GB", - tytuł oferty
"price": {
"amount": "1234", - cena jednostkowa
"currency": "PLN"
},
"url": "https://allegro.pl/oferta/apple-iphone-12-pro-pacyfic-blue-128-gb-7680560740?snapshot=MjAyMS0wNy0wOFQxMDoyOToyNS44O", - snapshot oferty z momentu sprzedaży
"reason": {
"type": "NOT_AS_DESCRIBED", - powód zwrotu
"userComment": "Niewłaściwy kolor." - komentarz kupującego
}
}
],
"refund": { - dane do zwrotu wpłaty
"bankAccount": {
"owner": "Adam Adamowski", - imię i nazwisko
"accountNumber": "90051670524612733466440893", - numer rachunku
"iban": "PL90051670524612733466440893", - numer iban
"swift": "ALBPPLPW", - kod swift tylko dla zagranicznych numerów konta
"address": { - adres
"street": "Grunwaldzka 182",
"city": "Poznań",
"postCode": "60-166",
"countryCode": "PL"
}
}
},
"rejection": {
“reason”: “Przedmiot jest uszkodzony.”, - powód odmowy zwrotu wpłaty
“code”: “REFUND_REJECTED”, - opcja odmowy zwrotu wpłaty,
przyjmuje wartości:
"REFUND_REJECTED",
"NEW_ITEM_SENT", "ITEM_FIXED",
"MISSING_PART_SENT"
“createdAt”: "2021-07-27T11:34:42.499Z" - data odmowy
},
"parcels": [ - dane przesyłki zwrotnej
{
"createdAt": "2021-07-08T12:13:59.001Z", - data utworzenia przesyłki
"waybill": null, - numer listu przewozowego
"truckingWaybill": null, - numer listu przewozowego od przewoźnika fizycznie dostarczającego paczkę, jeśli jest inny niż w "waybill", w innym wypadku zwrócimy null
"carrierId": null, - nazwa przewoźnika
"truckingCarrierId": null, - nazwa przewoźnika fizycznie dostarczającego paczkę, jeśli jest inny niż w "carrierId", w innym wypadku zwrócimy null
"carrierId": null, - nazwa przewoźnika
"sender": {
"phoneNumber": "+48600600600" - numer telefonu nadawcy
}
}
],
"marketplaceId": "allegro-pl" - identyfikator serwisu związanego z danym zwrotem.
}Zwroty płatności
Jak wykonać zwrot płatności
Aby zrealizować zwrot płatności, skorzystaj z POST /payments/refunds.
Opcjonalnie możesz również przekazać w polu "sellerComment" komentarz uzasadniający zwrot środków. Kupujący otrzyma ten komentarz w wiadomości potwierdzającej zlecenie zwrotu.
Jeśli chcesz wykonać zwrot płatności za przedmiot, masz do wyboru dwie możliwości, które możesz przekazać jako wartość pola lineItems.type:
- QUANTITY - zwrot według liczby sztuk. W polu “quantity” przekaż jako wartość liczbę przedmiotów, za które chcesz wykonać zwrot płatności,
- AMOUNT - zwrot określonej kwoty, możesz zwrócić część kwoty sprzedanego przedmiotu.
Przykładowe wywołania:
- Zwrot płatności za produkt według liczby sztuk, dostawę, nadpłatę, dopłatę i dodatkowe usługi:
Kliknij, aby zobaczyć request
curl -X POST \
'https://api.allegro.pl/payments/refunds' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d '{
"payment": {
"id": "a6bee8b2-8b4e-11e9-8918-07b31163120a" - wymagane, id płatności kupującego
},
"reason": "REFUND", - wymagane, powód zwrotu, dostępne
wartości: REFUND (zwrot), COMPLAINT
(reklamacja), PRODUCT_NOT_AVAILABLE
(produkt niedostępny), PAID_VALUE_TOO_LOW
(za niska wpłata od kupującego), OVERPAID (zwrot nadpłaty),
CANCELLED_BY_BUYER (anulowanie przez kupującego),
NOT_COLLECTED (nieodebrane zamówienie)
"lineItems": [ - niewymagane, lista przedmiotów,
dla których chcesz zlecić zwrot
płatności
{
"id": "09f0b4cc-7880-11e9-8f9e-2a86e4085a59", - id przedmiotu,wchodzącego
w skład zamówienia, za który chcesz
zwrócić płatność, lineItem.id
pobierzesz za pomocą
GET order/checkout-forms
"type": "QUANTITY", - rodzaj zwrotu płatności za produkt,
dostępne wartości:
QUANTITY (zwrot za sztuki) lub AMOUNT
(zwrot określonej kwoty)
“quantity”: 1 - liczba sztuk, za którą chcesz
zwrócić płatność
}
],
"delivery": { - niewymagane, zwrot
płatności za koszty wysyłki
"value": {
"amount": "123.45", - kwota, jaką chcesz zwrócić
za koszty wysyłki
"currency": "PLN"
}
},
"overpaid": { - niewymagane, zwrot płatności za nadpłatę
"value": {
"amount": "123.45", - kwota, jaką chcesz zwrócić z nadpłaty
"currency": "PLN"
}
},
"surcharges": [ - niewymagane, zwrot płatności za dopłatę
{
"id": "09f0b4cc-7880-11e9-8f9e-2a86e4085a59", - wymagane, jeśli zwracasz dopłatę,
surcharge.id, pobierzesz za pomocą
GET /order/checkout-forms
"value": {
"amount": "123.45", - kwota, jaką chcesz zwrócić z dopłaty
"currency": "PLN"
}
}
],
"additionalServices": { - niewymagane, zwrot płatności za dodatkowe
usługi
"value": {
"amount": "123.45", - kwota, jaką chcesz zwrócić za dodatkowe
usługi
"currency": "PLN"
}
}
"sellerComment": "Przesyłka zwrócona" - opcjonalny komentarz uzasadniający
zwrot środków
}' Kliknij, aby zobaczyć response
{
"id": "09f0b4cc-7880-11e9-8f9e-2a86e4085a59", - id zwrotu płatności
"payment": {
"id": "a6bee8b2-8b4e-11e9-8918-07b31163120a" - id płatności kupującego, której
dotyczy zwrot
},
"reason": "REFUND",
"status": "NEW", - aktualny status zwrotu płatności
"createdAt": "2017-05-17T08:36:57.292+02:00", - data zlecenia zwrotu
"totalValue": { - kwota do zwrotu
"amount": "123.45",
"currency": "PLN"
},
"lineItems": [ - lista przedmiotów, których dotyczy
zwrot płatności
{
"id": "09f0b4cc-7880-11e9-8f9e-2a86e4085a59",
"type": "QUANTITY",
"quantity": 1,
}
],
"delivery": {
"value": {
"amount": "123.45",
"currency": "PLN"
}
},
"overpaid": {
"value": {
"amount": "123.45",
"currency": "PLN"
}
},
"surcharges": [
{
"id": "09f0b4cc-7880-11e9-8f9e-2a86e4085a59",
"value": {
"amount": "123.45",
"currency": "PLN"
}
}
],
"additionalServices": {
"value": {
"amount": "123.45",
"currency": "PLN"
}
}
} Kliknij, aby zobaczyć request
curl -X POST \
‘https://api.allegro.pl/payments/refunds’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d ‘{
"payment": {
"id": "a6bee8b2-8b4e-11e9-8918-07b31163120a"
},
"reason": "REFUND",
"lineItems": [
{
"id": "03ec68f0-9d6a-11e9-8f47-458978ef2120",
"type": "AMOUNT",
"value": {
"amount": "100.00",
"currency": "PLN"
}
}
]
}Jak pobrać listę zwrotów płatności
Jeśli chcesz pobrać listę wykonanych zwrotów płatności, skorzystaj z GET /payments/refunds. Domyślnie otrzymasz listę 50 najnowszych zwrotów płatności.
Aby dostosować listę do swoich potrzeb, możesz skorzystać z parametrów:
- limit - określ liczbę zwrotów płatności, jaką chcesz otrzymać w odpowiedzi,
offset - wskaż miejsce, od którego chcesz pobrać następną porcję danych.
np. GET /payments/refunds?limit=50&offset=25 zwróci 50 zwrotów płatności od wybranego punktu.
Możesz także skorzystać z filtrów:
- identyfikator zwrotu płatności - np. GET /payments/refunds?id=09f0b4cc-7880-11e9-8f9e-2a86e4085a59;
- identyfikator płatności kupującego - np. GET /payments/refunds?payment.id=a6bee8b2-8b4e-11e9-8918-07b31163120a;
- data zwrotu płatności - możesz wyfiltrować zwrot płatności po dacie, używając parametrów occurredAt.gte (najwcześniejsza data wystąpienia zwrotu płatności w formacie ISO 8601) i occurredAt.lte (najpóźniejsza data wystąpienia zwrotu płatności w formacie ISO 8601), np. GET/payments/refunds?occurredAt.gte=2019-07-10T11:06:50.935Z&occurredAt.lte=2019-07-15T11:06:50.935Z;
- status np. GET /payments/refunds?status=SUCCESS.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/payments/refunds' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' Kliknij, aby zobaczyć response
{
"refunds": [
{
"id": "09f0b4cc-7880-11e9-8f9e-2a86e4085a59", - id zwrotu płatności
"payment": {
"id": "a6bee8b2-8b4e-11e9-8918-07b31163120a" - id płatności kupującego
},
"reason": "REFUND", - powód zwrotu płatności
"status": "SUCCESS", - aktualny status zwrotu
płatności,przyjmowane wartości:
WAITING (oczekujące, próbujemy
pobrać z salda środki na zwrot),
IN_PROGRESS (w realizacji,
pobraliśmy środki z salda
i przekazaliśmy zlecenie zwrotu
do operatora), SUCCESS
(środki zwrócone, trafiły
do kupującego), CANCELLED
(nie udało się pobrać środków
z salda lub wystąpił błąd po
stronie operatora), PARTIAL
(częściowe, dotyczy zwrotów do
dwóch operatorów, np. udał się
zwrot za przedmiot zakupiony
przez PAYU, ale nie udał się
zwrot za dopłatę przez P24)
"createdAt": "2017-05-17T08:36:57.292+02:00", - data utworzenia zwrotu płatności
"totalValue": { - kwota do zwrotu
"amount": "123.45",
"currency": "PLN"
},
"lineItems": [ - lista przedmiotów, dla
których został wykonany zwrot
{
"id": "09f0b4cc-7880-11e9-8f9e-2a86e4085a59",
"type": "QUANTITY",
"quantity": 5,
"value": null
}
],
"delivery": { - informacja o zwrocie za dostawę
"value": {
"amount": "123.45",
"currency": "PLN"
}
},
"overpaid": { - informacja o zwrocie za nadpłatę
"value": {
"amount": "123.45",
"currency": "PLN"
}
},
"surcharges": [ - informacja o zwrocie za dopłatę
{
"id": "09f0b4cc-7880-11e9-8f9e-2a86e4085a59", - identyfikator dopłaty
"value": {
"amount": "123.45",
"currency": "PLN"
}
}
],
"additionalServices": { - informacja o zwrocie za
dodatkowe usługi
"value": {
"amount": "123.45",
"currency": "PLN"
}
}
}
],
"count": 50, - ilość wyświetlanych wyników
"totalCount": 123 - całkowita ilość wykonanych
zwrotów płatności
}
Rabaty transakcyjne (zwroty prowizji)
Jak utworzyć wniosek o rabat transakcyjny
Aby utworzyć wniosek o rabat transakcyjny (zwrot prowizji), skorzystaj z POST /order/refund-claims.
Przez REST API możesz utworzyć wniosek dla prowizji, które pobraliśmy w ciągu ostatnich 45 dni.
W strukturze żądania przekaż wymagane pola:
- lineItem.id - identyfikator przedmiotu z zamówienia, za który chcesz otrzymać rabat transakcyjny. Pobierzesz go za pomocą GET /order/checkout-forms/{id},
- quantity - liczba przedmiotów z zamówienia, za którą chcesz otrzymać rabat transakcyjny.
Przykładowy request:
curl -X POST \
'https://api.allegro.pl/order/refund-claims' \
-H 'Authorization: Bearer {token}' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-d '{
"lineItem": {
"id": "15f8e350-5252-11ea-875e-a14b8f6a3728"
},
"quantity": 1
}'Przykładowy response:
{
"id": "c5ed3e8c-b37b-4379-892b-4e9bbd8de416" - identyfikator wniosku o rabat
transakcyjny. Aby poznać więcej
szczegółów, np. aktualny status
wniosku, przekaż ten identyfikator
jako claimId w
GET /order/refund-claims/{claimId}.
}’Jak pobrać listę utworzonych wniosków o rabat transakcyjny
Za pomocą GET /order/refund-claims pobierzesz listę utworzonych wniosków. Domyślnie w odpowiedzi otrzymasz 25 wniosków, gdzie pierwszy wynik jest najnowszym. Aby dostosować listę do swoich potrzeb, możesz skorzystać z parametrów:
- limit - określ liczbę wniosków, jaką chcesz otrzymać w odpowiedzi. Maksymalna wartość to 100.
- offset - wskaż miejsce, od którego chcesz pobrać następną porcję danych.
Możesz także skorzystać z filtrów:
- identyfikator oferty - np. GET order/refund-claims?lineItem.offer.id=6206823161 zwróci wnioski, które są powiązane z ofertą 6206823161,
- login kupującego - np. GET order/refund-claims?buyer.login=example_login zwróci wnioski, które dotyczą wskazanego kupującego,
- status wniosku - np. GET order/refund-claims?status=REJECTED zwróci odrzucone wnioski. Listę wszystkich statusów znajdziesz w naszej dokumentacji.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/order/refund-claims' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' Kliknij, aby zobaczyć response
{
"refundClaims": [
{
"id": "c5ed3e8c-b37b-4379-892b-4e9bbd8de416", - identyfikator wniosku o
rabat transakcyjny
"status": "REJECTED", - aktualny status wniosku
"quantity": 1, - liczba sztuk przedmiotu,
dla której wystąpiono o rabat
transakcyjny
"commission": {
"amount": 0.60, - kwota prowizji od
sprzedaży
"currency": "PLN" - waluta
},
"buyer": {
"id": "441827210", - identyfikator kupującego
"login": "testowy_login" - login kupującego
},
"createdAt": "2020-03-02T14:27:20.560Z", - data utworzenia wniosku
"type": "MANUAL", - rodzaj złożonego wniosku,
dostępne wartości: MANUAL (wniosek
złożony ręcznie przez sprzedającego),
AUTOMATIC (wniosek złożony automatycznie).
"lineItem": {
"id": "2035a9e0-3c66-11ea-9902-0b71080f41e0", - identyfikator przedmiotu z
zamówienia, za który chcesz
otrzymać rabat transakcyjny
"quantity": 3, - liczba przedmiotów w
zamówieniu
"boughtAt": "2020-01-21T15:53:17.829Z", - data zakupu
"offer": {
"id": "6216558337", - identyfikator oferty
"name": "oferta testowa" - tytuł oferty
}
}
},
{
"id": "17f69337-a5bc-44d1-bc5d-4ad2a6b9ce0d",
"status": "GRANTED",
"quantity": 1,
"commission": {
"amount": 0.05,
"currency": "PLN"
},
"buyer": {
"id": "441827210",
"login": "testowy_login"
},
"createdAt": "2020-03-02T13:20:27.523Z",
"type": "MANUAL",
"lineItem": {
"id": "ad727280-5961-11ea-9e7e-ef3e4a9eb4c3",
"quantity": 1,
"boughtAt": "2020-02-27T13:04:31.952Z",
"offer": {
"id": "6206857553",
"name": "oferta testowa"
}
}
}
],
"count": 2 - liczba dostępnych wniosków
o rabat transakcyjny
}’Jak pobrać pojedynczy wniosek o rabat transakcyjny
Za pomocą GET /order/refund-claims/{claimId} pobierzesz dane pojedynczego wniosku, który wskazałeś w żądaniu.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/order/refund-claims/17f69337-a5bc-44d1-bc5d-4ad2a6b9ce0d' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json'Przykładowy response:
{
"id": "17f69337-a5bc-44d1-bc5d-4ad2a6b9ce0d",
"status": "GRANTED",
"quantity": 1,
"commission": {
"amount": 0.05,
"currency": "PLN"
},
"buyer": {
"id": "441827210",
"login": "testowy_login"
},
"createdAt": "2020-03-02T13:20:27.523Z",
"type": "MANUAL",
"lineItem": {
"id": "ad727280-5961-11ea-9e7e-ef3e4a9eb4c3",
"quantity": 1,
"boughtAt": "2020-02-27T13:04:31.952Z",
"offer": {
"id": "6206857553",
"name": "oferta testowa"
}
}
}Jak anulować wniosek o rabat transakcyjny
Za pomocą DELETE /order/refund-claims/{claimId} anulujesz wniosek o rabat transakcyjny przekazany w żądaniu. Możesz anulować wnioski tylko w statusie IN_PROGRESS i APPEALED, w pozostałych przypadkach zwrócimy błąd 422.
Sandbox
Aby w pełni korzystać z opisanych zasobów na środowisku testowym (Allegro Sandbox):
- Zarejestruj dwa konta:
- firmowe (na którym wystawisz przedmioty na sprzedaż) - uzupełnij dane adresowe i aktywuj konto,
- zwykłe (z którego dokonasz zakupów jako klient) - uzupełnij dane adresowe i aktywuj konto.
- Zweryfikuj konto firmowe.
- Z konta sprzedającego wystaw ofertę na Sandbox - możesz to zrobić poprzez formularz lub API.
- Zaloguj się na konto kupującego i wejdź na stronę wybranej oferty:
- dodaj przedmiot do koszyka lub skorzystaj z Kup Teraz,
- uzupełnij adres dostawy, wybierz metodę dostawy oraz płatności,
- kliknij Kupuję i płacę (na Sandbox dostępny jest symulator płatności tzn. nie musisz dokonywać realnej zapłaty).
- Jako sprzedający otrzymane zamówienia sprawdzisz w zakładce Zamówienia lub poprzez API.
Podstawowe informacje o środowisku testowym znajdziesz w naszym poradniku.
FAQ
W dzienniku zdarzeń otrzymałem event FILLED_IN z konkretnym numerem zamówienia. Kiedy przekazuję ten numer w GET /order/checkout-forms/{id} w odpowiedzi otrzymuję status 404 z informacją, że nie znaleziono takiego zamówienia. Co się z nim z stało?
Kupujący najprawdopodobniej wykonał oddzielne zakupy, a następnie łącznie je opłacił. Otrzymasz nowy event z nowym numerem zamówienia, a stare usuniemy. Aby zidentyfikować taką sytuację możesz oprzeć się na pojedynczym akcie zakupowym - lineItem.id (jeżeli jeden lineItem.id występuje w kilku zamówieniach oznacza to, że mamy do czynienia z połączeniem zakupów przez kupującego).
Otrzymałem zdarzenie READY_FOR_PROCESSING, więc przechodzę do procesowania zamówienia. Jak mogę rozpoznać, czy w miedzyczasie kupujący nie anulował zamówienia?
Gdy zmieniasz status realizacji zamówienia za pomocą PUT /order/checkout-forms/{id}/fulfillment, wykorzystaj dodatkowy parametr checkoutForm.revision, który otrzymasz w odpowiedzi dla:
Zwracamy w nim informację o wersji zamówienia. Dzięki niemu będziesz pewien, że zmieniasz status realizacji zamówienia (“fulfillment.status”), którego dokładnie ta sama kopia znajduje się w Allegro.
np. PUT /order/checkout-forms/29738e61-7f6a-11e8-ac45-09db60ede9d6/fulfillment?checkoutForm.revision={revision}’
Czy jeśli dodam numer przesyłki za pomocą POST /order/checkout-forms/{id}/shipments status realizacji [zamówienia](https://allegro.pl/moje-allegro/sprzedaz/zamowienia/) (“fulfillment.status”) zmieni się automatycznie na SENT?
Status realizacji zamówienia zmieni się automatycznie, tylko wtedy, gdy sprzedawca korzysta z abonamentu i zaznaczy taką opcję w ustawieniach w zakładce Zamówienia. W pozostałych przypadkach musisz to wykonać ręcznie za pomocą PUT /order/checkout-forms/{id}/fulfillment.
Jak mogę wyfiltrować zamówienia, do których przypisałem numery przesyłek, a do których nie?
Skorzystaj w tym celu z parametru fulfillment.shipmentSummary.lineItemsSent. Znajdziesz w nim informację, czy do przedmiotów w zamówieniu dołączono numery przesyłek. Dostępne wartości określają przypisane numery przesyłek do:
- ALL - wszystkich przedmiotów w zamówieniu,
- SOME - przynajmniej jednego przedmiotu z zamówienia. Za pomocą GET /order/checkout-forms/{id}/shipments sprawdzisz przedmioty, do których dodałeś już numer.
- NONE - żadnego przedmiotu z zamówienia,
np. GET /order/checkout-forms?fulfillment.shipmentSummary.lineItemsSent=ALL - zwróci zamówienia, gdzie dla wszystkich przedmiotów, które wchodzą w jego skład, dodano numer przesyłki.
Lista zasobów
Pełną dokumentację zasobów w postaci pliku swagger.yaml znajdziesz tu.
Lista zasobów podstawowych opisanych w poradniku:
- GET /order/events - pobierz dziennik zdarzeń
- GET /order/event-stats - pobierz informacje o ostatnim zdarzeniu
- GET /order/checkout-forms/{id} - pobierz szczegóły zamówienia
- PUT /order/checkout-forms/{id}/fulfillment - zmień status realizacji zamówienia
- POST /order/checkout-forms/{id}/shipments - dodaj numer przesyłki do zamówienia
- GET /order/customer-returns/{customerReturnId} - pobierz szczegółowe informacje o zwrocie
- POST /order/customer-returns/{customerReturnId}/rejection - odmów zwrotu wpłaty
- POST /payments/refunds - zrealizuj zwrot płatności
- POST /order/refund-claims - utwórz wniosek o rabat transakcyjny
Lista zasobów wspierających opisanych w poradniku:
- GET /order/checkout-forms - pobierz listę zamówień
- GET /order/carriers - pobierz listę przewoźników
- GET /order/checkout-forms/{id}/shipments - pobierz numer przesyłki przypisany do zamówienia
- GET /order/customer-returns - pobierz listę zwrotów klienckich
- GET /payments/refunds - pobierz listę wykonanych zwrotów
- GET /order/refund-claims - pobierz listę złożonych wniosków o rabat transakcyjny
- GET /order/refund-claims/{claimId} - pobierz szczegóły wniosku o rabat transakcyjny
- DELETE /order/refund-claims/{claimId} - anuluj wniosek o rabat transakcyjny
