Whitelabel

🛡

To API jest zabezpieczone — w requestach w nagłówku Authorization należy przekazać token dostępowy.

Wysłanie zaproszenia dla reklamodawców do sklepu

Typowo zapraszanie reklamodawców do sklepu odbywa się poprzez panel w zakładce “Reklamodawcy” (widoczny tylko dla whitelabel). Ten endpoint udostępnia tę samą funkcjonalność po API, co jest użyteczne, gdy chcemy zautomatyzować zapraszanie reklamodawców.

POST https://api.adshero.io/v1/invitations/shop/{shopId}/whitelabel HTTP/2
Authorization: Bearer {access_token}
Content-Type: application/json

{ 
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "sellerIds": [ "string" ],
  "brands": [ "string" ]
}

curl --location --request POST \
    'https://api.adshero.io/v1/invitations/shop/{shopId}/whitelabel' \ 
    --header 'Authorization: Bearer {access_token}' \
    --header 'Content-Type: application/json' \
    --data '{ 
      "firstName": "string",
      "lastName": "string",
      "email": "string",
      "sellerIds": [ "string" ],
      "brands": [ "string" ]
    }'

Opis parametrów:

firstName — Imię sprzedawcy.
lastName — Nazwisko sprzedawcy.
email — Adres e-mail — na ten adres sprzedawca dostanie zaproszenie do założenia konta. Jeśli będzie niepoprawny, to sprzedawca nie skorzysta z Ads-ów.
sellerIds — Seller ID — Identyfikator sprzedawcy z feed-a (external_seller_id). Może być pusty, ale wtedy należy wypełnić pole brands. Definiuje produkty, które sprzedawca ma dostępne do reklamowania.
brands — Marka — Identyfikator marki z feeda (brand). Może być pusta, ale wtedy należy wypełnić pole sellerIds. Definiuje produkty, które sprzedawca ma dostępne do reklamowania.

Raport kosztów

Endpoint zwraca raport kosztów reklamodawców pogrupowany po jednostkach reklamowych (business slotach).

GET https://api.adshero.io/v1/whitelabel/{whitelabelHash}/report/costs?startDate=2026-01-01&endDate=2026-06-30&page=1&pageSize=10 HTTP/2
Authorization: Bearer {access_token}

curl --location --request GET \
    'https://api.adshero.io/v1/whitelabel/{whitelabelHash}/report/costs?startDate=2026-01-01&endDate=2026-06-30&page=1&pageSize=10' \
    --header 'Authorization: Bearer {access_token}'

Opis parametrów:

whitelabelHash (path, wymagany) — identyfikator whitelabel (UUID), przekazywany przez Adshero w ramach konfiguracji whitelabel.
startDate (query, wymagany) — data od, format YYYY-MM-DD. Nie może być wcześniejsza niż 1 rok przed dniem dzisiejszym.
endDate (query, opcjonalny) — data do, format YYYY-MM-DD. Jeśli nie zostanie podany, domyślnie przyjmuje wczorajszą datę (ostatni dzień z kompletnymi danymi). Nie może być wcześniejsza niż startDate.
page (query, wymagany) — numer strony (wartość > 0).
pageSize (query, wymagany) — liczba wyników na stronę (wartość > 0).

Przykładowa odpowiedź:

{
  "data": [
    {
      "advertiserId": "adv-123",
      "sellerIds": ["seller-1", "seller-2"],
      "stats": {
        "bs-uuid-1": {
          "placementName": "Strona główna",
          "regularWalletCost": "150.50",
          "bonusWalletCost": "25.00"
        }
      }
    }
  ],
  "meta": {
    "page": 1,
    "itemsPerPage": 10,
    "totalResults": 42,
    "hasNext": true,
    "hasPrevious": false
  }
}

Opis pól odpowiedzi:

advertiserId — identyfikator reklamodawcy.
sellerIds — zbiór identyfikatorów sprzedawców (seller ID) powiązanych z reklamodawcą.
stats — mapa kosztów per jednostka reklamowa, gdzie kluczem jest ID business slota:
- placementName — nazwa jednostki reklamowej.
- regularWalletCost — koszt z portfela regularnego.
- bonusWalletCost — koszt z portfela bonusowego.
meta.page — bieżąca strona.
meta.itemsPerPage — liczba wyników na stronę.
meta.totalResults — łączna liczba wyników.
meta.hasNext — czy istnieje następna strona.
meta.hasPrevious — czy istnieje poprzednia strona.

Odczyt portfela reklamodawcy

Endpoint zwraca typ aktywnego portfela reklamodawcy oraz saldo środków przedpłaconych. Reklamodawca identyfikowany jest po seller ID (external_seller_id z feeda). Token dostępowy musi mieć nadany zakres (scope) wallet.

GET https://api.adshero.io/v1/whitelabel/{whitelabelHash}/seller/{sellerId}/wallet HTTP/2
Authorization: Bearer {access_token}

curl --location --request GET \
    'https://api.adshero.io/v1/whitelabel/{whitelabelHash}/seller/{sellerId}/wallet' \
    --header 'Authorization: Bearer {access_token}'

Opis parametrów:

whitelabelHash (path, wymagany) — identyfikator whitelabel (UUID), przekazywany przez Adshero w ramach konfiguracji whitelabel.
sellerId (path, wymagany) — identyfikator sprzedawcy z feeda (external_seller_id). Musi wskazywać dokładnie jednego reklamodawcę-sprzedawcę w ramach whitelabel — w przeciwnym razie zwracany jest błąd 404.

Przykładowa odpowiedź:

{
  "data": {
    "type": "REGULAR",
    "balance": 150.00
  }
}

Opis pól odpowiedzi:

type — typ aktywnego portfela reklamodawcy: REGULAR (przedpłacony) lub UNLIMITED (emisja reklam bez limitu salda).
balance — saldo środków przedpłaconych.

Doładowanie portfela reklamodawcy

Endpoint doładowuje portfel przedpłacony (REGULAR) reklamodawcy o podaną kwotę. Portfel jest tworzony automatycznie, jeśli jeszcze nie istnieje. Doładowanie zawsze zasila portfel REGULAR — również wtedy, gdy aktywny jest portfel UNLIMITED. Token dostępowy musi mieć nadany zakres (scope) wallet.

POST https://api.adshero.io/v1/whitelabel/{whitelabelHash}/seller/{sellerId}/wallet/refill HTTP/2
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "amount": 150.00,
  "deduplicationId": "partner-payment-2026-07-08-001"
}

curl --location --request POST \
    'https://api.adshero.io/v1/whitelabel/{whitelabelHash}/seller/{sellerId}/wallet/refill' \
    --header 'Authorization: Bearer {access_token}' \
    --header 'Content-Type: application/json' \
    --data '{
      "amount": 150.00,
      "deduplicationId": "partner-payment-2026-07-08-001"
    }'

Opis parametrów:

whitelabelHash (path, wymagany) — identyfikator whitelabel (UUID), przekazywany przez Adshero w ramach konfiguracji whitelabel.
sellerId (path, wymagany) — identyfikator sprzedawcy z feeda (external_seller_id). Musi wskazywać dokładnie jednego reklamodawcę-sprzedawcę w ramach whitelabel — w przeciwnym razie zwracany jest błąd 404.
amount (body, wymagany) — kwota doładowania. Musi być większa od 0.
deduplicationId (body, wymagany) — identyfikator deduplikacji (maksymalnie 256 znaków), np. identyfikator płatności po stronie partnera. Zapewnia idempotentność doładowań: ponowne wysłanie żądania z tym samym deduplicationId dla tego samego reklamodawcy nie doładuje portfela po raz drugi, a jedynie zwróci aktualny stan portfela.

Odpowiedź ma taki sam format jak odczyt portfela i zawiera stan portfela po doładowaniu:

{
  "data": {
    "type": "REGULAR",
    "balance": 300.00
  }
}