Historia operacji billingowych

Za pomocą zasobu GET /billing/billing-entries pobierzesz historię operacji billingowych oraz saldo zautoryzowanego użytkownika.

Domyślnie w odpowiedzi otrzymasz listę 100 operacji billingowych, gdzie pierwszy wynik jest najnowszy. Aby dostosować listę do swoich potrzeb, możesz skorzystać z parametrów:

  • limit - określ liczbę operacji billingowych, jaką chcesz otrzymać w odpowiedzi, maksymalna wartość to 100,

  • offset - wskaż miejsce, od którego chcesz pobrać następną porcję danych.

np. GET /billing/billing-entries?limit=50&offset=25 zwróci 50 operacji billingowych od wybranego punktu. Możesz także skorzystać z filtrów:

Możesz także skorzystać z filtrów:

  • data operacji billingowej - możesz filtrować operacje billingowe według daty, używając parametrów:

    • occurredAt.gte (najwcześniejsza data wystąpienia operacji billingowej w formacie ISO 8601),

    • occurredAt.lte (najpóźniejsza data wystąpienia operacji billingowej w formacie ISO 8601),

np. GET /billing/billing-entries?occurredAt.gte=2019-07-10T11:06:50.935Z&occurredAt.lte=2019-07-15T11:06:50.935Z,

  • typ operacji billingowej - sprawdź, jaki type.id jest powiązany z name.id (nazwą operacji) - szczegółową listę dostępnych operacji billingowych pobierzesz zasobem GET /billing/billing-types. Przekaż type.id jako wartość parametru, aby uzyskać interesujące cię wyniki. np. GET /billing/billing-entries?type.id=SUC - w ten sposób pobierzesz wszystkie wyniki, które dotyczą prowizji od sprzedaży,

  • identyfikator oferty - np. GET /billing/billing-entries?offer.id=8566354406 - pobierze wszystkie operacje billingowe powiązane z przekazaną ofertą.


Przykładowy request:

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

Za pomocą GET /billing/billing-types pobierzesz również numer zamówienia, który zwrócimy w polu “order.id”. Dzięki temu w historii operacji billingowych będziesz mógł zidentyfikować zamówienie, dla którego pobrana została opłata.

information WAŻNE! Wartość w polu “order.id” zwrócimy dla wszystkich typów billingowych, w których pokazujemy numer zamówienia. Dla pozostałych nie zwrócimy obiektu “order”.

Przykładowy response:

...
{    
    "id": "f2b843f1-8fa3-45a6-98f7-0590cd8d39d2",
    "occurredAt": "2020-09-07T10:47:19.981Z",
    "type": {
        "id": "SUC",
        "name": "Prowizja od sprzedaży"
    },
    "offer": {
        "id": "9608631866",
        "name": "oferta testowa"
    },
    "value": {
        "amount": "-10.10",
        "currency": "PLN"
    },
    "tax": {
        "percentage": "23"
    },
    "balance": {
        "amount": "-113.53",
        "currency": "PLN"
    },
    "order" : {
        "id" : "726c25e0-f0f7-11ea-887c-8753d63d8e79"
    }
...
 }

Historia operacji płatniczych

Za pomocą GET /payments/payment-operations pobierzesz historię operacji na saldzie zalogowanego sprzedającego.

Domyślnie w odpowiedzi otrzymasz listę 100 operacji płatniczych, gdzie pierwszy wynik jest najnowszy. Aby dostosować listę do swoich potrzeb, możesz skorzystać z parametrów:

  • limit - określ liczbę operacji, jaką chcesz otrzymać w odpowiedzi, maksymalna wartość to 100,

  • offset - wskaż miejsce, od którego chcesz pobrać następną porcję danych.

np. GET /payments/payments-operations?limit=50&offset=25 zwróci 50 operacji billingowych od wybranego punktu. Możesz także skorzystać z filtrów:

  • data operacji - możesz filtrować operacje billingowe według daty, używając parametrów:

    • occurredAt.gte (najwcześniejsza data wystąpienia operacji w formacie ISO 8601)

    • occurredAt.lte (najpóźniejsza data wystąpienia operacji w formacie ISO 8601),

np. GET /payments/payment-operations ?occurredAt.gte=2019-07-10T11:06:50.935Z&occurredAt.lte=2019-07-15T11:06:50.935Z,

  • identyfikator płatności - np. GET /payments/payment-operations?payment.id=ca3871d1-ec01-11e9-bc5f-3de157f9f689,

  • login kupującego - np. GET /payments/payment-operations?participant.login=participant. Wyjątkiem jest operacja typu REFUND_INCREASE, wtedy participant.login oznacza sprzedawcę,

  • grupa typów operacji - np. GET /payments/payment-operations?group=INCOME. Dostępne wartości to: INCOME, OUTCOME, REFUND lub BLOCKADES,

  • operator płatności - np. GET /payments/payment-operations?wallet.operator=PAYU,

  • możliwość wypłacenia środków - np. GET /payments/payment-operations?wallet.type=AVAILABLE zwróci operacje, dla których można wypłacić środki z salda, wartość WAITING oznacza, że jest to tymczasowo niemożliwe.


Przykładowy request:

  curl -X GET
  https://api.allegro.pl/payments/payment-operations?group=INCOME&limit=1
  -H ‘Authorization: Bearer {token}’ /
  -H ‘Accept: application/vnd.allegro.public.v1+json’ /
  -H ‘Content-Type: application/vnd.allegro.public.v1+json’

Przykładowy response:

  {
    "paymentOperations": [
        {
            "type": "CONTRIBUTION",                             -- typ operacji
            "group": "INCOME",                                  -- grupa typu operacji
            "wallet": {
                "paymentOperator": "PAYU",                      -- operator płatności
                "type": "AVAILABLE",                            -- oznacza możliwość wypłacenia
                                                                środków z salda
                "balance": {
                    "amount": "3297.81",                        -- saldo po operacji
                    "currency": "PLN"
                }
            },
            "occurredAt": "2019-10-11T08:33:40.650Z",           -- czas wystąpienia operacji
            "value": {
                "amount": "144.00",                             -- kwota operacji
                "currency": "PLN"
            },
            "payment": {
                "id": "ca3871d1-ec01-11e9-bc5f-3de157f9f689"    -- identyfikator płatności
            },
            "participant": {                                    -- dane kupującego
                "id": "44182721",                   
                "companyName": "Allegro.pl Sp. z o.o.",
                "login": "przykładowyLogin",
                "firstName": "",
                "lastName": "",
                "address": {
                    "street": "Grunwaldzka 1822",
                    "city": "Poznań",
                    "postCode": "60-166"
                }
            }
        }
    ],
    "count": 1,                                                 -- widoczna liczba wyników
    "totalCount": 31                                            -- dostępna liczba wyników
  }           

Kalkulator opłat

Dzięki kalkulatorowi opłat sprzedający mogą sprawdzić, jakie opłaty pobieramy w ramach danej kategorii lub dla konkretnej oferty. Kalkulator opłat zwraca dane dla zalogowanego użytkownika.

Skorzystaj z POST /pricing/offer-fee-preview aby sprawdzić sprawdzić, jakie opłaty naliczymy w ramach konkretnej oferty. Wystarczy, że w strukturze offer przekażesz pełne dane oferty. Pobierzesz je za pomocą GET /sale/offers/{offerId}.


Kliknij, żeby zobaczyć przykładowy request:
curl -X POST 
https://api.allegro.pl/pricing/offer-fee-preview
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-H 'Authorization: Bearer {token}'
-H 'Accept-Language: PL'
-d '{ "offer": { "name": "Przykładowa oferta", "category": { "id": "79419" }, "product": null, "parameters": [ { "id": "11323", "valuesIds": [ "11323_246514" ], "values": [], "rangeValue": null }, { "id": "223489", "valuesIds": [], "values": [ "Autor" ], "rangeValue": null }, { "id": "223541", "valuesIds": [ "223541_491585" ], "values": [], "rangeValue": null }, { "id": "223545", "valuesIds": [], "values": [ "Sample" ], "rangeValue": null }, { "id": "245669", "valuesIds": [], "values": [ "9780000000057" ], "rangeValue": null }, { "id": "74", "valuesIds": [], "values": [ "2015" ], "rangeValue": null }, { "id": "7773", "valuesIds": [ "7773_2" ], "values": [], "rangeValue": null } ], "customParameters": null, "ean": "9780000000057", "description": { "sections": [ { "items": [ { "type": "TEXT", "content": "<p>Pzykładowy opis</p>" } ] } ] }, "compatibilityList": null, "tecdocSpecification": null, "images": [ { "url": "https://a.allegroimg.allegrosandbox.pl/original/116421/ece7111d4b8fbbc4662ab92f84ce&#34; } ], "sellingMode": { "format": "BUY_NOW", "price": { "amount": "50", "currency": "PLN" }, "startingPrice": null, "minimalPrice": null, "netPrice": null }, "tax": null, "stock": { "available": 1, "unit": "UNIT" }, "publication": { "duration": null, "status": "ACTIVE", "startingAt": null, "endingAt": null, "endedBy": null, "republish": false }, "delivery": { "shippingRates": { "id": "17221a3c-f4cf-4e47-953a-8e125013b014" }, "handlingTime": "PT336H", "additionalInfo": "", "shipmentDate": null }, "payments": { "invoice": "NO_INVOICE" }, "discounts": null, "afterSalesServices": { "impliedWarranty": { "id": "f86078a6-9f42-4b76-9696-1e5c0646a60a" }, "returnPolicy": { "id": "47101223-7236-4201-9779-316e6d10af2a" }, "warranty": null }, "additionalServices": null, "sizeTable": null, "fundraisingCampaign": null, "promotion": { "emphasized": true, "bold": false, "highlight": false, "departmentPage": false, "emphasizedHighlightBoldPackage": false }, "location": { "countryCode": "PL", "province": "WIELKOPOLSKIE", "city": "Poznań", "postCode": "66-166" }, "external": null, "attachments": [], "contact": null, "validation": { "errors": [], "warnings": [], "validatedAt": "2020-12-04T09:31:07.684Z" }, "createdAt": "2020-10-01T05:44:23.000Z", "updatedAt": "2020-12-04T09:31:08.925Z" } } '


Kliknij, żeby zobaczyć przykładowy response:
{
    "commissions": [                                      – prowizje
        {
            "name": "Prowizja od sprzedaży",              – nazwa prowizji
            "type": "commissionFee",                      – typ prowizji
            "fee": {
"amount": 2.50, – kwota prowizji "currency": "PLN" } }, { "name": "Prowizja od sprzedaży oferty wyróżnionej", "type": "commissionFeatureFee", "fee": { "amount": 200.00, "currency": "PLN" } } ], "quotes": [ – opłaty { "name": "Wystawienie przedmiotu", – nazwa opłaty "type": "listingFee", – typ opłaty "fee": { "amount": 0.15, – kwota opłaty "currency": "PLN" }, "cycleDuration": "PT240H", – informacje w jakich cyklach będziemy naliczać daną opłatę "classifiedsPackage": { "id": null } }, { "name": "Opłata za wyróżnienie", "type": "distinctionFee", "fee": { "amount": 12.00, "currency": "PLN" }, "cycleDuration": "PT240H", "classifiedsPackage": { "id": null } } ] }

Data naliczenia kolejnej opłaty

Od sierpnia 2017 roku opłaty naliczamy w cyklach 10 dniowych. Dlatego udostepniliśmy zasób, który pozwoli w prosty sposób sprawdzić, kiedy dany cykl się skończy i kiedy naliczymy kolejną opłatę.

Do sprawdzenia kiedy dany cykl się skończy i naliczymy kolejną opłatę przygotowaliśmy dedykowany zasób w REST API Allegro:

  • GET /pricing/offer-quotes - to zasób, którym sprawdzisz kiedy dany cykl się skończy i naliczymy kolejną opłatę. Musisz być zalogowany jako sprzedawca, który wystawił oferty.


Ważne! Maksymalnie możesz podać 20 numerów ofert.


Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/pricing/offer-quotes?offer.id=7617492560,7794910978' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Accept-Language: PL' \
  -H 'Authorization: Bearer {token}' \

Kliknij, żeby zobaczyć przykładowy response:
{

{ "count": 3, – liczba opłat "quotes": [ { "type": "LISTING", – rodzaj opłaty, dostępne są wartości: LISTING, BOLD, HIGHLIGHT, EMPHASIZED, EMPHASIZED_HIGHLIGHT_BOLD_PACKAGE, DEPARTMENT_PAGE, MIN_PRICE, BARGAIN INEFFECTIVE_LISTING_FEE "name": "Wystawienie", – nazwa opłaty, dostępne są wartości: Wystawienie, Pogrubienie, Podświetlenie, Wyróżnienie, Pakiet promo, Strona działu, Cena minimalna, Okazja Utrzymaniowa "nextDate": "2019-01-24T15:41:33.112Z", – data naliczenia kolejnej opłaty za wystawienie "fee": { "amount": "0.00", – kwota, którą naliczymy "currency": "PLN" – waluta }, "offer": { – oferta, dla której obliczyliśmy opłaty "id": "7617492560" – identyfikator oferty }, "enabled": true – status opłaty }, { "type": "EMPHASIZED", "name": "Wyróżnienie", "nextDate": "2019-02-01T09:50:05.135Z", "fee": { "amount": "19.00", "currency": "PLN" }, "offer": { "id": "7794910978" }, "enabled": true }, { "type": "LISTING", "name": "Wystawienie", "nextDate": "2019-02-01T09:50:05.135Z", "fee": { "amount": "0.00", "currency": "PLN" }, "offer": { "id": "7794910978" }, "enabled": true } ] }

Lista zasobów

Pełną dokumentację zasobów w postaci pliku swagger.yaml znajdziesz tu.

Lista zasobów podstawowych opisanych w poradniku:

Lista zasobów wspierających opisanych w poradniku: