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

Historia operacji

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

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, 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 lub REFUND,

  • 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 w REST API. Sprzedający mogą sprawdzić jakie opłaty pobieramy w każdej kategorii. Kalkulator opłat w REST API zwraca dane dla Użytkownika, który jest zalogowany. Dla sprawdzenia opłaty jakie pobieramy w danej kategorii przygotowaliśmy poniższy zasób w REST API Allegro:


Przykładowy request:

 
  curl -X POST \
  https://api.allegro.pl/pricing/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 '{
    "includeQuotingBundles": true,                -- niewymagane, uzwględnij pakiety z Centrum Zniżek
    "offer": {
      "category": {
        "id": "250442"                            -- wymagane, id kategorii
      },
      "condition": "NEW",                         -- niewymagane, parametr stan, możliwe wartości:
                                                  "NEW", "USED", "OTHER"  
      "duration": "PT720H",                       -- wymagane, czas trwania oferty, możliwe wartości:
                                                  PT72H, PT120H, PT168H, PT240H, PT336H, PT480H, PT720H
      "numberOfBigPhotos": 3,                     -- niewymagane, liczba dużych zdjęć - nie ma wpływu
                                                  na wysokość opłaty
      "numberOfPhotos": 3,                        -- niewymagane, liczba zdjęć - nie ma wpływu
                                                  na wysokość opłaty
      "quantity": 5,                              -- niewymagane w ogłoszeniach,
                                                  liczba sprzedawanych przedmiotów
      "shop": true,                               -- niewymagane, format sprzedaży: sklep lub nie -
                                                  nie ma wpływu na wysokość opłaty
      "soldQuantity": 1,                          -- niewymagane, liczba sprzedanych przedmiotów
      "type": "SHOP",                             -- wymagane, format sprzedaży, możliwe wartości:
                                                  OFFER, ADVERTISEMENT, SHOP
      "unitPrice": 131,                           -- wymagane, cena jednostkowa - liczby całkowite
      "bold": true,                               -- niewymagane, pogrubienie
      "highlight": true,                          -- niewymagane, podświetlenie  
      "departmentPage": true,                     -- niewymagane, strona kategorii
      "emphasized": true,                         -- niewymagane, wyróżnienie
      "emphasizedHighlightBoldPackage": true,     -- niewymagane, pakiet promowania
      "multiVariant": true                        -- niewymagane, oferta wielowariantowa,
                                                  możliwe wartości: “true”, “false”
    }
  }'
 

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

  {
    "quotes": [
        {
            "type": "listingFee",                       -- typ opłaty
            "name": "Opłata za wystawienie",            -- nazwa opłaty
            "fee": {                                    -- kwota w złotówkach
                "amount": "0.00",
                "currency": "PLN"
            },
            "cycleDuration”: “PT240H”            -- informacje w jakich cyklach będziemy
                                                 naliczać daną opłatę
        },
        {
            "type": "highlightFee",
            "name": "Podświetlenie (sklep)",
            "fee": {
                "amount": "9.00",
                "currency": "PLN"
            },
            "cycleDuration": "PT240H"
        },
        {
            "type": "distinctionFee",
            "name": "Opłata za wyróżnienie (sklep)",
            "fee": {
                "amount": "19.00",
                "currency": "PLN"
            },
            "cycleDuration": "PT240H"
        },
        {
            "type": "departmentPageFee",
            "name": "Opłata za promowanie na stronie działu",
            "fee": {
                "amount": "29.00",
                "currency": "PLN"
            },
            "cycleDuration": "PT240H"
        },
        {
            "type": "boldHighlightDistinctionFee",
            "name": "Pakiet Wyróżnienie + Pogrubienie + Podświetlenie (sklep)",
            "fee": {
                "amount": "29.00",
                "currency": "PLN"
            },
            "cycleDuration": "PT240H"
        },
        {
            "type": "boldFee",
            "name": "Oplata za pogrubienie (sklep)",
            "fee": {
                "amount": "9.00",
                "currency": "PLN"
            },
            "cycleDuration": "PT240H"
        }
    ],
    "commissions": [                                    -- prowizje
        {
            "type": "commissionFee",                    -- typ prowizji
            "name": "Prowizja od sprzedaży (sklep)",    -- nazwa
            "fee": {                                    -- kwota w złotówkach
                "amount": "10.48",
                "currency": "PLN"
            }
        },
        {
            "type": "commissionFeatureFee",
            "name": "Prowizja od sprzedaży oferty wyróżnionej",
            "fee": {
                "amount": "4.20",
                "currency": "PLN"
            }
        }
    ]
}

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