Jak sprawdzić opłaty
Poniżej znajdziesz opis procesów, dzięki którym dowiesz się m.in., jak pobrać historię operacji billingowych i płatniczych na koncie oraz sprawdzisz, jakie opłaty naliczymy w ramach konkretnej oferty.
Historia operacji billingowych
Za pomocą 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,
- marketplaceId - wskaż wybrany przez Ciebie serwis, dla którego zwrócimy historię operacji billingowych.
Jeżeli nie użyjesz parametru "marketplaceId", to domyślnie zwrócimy serwis bazowy, np. allegro-pl. Identyfikator serwisu bazowego użytkownika sprawdzisz w polu "baseMarketplace.id", korzystając z GET /me.
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 - pobierzesz wszystkie operacje billingowe powiązane z przekazaną ofertą,
- identyfikator zamówienia - np. GET /billing/billing-entries?order.id=29738e61-7f6a-11e8-ac45-09db60ede9d6 - pobierzesz wszystkie operacje billingowe powiązane z przekazanym zamówieniem.
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-entries 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.
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.
marketplaceId - identyfikator serwisu, na którym została przeprowadzona operacja płatnościowa,
currency - waluta, w której została przeprowadzona operacja.
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
"marketplaceId": "allegro-pl" -- identyfikator serwisu, w którym została
przeprowadzona operacja
"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 dla konkretnej oferty. Kalkulator opłat zwraca dane dla zalogowanego użytkownika.
Skorzystaj z POST /pricing/offer-fee-preview, aby sprawdzić, jakie opłaty naliczymy w ramach konkretnej oferty. Wystarczy, że w strukturze offer przekażesz pełne dane oferty.
Jeżeli w żądaniu nie przekażesz pola “marketplaceId”, domyślnie ustawimy wartość serwisu bazowego, np. “allegro-pl”. Identyfikator serwisu bazowego użytkownika sprawdzisz w polu "baseMarketplace.id", korzystając z GET /me.
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"
}
}'{
"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}'
{
{
"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:
- GET /billing/billing-entries - pobierz historię operacji billingowych
- GET /payments/payment-operations - pobierz historię operacji płatniczych
- POST /pricing/offer-fee-preview - sprawdź opłaty za ofertę
- GET /pricing/offer-quotes - pobierz informację o cyklu naliczenia opłat
Lista zasobów wspierających opisanych w poradniku:
- GET /billing/billing-types - pobierz typy operacji billingowych
