search

allegro / allegro-api

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

[NEWS] Historia operacji billingowych i saldo / Billing operations and balance #2403

Open PrzemyslawLukanowski opened 4 years ago

PrzemyslawLukanowski commented 4 years ago

Udostępniliśmy dziś nowy zasób GET /billing/billing-entries, dzięki któremu pobierzesz historię operacji billingowych oraz saldo zautoryzowanego użytkownika.

Domyślnie w odpowiedzi otrzymasz listę 100 operacji billingowych, gdzie pierwszy wynik jest najnowszy. Możesz skorzystać z sortowania i filtrowania, aby zawęzić wyniki wyszukiwania i uzyskać interesujące cię dane. Więcej na ten temat dowiesz się z naszego poradnika.

Przykładowy request, dla którego otrzymasz informacje o operacjach z 10.10.2019:

curl -X GET
https://api.allegro.pl/billing/billing-entries?occurredAt.gte=2019-10-10T00:00:00.000Z&occurredAt.lte=2019-10-10T23:59:59.000Z
-H ‘Authorization: Bearer {token}’ /
-H ‘Accept: application/vnd.allegro.public.v1+json’ /
-H ‘Content-Type: application/vnd.allegro.public.v1+json’

Przykładowy response:

{
    "billingEntries": [
        {
            "id": "da74ef80-f97a-4b04-a748-4c129cfb94b8    -- identyfikator operacji 
            "occurredAt": "2019-10-10T10:27:17.412Z",      -- czas wystąpienia operacji
            "type": {
                "id": "LIS",                   -- trzyliterowy kod typu operacji
                "name": "Wystawienie przedmiotu"       -- nazwa typu operacji
            "offer": {
                "id": "6206586563",            -- identyfikator oferty
                "name": "oferta testowa"           -- tytuł oferty
            },
            "value": {
                "amount": "-1.00",                 -- cena operacji                
                "currency": "PLN"
            },
            "tax": {
                "percentage": "0",              -- wysokość podatku
            "annotation": "EXEMPT"              -- pole opcjonalne - dane zwracamy 
                                w przypadku, gdy operacja jest
                                zwolniona z podatku (“EXEMPT”) 
                                                            lub podatek nie ma zastosowania
                                                            ("NOT_APPLICABLE")
            },
            "balance": {
                "amount": "-737.57",                    -- saldo po operacji
                "currency": "PLN"
            }
        }
    ]
}

Więcej informacji znajdziesz w naszej dokumentacji.

We have introduced new resource GET /billing/billing-entries, which allows you to retrieve list of billing operations and balance for the authorized user.

By default, you will retrieve list of 100 billing operations, where the first result is the newest. You can use sorting and filtering to narrow down your search results and get the data you are interested in. More information you will find in our tutorial.

Sample request, for which you will retrieve information about the operations from 10.10.2019:

curl -X GET
https://api.allegro.pl/billing/billing-entries?occurredAt.gte=2019-10-10T00:00:00.000Z&occurredAt.lte=2019-10-10T23:59:59.000Z
-H ‘Authorization: Bearer {token}’ /
-H ‘Accept: application/vnd.allegro.public.v1+json’ /
-H ‘Content-Type: application/vnd.allegro.public.v1+json’

Sample response:

{
    "billingEntries": [
        {
            "id": "da74ef80-f97a-4b04-a748-4c129cfb94b8",   -- billing entry ID
            "occurredAt": "2019-10-10T10:27:17.412Z",       -- date of billing entry
            "type": {
                "id": "LIS",                    -- three-letter code of the billing type 
                "name": "Wystawienie przedmiotu"        -- name of the billing type
            "offer": {
                "id": "6206586563",             -- offer ID
                "name": "oferta testowa"            -- offer title
            },  
            "value": {
                "amount": "-1.00",                             
                "currency": "PLN"
            },
            "tax": {
                "percentage": "0"               -- tax rate
            "annotation": "EXEMPT"              -- additional field - returned if 
                                                            the billing entry is exempt 
                                                            from tax (“EXEMPT”)  
                                                            or tax is not applicable 
                                                            ("NOT_APPLICABLE")
            },
            "balance": {
                "amount": "-737.57",                    -- balance after the operation
                "currency": "PLN"
            }
        }
    ]
}

You can find more details about the new resource in the documentation.

rtnet-pl commented 4 years ago

Ekstra. Przydałoby się aby zasób zwracał dodatkowo po prostu sumę wszystkich kosztów. Dzięki temu byłoby możliwe pobranie kosztu całkowitego dla danej oferty w 1 req. (unikniemy w ten sposób niepotrzebnego stronicowania dla starszych ofert).

rtnet-pl commented 4 years ago

Jest problem jeśli podam >1 identyfikator oferty (wg dokumentacji jest to możliwe). otrzymam wtedy pusty wynik.

GET https://api.allegro.pl/billing/billing-entries?offer.id=7932039542&offer.id=860345876 HTTP/1.1
Accept: application/vnd.allegro.public.v1+json
Content-Type: application/vnd.allegro.public.v1+json
Authorization: Bearer eyJh....
Host: api.allegro.pl
Connection: Close
-----------------
HTTP/1.1 200 OK
expires: 0
cache-control: no-cache, no-store, max-age=0, must-revalidate
x-xss-protection: 1; mode=block
server: envoy
pragma: no-cache
x-frame-options: DENY
trace-id: 23b89cbb6ef5d26b
date: Mon, 21 Oct 2019 21:19:12 GMT
x-ratelimit-remaining: 8185
x-content-type-options: nosniff
content-type: application/vnd.allegro.public.v1+json;charset=UTF-8
content-length: 21
x-ratelimit-limit: 9000
x-envoy-upstream-service-time: 27
connection: close

{"billingEntries":[]}

dla jednego ID jest ok:

GET https://api.allegro.pl/billing/billing-entries?offer.id=7932039542 HTTP/1.1
Accept: application/vnd.allegro.public.v1+json
Content-Type: application/vnd.allegro.public.v1+json
Authorization: Bearer eyJ..kA
Host: api.allegro.pl
Connection: Close

----------------
HTTP/1.1 200 OK
expires: 0
cache-control: no-cache, no-store, max-age=0, must-revalidate
x-xss-protection: 1; mode=block
server: envoy
pragma: no-cache
x-frame-options: DENY
trace-id: 2c765ad2f767f9b3
date: Mon, 21 Oct 2019 21:17:41 GMT
x-ratelimit-remaining: 8548
x-content-type-options: nosniff
content-type: application/vnd.allegro.public.v1+json;charset=UTF-8
content-length: 624
x-ratelimit-limit: 9000
x-envoy-upstream-service-time: 26
connection: close

{"billingEntries":[{"id":"8793ffe1-8823-4609-926a-f9a2ebadd1ee","occurredAt":"2019-04-11T08:36:32.596Z","type":{"id":"HLI","name":"Podświetlenie"},"offer":{"id":"7932039542","name":"Aukcja testowa 4444"},"value":{"amount":"-9.00","currency":"PLN"},"tax":{"percentage":"23"},"balance":{"amount":"-18.00","currency":"PLN"}},{"id":"f4236081-d62d-465b-8759-87db943dc15b","occurredAt":"2019-04-11T08:36:32.113Z","type":{"id":"BLD","name":"Pogrubienie"},"offer":{"id":"7932039542","name":"Aukcja testowa 4444"},"value":{"amount":"-9.00","currency":"PLN"},"tax":{"percentage":"23"},"balance":{"amount":"-9.00","currency":"PLN"}}]}
PrzemyslawLukanowski commented 4 years ago

@rtnet-pl Twoją sugestię przekazuję do odpowiedniego zespołu. Co do wyszukiwania po id wielu ofert - dziękuję za zwrócenie uwagi, pracujemy już nad rozwiązaniem problemu, poinformuję Cię w tym wątku po jego wyeliminowaniu.

PrzemyslawLukanowski commented 4 years ago

@rtnet-pl wracam z aktualną informacją, dla tego zasobu istnieje możliwość filtrowania tylko po jednej wartości offer.id. Zaktualizowaśmy już dokumentację, przepraszam za nieporozumienie.

rtnet-pl commented 4 years ago

Niedobrze, np powiedzmy że powiązany z nim pricing/offer-quotes już ma taką możliwość. Poza tym jest jeszcze jeden błąd, jeśli odpytamy o ofertę która nie istnieje lub nie należy do klienta, to otrzymujemy kod 200 i pusty wynik zamiast błędu 40x

PrzemyslawLukanowski commented 4 years ago

Zgadza się, kod 200 i pusta tablica jest w tym przypadku prawidłową odpowiedzią, dla listingów zakładamy że to są błędne zapytania do wyszukiwarki i zwracamy pusta listę. Forbidden ma miejsce w przypadku zapytań o pojedynczy zasób.

TimothyKoval commented 4 years ago

Jakie wartości przyjmuje type.id?

PrzemyslawLukanowski commented 4 years ago

Możesz to sprawdzić przez powiązanie z type.name po wywołaniu GET billing/billing-entries, np. dla type.name: Prowizja od sprzedaży type.id to SUC, dla type.name: Wystawienie przedmiotu type.id to LIS. Na tę chwilę nie udostępniamy listy wszystkich wartości, jakie może przyjmować to pole.

kulisz commented 4 years ago

@PrzemyslawLukanowski Czy jestem jakoś wstanie sobie przefiltrować prowizje (SUC) na linii oferta - zakup klienta? Nie widzę w dokumentacji wzmianki na ten temat aby móc sobie to powiązań jaka była prowizja od zakupu oferty przez danego klienta.

Ew. czy istnieje jakiś inny endpoint gdzie mogę pobrać jaka została naliczona prowizja za sprzedaż dla całego koszyka zakupowego klienta?

Obecnie wydaje mi się, że jedyne co mogę zrobić to przefiltrować opłaty po type SUC + numerze oferty + dacie wystąpienia ustawionego w widełkach od daty zakupu + pare sekund. I z grubsza to będzie działać ale krzaczyć się już będzie gdy prowizja zostanie naliczona z większym opóźnieniem i dodatkowo inny klient kupi to samo w podobnym czasie.

PrzemyslawLukanowski commented 4 years ago

Czy jestem jakoś wstanie sobie przefiltrować prowizje (SUC) na linii oferta - zakup klienta? Nie widzę w dokumentacji wzmianki na ten temat aby móc sobie to powiązań jaka była prowizja od zakupu oferty przez danego klienta.

Ew. czy istnieje jakiś inny endpoint gdzie mogę pobrać jaka została naliczona prowizja za sprzedaż dla całego koszyka zakupowego klienta?

Niestety nie. Zasób oparty jest na zestawieniu z frontu, gdzie nie zwracamy informacji per user/zamówienie tylko oferta. Jedynym rozwiązaniem na tę chwilę jest to zaproponowane przez Ciebie - tylko wartość w polu occurredAt może być wykorzystana w celu powiązania z zamówieniem usera,

bozydarlelutko commented 4 years ago

Niestety nie. Zasób oparty jest na zestawieniu z frontu, gdzie nie zwracamy informacji per user/zamówienie tylko oferta.

@PrzemyslawLukanowski widzę, że w chwili obecnej na froncie jest już zwracany numer zamówienia w kolumnie typ operacji dla typu Prowizja od sprzedaży. Niestety API nadal nie zwraca informacji z jakiego zamówienia dotyczy operacja billingowa. Czy przewidujecie dodać informację jakiego zamówienia dotyczy operacja?

PrzemyslawLukanowski commented 4 years ago

Na tę chwilę nie mamy tego w planach, jednak jak najbardziej jest możliwe, że w przyszłości będziemy to zwracać. Nie mogę niestety podać przybliżonego terminu, ale o wszelkich zmianach będziemy informować.

centrumelektroniki commented 4 years ago

Na tę chwilę nie mamy tego w planach, jednak jak najbardziej jest możliwe, że w przyszłości będziemy to zwracać. Nie mogę niestety podać przybliżonego terminu, ale o wszelkich zmianach będziemy informować.

jest już możliwe przez API pobrać ten numer zamówienia ? ewentualnie jest jakiś termin kiedy udostępnicie tą informacje przez API ?

PrzemyslawLukanowski commented 4 years ago

Na tę chwilę sytuacja się nie zmieniła, nie mamy tego w planach. Dopisuję jednak Twój głos do sugestii i przekazuję potrzebę do odpowiedniego zespołu. Jeśli sytuacja się zmieni lub będę mógł podać bardziej wiążące informacje - poinformuję w tym wątku.

kulisz commented 4 years ago

@PrzemyslawLukanowski mój głos do tej sugestii też dopisz

PrzemyslawLukanowski commented 4 years ago

@kulisz Oczywiście.

jaceklodz commented 4 years ago

Nie tylko koszt całego koszyka się przyda ale także np koszt przesyłki i jej numer podany tak jak to ma miejsce w historii.

NUMER NADANIA:
0000242357947U
KOD:
DPD_P1_KURIER
NUMER ZAMÓWIENIA:
aea38102-c4e4-11ea-9e55-8ddf0c4c1349
SZCZEGÓŁY:
Allegro Kurier DPD

W tej chwili nie można ustalić całkowitych kosztów zamówienia. Jak się oblicza prowizja od kosztów przesyłki? Gdzie ona jest widoczna?

PrzemyslawLukanowski commented 4 years ago

Koszt przesyłki jest widoczny w sekcji value.amount dla tego typu operacji. Prowizja od kosztów dostawy jest już naliczona w każdej prowizji, jaka naliczamy np “prowizji od sprzedaży,” “prowizji od sprzedaży oferty wyroznionej”.

tobiaxor commented 4 years ago

@PrzemyslawLukanowski chciałem zauważyć, że brak ID transakcji dla wygenerowanych wpisów billingowych może być (i na pewno będzie) przez wiele osób uznane jako celowe działanie, żeby sprzedawcy nie zorientowali się na jakiej podstawie Allegro nalicza opłaty. Ten jeden identyfikator decyduje o tym, czy Allegro jest transparentne w naliczaniu kosztów, czy nie. Mój system próbuje łączyć opłaty z zamówieniami tak, jak piszą koledzy wyżej, ale niestety nie da się tego zrobić dobrze i brak tego jednego identyfikatora może ostatecznie mi posadzić cały biznes... Czy jest szansa na jego niedługie wdrożenie, szczególnie że jest już od dłuższego czasu na froncie, czy jedynym sposobem będzie crawlowanie strony Allegro?

PrzemyslawLukanowski commented 4 years ago

@tobiaxor Na tę chwilę nie mogę jeszcze przekazać wiążącej decyzji. Dopisałem Twoje zdanie do naszych sugestii i wrócę z wiadomością, gdy otrzymam odpowiedź od odpowiedniego zespołu.

jaceklodz commented 3 years ago

Trzeba powiedzieć sobie jasno i dobitnie: brak powiązania koszt-zamówienie jest celowym utrudnianiem zautomatyzowanego monitorowania kosztów. API zwraca jedno, raport generowany ze strony drugie. Powiązanie jednego z drugim jest niemożliwe.

Nie można kontrolować kosztów prowizji per zamówienie, kosztów kuriera etc. Wolna amerykanka. Tłumaczenia że "front" etc to klasyczna allegrowa ściema. Jak przychodzi do wprowadzania nowych prowizji to nie ma problemów.

Ps. Front zwraca informację o numerze zamówienia, numer przesyłki etc. Czemu do k.. nędzy API tego nie zwraca?

tobiaxor commented 3 years ago

Nie dość, że się nie udało uzyskać żadnej informacji, to sprawa się pogarsza - w przypadku wspisów dotyczących nowych opłat za smarta nie ma nawet powiązania z ofertą... Dostajemy tylko bezwartościowe wpisy, takie jak ten: { "id": "xxxxxxxxxxxxxxxxxxxxxx", "occurredAt": "2021-01-19T10:22:26.465Z", "type": { "id": "HB4", "name": "Allegro Paczkomaty InPost" }, "value": { "amount": "-0.99", "currency": "PLN" }, "tax": { "percentage": "23" }, "balance": { "amount": "-xxxx", "currency": "PLN" } }, Czy jest szansa na poprawę sytuacji, czy trzeba wrócić do crawlowania strony Allegro?

PrzemyslawLukanowski commented 3 years ago

Mamy wstępnie w planach zwracać informację o powiązanym numerze zamówienie, jednak na tę chwilę jest za wcześnie, abym mógł przekazać więcej wiążących informacji.

tobiaxor commented 3 years ago

Czy coś już wiadomo na temat tego, czy to ID transakcji pojawi się przy wpisach billingowych? Skoro na froncie to ID widać, to zakładam, że to nie jest problem techniczny...?

AureliuszBrussy commented 3 years ago

@tobiaxor tak jak napisaliśmy w wątku w Discussions - podjeliśmy decyzję, że zwrócimy pole, w którym wskażemy numer zamówienia, z którym powiązana jest opłata. O szczegółach będziemy jeszcze informować.

kulisz commented 3 years ago

@AureliuszBrussy ruszyło się coś w tym kierunku? Minął miesiąc i cisza

MartaNowaczyk commented 3 years ago

@kulisz prace trwają. Na ten moment nie mamy konkretnej daty. Na pewno damy znać, gdy dodamy pole z numerem zamówienia.