search

allegro / allegro-api

Issue tracker and wiki for Allegro REST API
https://developer.allegro.pl/
217 stars 39 forks source link

[NEWS] Allegro Ceny - dodamy nowe obiekty i typy pól do obsługi zamówień / Allegro Prices - we will add new objects and field types to handle orders #4279

Open AureliuszBrussy opened 3 years ago

AureliuszBrussy commented 3 years ago

Allegro Ceny to program, który pomaga Sprzedającym zaoferować najlepsze ceny na rynku – bez ponoszenia żadnych dodatkowych kosztów.

W związku z tym programem 31 marca 2021 wprowadzimy zmiany w:

dzięki którym prawidłowo rozpoznasz i obsłużysz zamówienie, w których kupujący dokonał zakupu w ofercie, która jest w programie Allegro Ceny.

Dla GET /order/checkout-forms oraz GET /order/checkout-forms/{id} wprowadzimy nowe obiekty:

W obiekcie lineItems[].reconciliation zwrócimy także pole type, w którym pobierzesz jedną z dwóch możliwych wartości:

W przypadku takich zamówień zwrócimy także w polu discounts nowy typ zniżki: “ALLEGRO_PRICES”.

Przykładowy request:

curl -X GET 
  ‘https://api.allegro.pl/order/checkout-forms/4fceac60-71c6-11eb-bb0e-5f505b61d1dc’ 
  -H ‘Authorization: Bearer {token}’  
  -H ‘Accept: application/vnd.allegro.public.v1+json’

Przykładowy 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”: “0”,                  – kwota, którą wyrównamy w płatności
                                            (dodamy do płatności kupującego).
                                            Wystąpi tylko w przypadku
                                            wyrównania typu “WALLET”

            “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”
              }
            },
            “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”

}

Ważne! W przypadku prawidłowej płatności (w której nie wystąpiła nadpłata lub niedopłata) kwota w polu payment.paidAmount oraz summary.totalToPay powinna być identyczna - niezależnie od tego, czy zamówienie zostało objęte programem Allegro Ceny.

W GET /billing/billing-entries zwrócimy nowy typ operacji billingowej: “PS1”. Otrzymasz go, gdy kupujący dokona zakupu w ofercie będącej w programie Allegro Ceny, a w zamówieniu zwróciliśmy w polu lineItems[].reconciliation.type wartość: “BILLING”.

Więcej informacji o szczegółach programu Allegro Ceny przeczytasz na stronie dla sprzedających. Więcej informacji o zmianie znajdziesz w naszym poradniku.

Allegro Prices is a seller support program that will help you to offer the best prices on the market - at no extra cost.

Because of this program, on March 31th, 2021 we will make changes to:

so you will be able to correctly identify and process orders where the buyer has purchased from the offer that is in the Allegro Prices program.

For GET /order/checkout-forms and GET /order/checkout-forms/{id} we will add objects:

In the lineItems[].reconciliation object, we will also return the type field, in which you will get one of the two possible values:

For such orders, we will also return a new discount type in the discounts field: "ALLEGRO_PRICES".

Sample request:

curl -X GET \
  'https://api.allegro.pl/order/checkout-forms/4fceac60-71c6-11eb-bb0e-5f505b61d1dc’ \
  -H 'Authorization: Bearer {token}'  \
  -H 'Accept: application/vnd.allegro.public.v1+json'

Sample response:

 {
  ...
    "payment": {
        "id": "677d4ba1-71c6-11eb-a259-c766517115fd",
        "type": "ONLINE",
        "provider": "PAYU",
        "finishedAt": "2021-03-15T12:18:33.434Z",
        "paidAmount": { 
            "amount": "80",                 -- customer payment amount
            "currency": "PLN"
        },
        "reconciliation": {
            "amount": "0",                  -- amount of reconciliation for the price
                                            reduction in buyer’s payment.
                                            Will only occur in the case of 
                                            "WALLET" type reconciliation    
            "currency": "PLN"
        }
    },
    "status": "READY_FOR_PROCESSING",                      
    ...
    "lineItems": [
        {
            "id": "ffc36fa0-9584-11e8-8d53-07c966f77738",
            "offer": {
                "id": "6205584023",
                "name": "Lifebelt",
                "external": {
                "id": "ext_2018_08_17" 
              }
            },
            "quantity": 1, 
            "originalPrice": {          
                "amount": "80.00",
                "currency": "PLN"
            },
            "price": {
                "amount": "80.00",      
                "currency": "PLN"
            },
            "reconciliation": {
                "value": {  
                "amount": "20.00",          -- reconciliation amount
                "currency": "PLN"
                },
            "quantity": 1,                  -- amount of reconciled items
            "type": "BILLING"               -- reconciliation type, one of two 
                                            values are possible:
                                            BILLING (reconciliation for the price 
                                            reduction on billing entry);
                                            WALLET (reconciliation for the price reduction 
                                            in buyer’s payment).
            },
            "selectedAdditionalServices": [ ],
            "boughtAt": "2021-03-15T12:18:33.434Z"
        }
    ],
    "surcharges": [],
    "discounts": [ 
                {
                "type": "ALLEGRO_PRICES"    -- ALLEGRO_PRICES discount type means, 
                                            that we reduced price and granted 
                                            compensation
                }             
    ],
    "summary": {
        "totalToPay": {
            "amount": "80.00",           
            "currency": "PLN"
        }
    },
 "updatedAt": "2021-03-15T12:18:33.434Z",
 "revision": "dc0f896f"                                   
}

Note! In case of a correct payment (in which there was no overpayment or underpayment), the amount in payment.paidAmount and summary.totalToPay fields should be identical - regardless of whether the order was covered by Allegro Prices.

In GET /billing/billing-entries we will return a new billing operation type: "PS1". You will get it when a buyer makes a purchase that is covered by the Allegro Prices program, and in the order we returned value "BILLING" in the lineItems[].reconciliation.type field.

You can read more about the Allegro Prices program on the Sellers Page. You can find more informations about change in our guide.

ghost commented 3 years ago

@AureliuszBrussy czy pobierając ofertę przez API przez zasób Offers dostaniemy informację o cenie i dopłacie?

Przykładowo obecne działanie Wystawiam ofertę z ceną 100 zł Pojawia się oferta na 100 zł Zmieniam cenę produktu na 97 zł Automat zmienia cenę na 97 zł w ofercie I tak skalujemy to na tysiące zmian ceny na tysiącach ofert.

Teraz do tego scenariusza powyżej dodaję AllegroCeny Wystawiam ofertę z ceną 100 zł Pojawia się oferta na 100 zł, ale wyświetla się 95 zł (5 zł mam zwrotu z Allegro) Zmieniam cenę produktu na 97 zł, ile się wyświetli (nadal 95 czy może 92 zł) ? Automat w naszym przypadku się zapętli próbując cały czas ustawić poprawną cenę

W zwiąku z tym pytanie, czy zasób Offers zwróci "moją cenę" oraz "cenę po obniżce" by nadal móc automatycznie zarządzać cenami?

AureliuszBrussy commented 3 years ago

@SebastianOzdoba zgodnie z zasadami programu Allegro Ceny - każda zmiana ceny towaru w ofercie spowoduje wyłączenie programu Allegro Ceny dla tej oferty. Ponowne zakwalifikowanie oferty do programu będzie możliwe dopiero w następnej rundzie kwalifikacyjnej.

To, czy oferta znajduje się w programie Allegro Ceny rozpoznasz dzięki GET /sale/badges. Więcej o tym piszemy w newsie.

AureliuszBrussy commented 3 years ago

@SebastianOzdoba nie zwracamy informacji na zasobie /sale/offers o tym, czy oferta jest w programie Allegro Ceny. Tą informację uzyskasz w GET /sale/badges.