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 płatniczych

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

Możesz skorzystać z dwóch udostępnionych przez nas zasobów:

  • POST /pricing/fee-preview - na podstawie określonych warunków oferty sprawdź, jakie opłaty pobieramy w danej kategorii.


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


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