AD10€10 zľava s kódom AD10 pri pokladni
Dokumentácia

Hľadať v dokumentácii

Hľadať podľa témy…

API

Partnerské API

Základná URL je https://adyoutiser.com/api/v1. Každé volanie nesie bearer token. Chyby prichádzajú ako RFC 7807 problem dokument.

Aktualizované

Prístup

API je pre partnerov s API prístupom. Prístupové údaje prideľuje administrácia. Neexistuje samoregistrácia ani generátor kľúčov v dashboarde.

Základná URL
https://adyoutiser.com/api/v1
Auth hlavička
Authorization: Bearer <token>Hlavička X-API-Key neexistuje.
Formát chýb
application/problem+json (RFC 7807)
Rate limit
Predvolene 600 požiadaviek za minútu na prístup.

Autentifikácia

Token pošli v hlavičke Authorization. Predpona rozhoduje, ako sa číta: hodnota začínajúca na adyo_ je API kľúč, čokoľvek iné je OAuth prístupový token.

curl -H "Authorization: Bearer adyo_your_api_key" \
  "https://adyoutiser.com/api/v1/screens?city=Wien&limit=50"
API kľúč: pri každom volaní ho posielaj nezmenený.
curl -X POST "https://adyoutiser.com/api/v1/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'
OAuth: vymeň client credentials za prístupový token.
{
  "access_token": "...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "screens:read"
}
Token platí 3600 sekúnd. Obnov ho pred vypršaním.

Token endpoint má prísny limit

10 požiadaviek za minútu na IP. Token si cachuj celú hodinu, namiesto získavania nového pri každom volaní.

Limity a chyby

RozsahLimit
POST /oauth/token10 za minútu na IP.
Všetky ostatné endpointyPredvolene 600 za minútu na prístup.
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 60
Nad limitom dostaneš 429 a Retry-After 60 sekúnd.

Každé telo chyby zodpovedá RFC 7807 s typom obsahu application/problem+json.

type
Identifikátor typu chyby.
title
Krátke označenie chyby.
status
HTTP stavový kód.
detail
Čo sa pokazilo pri tomto konkrétnom volaní.
retry_after
Iba pri 429. Čakanie v sekundách.

Endpointy

MetódaCestaScope
POST/api/v1/oauth/token—
GET/api/v1/screensscreens:read
GET/api/v1/screens/{screenId}screens:read
GET/api/v1/screens/{screenId}/availabilityscreens:read
POST/api/v1/couponscoupons:write
GET/api/v1/coupons/{code}coupons:read | coupons:write
POST/api/v1/coupons/{code}/revokecoupons:write
GET/api/v1/users/lookupusers:read
POST/api/v1/landing-linkslinks:write
GET/api/v1/campaign-requestscampaign_requests:read
GET/api/v1/campaign-requests/{id}campaign_requests:read

Obrazovky. GET /screens vracia { data, pagination } s cursor, has_more a total_count. Filtre: country (2 písmená), city, orientation, bbox. limit je predvolene 50, maximum 200; stránkuje sa cez cursor.

{
  "id": "...",
  "name": "...",
  "description": "...",
  "country": "AT",
  "city": "Wien",
  "address": "...",
  "latitude": 0,
  "longitude": 0,
  "orientation": "portrait",
  "resolution_width": 1080,
  "resolution_height": 1920,
  "price_per_day_cents": 0,
  "ad_sov_pct": 0,
  "thumbnail_url": "...",
  "venue_type": "...",
  "is_active": true,
  "created_at": "..."
}
Polia jedného objektu obrazovky. Hodnoty sú zástupné, nie skutočný inventár.

404 neznamená, že neexistuje

GET /screens/{id} odpovie 404 aj vtedy, keď obrazovka existuje, ale nie je rezervovateľná.

Dostupnosť. from a to sú povinné, formát YYYY-MM-DD. Odpoveď obsahuje screen_id, from, to, max_sov_pct, used_sov_pct, available_sov_pct a price_per_day_cents.

curl -H "Authorization: Bearer adyo_your_api_key" \
  "https://adyoutiser.com/api/v1/screens/SCREEN_ID/availability?from=2026-09-01&to=2026-09-07"

Kupóny. POST /coupons odpovie 201. Povinné: discount_type (percent, amount_cents alebo free_days), discount_value väčšie ako 0, a lead_email. Voliteľné: code, max_redemptions (1–1000, predvolene 1), valid_until, lead_metadata. Bez vlastného code sa vygeneruje podľa vzoru BVCC-XXXX.

curl -X POST "https://adyoutiser.com/api/v1/coupons" \
  -H "Authorization: Bearer adyo_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "discount_type": "percent",
    "discount_value": 10,
    "lead_email": "lead@example.com",
    "max_redemptions": 1
  }'
StavKedy
400percent nad 100, alebo revoke kupónu, ktorý už nie je aktívny alebo už bol uplatnený.
409Kód je už obsadený, alebo tento lead_email už má na tvojom prístupe aktívny kupón. Jeden aktívny kupón na lead e-mail a prístup.

Používatelia. GET /users/lookup prijíma email alebo vat_uid. Dostaneš buď { "data": { "exists": false } }, alebo záznam s user_id, registered_at, has_bookings a voliteľne attribution. Atribučné dáta prídu len vtedy, keď sprostredkovanie patrí tvojmu prístupu.

Landing linky. POST /landing-links odpovie 201 a vráti url aj s UTM parametrami. utm_medium je vždy partner_api.

Žiadosti o kampaň. GET /campaign-requests filtruje podľa status (rejected, abandoned, no_inventory, converted), from, to a industry. Vidíš vždy len vlastné žiadosti.

Webhooky

UdalosťSpustí sa, keď
user.registeredSprostredkovaný používateľ sa zaregistruje.
campaign.paidKampaň je zaplatená.
coupon.redeemedJeden z tvojich kupónov je uplatnený.
campaign_request.createdPríde žiadosť o kampaň.
campaign_request.rejectedŽiadosť o kampaň je zamietnutá.
X-Adyoutiser-Signature: t=1754438400,v1=<hex>
Over si túto hlavičku, kým budeš veriť telu správy.

Opakovania

Pri chybe sa doručenie opakuje až 5-krát, s odstupmi 1 s, 5 s, 30 s, 2 min, 10 min. Potom sa doručenie považuje za vyčerpané — odpovedz rýchlo 2xx a prácu urob potom.

Súvisiace

  • Prehľad pre partnerovObrazovka patrí tebe. My predávame reklamný čas a platíme ti za kampaň. Čo to znamená v praxi.
  • Ako funguje AdyoutiserSkutočné obrazovky na skutočných adresách. Rezervuješ si podiel reklamného času — takto sa podiel delí.