Zamówienia w Allegro REST API

orders



Dowiedz się, jak zrealizować zamówienia przez Allegro REST API. 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.

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.


Ważne:

  • 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ń.

  • Identyfikató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. /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ń:

Kliknij, żeby zobaczyć przykładowy 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
                },
                "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
                }
            },
            "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"
                },
                "lineItems": [
                    {
                        "offer": {
                            "id": "7458058360",
                            "name": "Telewizor Sony '21",
                            "external": 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"
                }
            },
            "type": "FILLED_IN",
            "occurredAt": "2018-07-16T10:13:37.925Z"
        },
    ]
}

Szczegóły zamówienia

Wywołaj GET /order/checkout-forms/{checkoutForm_id}, żeby 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/{checkoutForm_id} \’
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'
 

Kliknij, żeby zobaczyć przykładowy response:
 {
    "id": "ffc396b0-9584-11e8-8d53-07c966f77738",           -- identyfikator zamówienia
    "buyer": {
        "id": "1424041",                                    -- identyfikator kupującego
        "email": "ymu1woaqq+54111a037@user-dev.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": "+381 11 1111111",                   -- numer telefonu z ustawień konta 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": {
        "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"
        "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 6990",                     -- ulica
            "city": "Poznań",                               -- miasto
            "zipCode": "18-282",                            -- kod pocztowy
            "countryCode": "PL",                            -- kod kraju
            "phoneNumber": "000333666"                      -- numer telefonu kupującego
                                                            z formularza dostawy
        },
        "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": {
            "guaranteed": {                                 -- gwarantowany czas dostawy
                "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)
    },
    "invoice": {                                             -- informacja o danych do faktury
        "required": false
    },
    "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
              }
            },
            "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
        }
    ],
    "surcharges": [],                                        -- informacje o ew. dopłatach
    "discounts": [                                           -- zniżki z których skorzystał
                                                             kupujący podczas zakupów
                {
                "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
                }
            ],
    "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/{checkoutForm.id}/fulfillment zmienisz status realizacji zamówienia widoczny w polu fulfillment.status. Jako checkoutForm.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”) 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.

information

WAŻNE! Do końca lipca 2020 możesz wyłączyć opcję anulowania zamówienia dla wszystkich swoich zamówień - zrobisz to na stronie Ustawienia zamówień.my do 60 dni. Po tym okresie usuniemy taki draft. Jeśli zmienisz coś w nim, wydłużymy jego ważność o 60 dni.

Kliknij, żeby zobaczyć przykładowy 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",
        "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": [],
    "summary": {
        "totalToPay": {
            "amount": "1.00",
            "currency": "PLN"
        }
    },
    "updatedAt": "2020-05-05T10:06:39.065Z",
    "revision": "dc0f896f"
}

Lista zamówień

GET /order/checkout-forms - pozwoli ci pobrać listę zamówień.

information

WAŻNE! 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.

W takiej formie zapytanie zwróci maksymalnie 100 najnowszych zamówień. Lista zawiera zamówienia z ostatnich 6 miesięcy, z takim samym zestawem danych, jakie możesz zobaczyć w szczegółach zamówienia. 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 od 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:


Ważne: W sytuacji:

  • Jeśli kupujący zrobił np. dwa oddzielne zakupy przez koszyk lub Kup Teraz,

  • następnie postanowił zapłacić za nie wspólnie (wypełnił wspólny FOD),

  • dostaniesz nowe zamówienie z nowym identyfikatorem checkoutForm.id.

  • Poprzednie zamówienia, oddzielne dla każdego z tych zakupów usuniemy - pozostanie tylko to ostatnie.

Przykładowy request:

 
  curl -X GET \
  'https://api.allegro.pl/order/checkout-forms'
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json'
 

Kliknij, żeby zobaczyć przykładowy 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@user-dev.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": "+381 11 1111111",                  -- numer telefonu z ustawień
                                                                   konta 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": {
                "guaranteed": {                                    -- gwarantowany czas dostawy
                    "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)
             },
               "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
                            }
                    },
                    "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"
                }
            ],
            "surcharges": [],
            "discounts": [                                          -- zniżki z których skorzystał
                                                                    kupujący podczas zakupów
                {
                "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
                }
            ],
            "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@user-dev.allegrogroup.pl",
                "login": "example_login",
                "firstName": "Andrzej",
                "lastName": "Nowak",
                "companyName": null,
                "guest": false,
                "personalIdentity": null,
                "phoneNumber": "+381 11 1111111",
                "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"
                    },
                    "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"
                }
            ],
            "surcharges": [],
            "discounts": [],
            "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@user-dev.allegrogroup.pl",
                "login": "example_login",
                "firstName": "Jan",
                "lastName": "Nowak",
                "companyName": null,
                "guest": false,
                "personalIdentity": null,
                "phoneNumber": "+381 11 1111111",
                "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ń"
                    }
                },
                "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)
            },
            "invoice": {
                "required": false
            },
            "lineItems": [
                {
                    "id": "4db6dae0-7e9b-11e8-a346-0ff9a46a7007",
                    "offer": {
                        "id": "6205387764",
                        "name": “podręczniki do 1 klasy"
                    },
                    "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"
                }
            ],
            "surcharges": [],
            "discounts": [],
            "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:

orders

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"
                   }
                 }
               ],
 

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": "+381 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ń"
                    }
                },
            "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)
        }
    }
 },
 

Obsługa przesyłek

Jak dodać numer przesyłki do przedmiotu w zamówieniu

Za pomocą POST /order/checkout-forms/{checkoutForm.id}/shipments możesz dodać numer przesyłki do wybranych aktów zakupowych (lineItem.Id) w danym zamówieniu. CheckoutForm.id i poszczególne lineItem.id pobierzesz zasobami do obsługi zamówień.

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": [                          -- wymagane, 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/{checkoutForm.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=="
        }
    ]
 }
 

Zwroty płatności

Jak wykonać zwrot płatności

Aby zrealizować zwrot płatności, skorzystaj z POST /payments/refunds.

information

Możesz zlecić zwrot dla płatności utworzonych po 31.07.2019.


Ważne! W zleceniu zwrotu przekaż:

  • identyfikator płatności kupującego (payment.id pobierzesz za pomocą GET order/checkout-forms),

  • powód zwrotu,

  • za co chcesz zwrócić płatność - możesz zwrócić płatność za przedmiot, dostawę, nadpłatę, dopłatę oraz dodatkowe usługi.


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.


Zwrot płatności za produkt według liczby sztuk, dostawę, nadpłatę, dopłatę i dodatkowe usługi:

Kliknij, żeby zobaczyć przykładowy 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)
    "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"
        }
      }
 }’


Zwrot określonej kwoty za produkt:

Kliknij, żeby zobaczyć przykładowy 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"
            }
        }
    ]
 }

Kliknij, żeby zobaczyć przykładowy 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"
        }
    }
}

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, żeby zobaczyć przykładowy 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.

information

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/{checkoutFormId},

  • quantity - liczba przedmiotów z zamówienia, za którą chcesz otrzymać rabat transakcyjny.


Ważne! Dla każdego lineItem.id możesz utworzyć tylko jeden wniosek o rabat transakcyjny. Zwróć uwagę, czy w polu quantity przekazujesz prawidłową liczbę przedmiotów.


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, żeby zobaczyć przykładowy 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
            "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",
            "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",
            "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.