Dokumentáció / Integrációk és tartalomkészítés / API saját rendszer csatlakoztatásához

API saját rendszer csatlakoztatásához

Bevezetés és tájékozódás

Médiafájlok, kampányok és jelentések kezelése közvetlenül saját rendszeréből, az adminisztrációba való bejelentkezés nélkül.

Mire szolgál az API

Az API az ügyfél saját rendszerét – például webáruházat, reklámkampány-tervezőt vagy belső katalógust – közvetlenül az eszközök tartalomkezeléséhez csatlakoztatja. Rendszere médiafájlokat tölthet fel, kampányokat hozhat létre és indíthat el, valamint lekérheti azok eredményeit anélkül, hogy valakinek be kellene jelentkeznie az adminisztrációba, és kézzel kellene elvégeznie ezeket a műveleteket.

A webes adminisztráció ugyanezt a felületet használja. Az API ezért a bejelentkezett felhasználó jogosultságain belül ugyanazokat a műveleteket támogatja, mint az adminisztráció.

Mikor érdemes az API-t használni

Néhány médiafájl alkalmi feltöltéséhez és kampány kézi indításához az adminisztráció célszerűbb: a kampányvarázsló előnézetet mutat, és ellenőrzi a médiaformátumokat és az eszközkapacitást. Az API akkor hasznos, amikor a kézi munka már lassítja a folyamatot.

FeladatAjánlott megoldás
Néhány médiafájl feltöltése és kampány indításaAdminisztráció
Tartalom rendszeres, de kézi frissítéseAdminisztráció
Médiafájlok tömeges feltöltése saját rendszerbőlAPI
Kampányok automatikus létrehozása saját ütemezőbőlAPI
Kampányeredmények átvétele saját jelentéskészítő rendszerbeAPI

A felület nincs verziózva, és a platform fejlődésével változhat. Integráció élesítése előtt értesítse szoftverszolgáltatóját, és rendszerfrissítések után ellenőrizze a további működését.

Kinek szól az útmutató, és ki miért felelős

  • A platform szolgáltatója üzemelteti a felületet, megadja az adminisztráció címét, és beállítja a Vállalat lejátszási módját.
  • Az ügyfél határozza meg az integráció terjedelmét, és létrehoz a Vállalatán belül egy külön, megfelelő jogosultságú felhasználót – lásd: Felhasználó létrehozása és első bejelentkezés.
  • Az integráció fejlesztője csatlakoztatja az ügyfél rendszerét a felülethez. Az útmutató műszaki utasításai és kódpéldái ennek a fejlesztőnek szólnak. Ha saját maga fejleszti az integrációt, ezt a szerepet is Ön tölti be.

Műszaki referencia

Műszaki útmutató integrációfejlesztőknek

Kezdje a közös hívási szabályokkal és a bejelentkezéssel. Ezután kövesse a médiafájl feltöltésétől a kampány elindításáig tartó munkafolyamatot, és tekintse meg az elérhető végpontok áttekintését.

Közös hívási szabályok

  • Cím: a felület az adminisztrációval azonos címen fut; minden útvonal ezzel kezdődik: /api/. A példákban a címet ez helyettesíti: https://admin.example.org. Ha van tesztkörnyezet, annak címét a szolgáltató adja meg.
  • Bejelentkezés: minden kérés HTTP Basic Auth használatával tartalmazza a hitelesítési adatokat. Nincsenek munkamenetek vagy tokenek.
  • Adatformátum: a kérés- és választörzsek JSON-formátumúak. Kivétel a fájlfeltöltés, ahol a törzs a nyers bináris adatokat tartalmazza.
  • Azonosítók és értékek: az azonosítók egész számok. A dátum és idő formátuma: YYYY-MM-DDTHH:MM:SS, a megjelenítési időtartamok pedig milliszekundumban értendők (10000 = 10 mp).
  • Eredmény: a sikert az alábbi állapot igazolja: 200. Ez a kérés elfogadását jelenti, nem azt, hogy a tartalom már lejátszódik az eszközökön.

Bejelentkezés

A bejelentkezési azonosító nem e-mail-cím, hanem a felhasználó létrehozásakor a rendszer által generált nyolckarakteres kód, például: A1B2C3D4. Az integrációhoz hozzon létre külön felhasználót a minimálisan szükséges jogosultságokkal; ennek hozzáférése később bármikor visszavonható más felhasználók érintése nélkül.

curl -u "A1B2C3D4:your-password" https://admin.example.org/api/public/login

A jelszó minden kéréssel továbbításra kerül. Tárolja titokként, például környezeti változóban vagy jelszótárolóban – soha ne forráskódban, adattárban vagy naplókban.

Az alábbi példák feltételezik, hogy ezek a változók be vannak állítva:

export API="https://admin.example.org"
export AUTH="A1B2C3D4:your-password"

A példák a curl eszközt használják, mert nem kötődik programozási nyelvhez. A felület szabványos HTTP-alapú, ezért bármely Basic Auth-t támogató nyelvből vagy eszközből hívható, például Pythonból, JavaScriptből, PHP-ból, Postmanből vagy Make-ből.

Munkafolyamat: a fájltól a futó kampányig

  1. Kérje le a Vállalat azonosítóját. Ezt fogja használni minden további hívásban.
  2. Töltsön fel egy médiafájlt. A válasz visszaadja annak azonosítóját.
  3. Töltsön be egy kampánysablont. A kiszolgáló előre kitölti a Vállalat beállításaival, valamint a helyszínek és eszközök listájával.
  4. Szerkessze a sablont – név, időszak, céleszközök és vizuális anyag.
  5. Hozza létre a kampányt. Piszkozatként jön létre, és még nem játszódik le.
  6. Aktiválja a kampányt. A rendszer új lejátszási tervet készít, és elküldi az eszközöknek.
  7. Kövesse az eredményeket a kampányjelentésben.

1. A Vállalat azonosítója

curl -u "$AUTH" "$API/api/public/login"

Válasz (rövidítve):

{
  "id": 1715714421868,
  "name": "Integration – e-shop",
  "login": "A1B2C3D4",
  "company": { "id": 1698234512001, "name": "Advertising Agency Ltd." },
  "permission": {
    "resource": 12,
    "device_layer_top": 12,
    "report_layer_top": 4
  }
}

Tárolja a company.id értékét; a példák ezt a COMPANY változóként használják. A permission szakasz felsorolja a felhasználó jogosultságait; jelentésüket a Jogosultságok rész ismerteti.

2. Médiafájl feltöltése

A fájl a kérés bináris törzseként, PUT metódussal kerül elküldésre; tulajdonságai a fejlécekben szerepelnek.

curl -u "$AUTH" -X PUT \
  "$API/api/resource/single/$COMPANY" \
  -H "file-type: IMAGE" \
  -H "file-mime: image/jpeg" \
  -H "file-name: summer-sale.jpg" \
  -H "file-suffix: jpg" \
  --data-binary @summer-sale.jpg
FejlécTartalom
file-typeMédiatípus az alábbi táblázat szerint: Médiatípusok , például: IMAGE.
file-mimeA fájl MIME-típusa, például: image/jpeg, video/mp4 vagy application/pdf.
file-nameAz adminisztrációban megjelenő médianév; a kiszolgáló eltávolítja a kiterjesztést. A nem ASCII-karaktereket tartalmazó neveket URL-kódolással adja meg (encodeURIComponent).
file-suffixA fájlkiterjesztés pont nélkül.

Ugyanez a hívás Pythonban:

import requests

with open("summer-sale.jpg", "rb") as f:
    r = requests.put(
        f"{API}/api/resource/single/{COMPANY}",
        auth=("A1B2C3D4", "your-password"),
        headers={
            "file-type": "IMAGE",
            "file-mime": "image/jpeg",
            "file-name": "summer-sale.jpg",
            "file-suffix": "jpg",
        },
        data=f,
    )
r.raise_for_status()
resource_id = r.json()["id"]

A válasz tartalmazza a médiafájl azonosítóját (id) és típusát (type); mindkét értéket felhasználja a kampány vizuális anyagánál.

{
  "id": 1724832015443,
  "type": 2,
  "name": "summer-sale",
  "width": 1920,
  "height": 1080,
  "duration": 0,
  "aspectRatio": 32
}
  • Méret: szokásos fájloknál körülbelül 1,1 GB-ig, átlátszóságot tartalmazó videóknál körülbelül 2,1 GB-ig. A nagyobb fájlokat a kiszolgáló az alábbi hibával utasítja el: 413.
  • Videó előkészítése: a videó a feltöltés után a háttérben konvertálódik. Akkor áll készen, ha a médiafájl részleteiben (GET /api/resource/single/{companyId}/{id}) érték szerepel a dt_ready mezőben. A képek előkészítése gyakorlatilag azonnali.
  • Hiányzó fejléc: e nélkül: file-mime, file-name vagy file-suffix a kiszolgáló ezt adja vissza: 204 , és nem hozza létre a médiafájlt. Mindig ellenőrizze, hogy a válasz tartalmazza-e ezt: id mielőtt továbblépne.

3. Kampánysablon

Ne kézzel állítsa össze a kampányt. Kérjen sablont, amelyet a kiszolgáló előre kitölt alapértelmezett időszakkal (mától egy hónap), a Vállalat beállításaival, valamint az összes helyszín és eszköz listájával. A benne szereplő minden eszköz megjelölése: isActive: false.

curl -u "$AUTH" "$API/api/campaign/company/$COMPANY" > campaign.json

Sablonpélda (rövidítve):

{
  "id": -1,
  "groupId": -1,
  "state": 2,
  "name": "",
  "start": "2026-11-01T10:00:00",
  "end": "2026-12-01T10:00:00",
  "isCommercial": true,
  "isNonCommercial": false,
  "settings": {
    "type": 2,
    "companyCount": 10,
    "companyDuration": 10000,
    "campaignCount": 1,
    "campaignDuration": 10000
  },
  "locations": [
    {
      "id": 1698234512100,
      "name": "City Mall",
      "days": [ { "day": 1, "start": "09:00", "end": "21:00" } ],
      "devices": [
        {
          "id": 1698234512201,
          "name": "Entrance A",
          "screenRatio": 32,
          "isHorizontal": true,
          "isActive": false
        }
      ]
    }
  ],
  "visuals": []
}

A settings.type értéke határozza meg a Vállalat lejátszási módját: 2 = SLOT, 4 = IMPRESSION. A módot a szolgáltató állítja be, és API-n keresztül nem változtatható meg.

4. A sablon szerkesztése

  • name: az adminisztrációban és a jelentésekben megjelenő kampánynév.
  • start, end: a kampány kezdete és vége.
  • isActive: állítsa az értékét true értékre azoknál az eszközöknél, amelyeken a kampánynak le kell játszódnia.
  • visuals: adjon hozzá vizuális anyagot a feltöltött médiafájllal.
"visuals": [
  {
    "id": 1,
    "name": "Main visual",
    "isPrimary": true,
    "isCustom": true,
    "res": [
      {
        "id": 1,
        "conditionId": 0,
        "resourceId": 1724832015443,
        "name": "summer-sale",
        "duration": 10000,
        "type": 2
      }
    ]
  }
]
MezőJelentés
idA kampányon belül egyedi tetszőleges szám; létrehozáskor a kiszolgáló újraszámozza.
isPrimarytrue a fő vizuális anyagnál, false a többinél.
isCustomtrue – a vizuális anyag ehhez a kampányhoz tartozik.
resourceIdA médiafájl azonosítója a 2. lépésből.
durationMegjelenítési időtartam milliszekundumban.
typeMédiatípus; ugyanaz az érték, amelyet a feltöltés itt adott vissza: type.

A sablon szkripttel is szerkeszthető, például ezzel: jq:

jq --argjson res "$RESOURCE" '
  .name = "Summer sale 2026"
  | .start = "2026-11-02T00:00:00"
  | .end   = "2026-11-09T00:00:00"
  | .locations[].devices[].isActive = true
  | .visuals = [{
      id: 1, name: "Main visual", isPrimary: true, isCustom: true,
      res: [{ id: 1, conditionId: 0, resourceId: $res,
              name: "summer-sale", duration: 10000, type: 2 }]
    }]
' campaign.json > campaign-edited.json

Ha a kampány fekvő és álló képernyőket is céloz (isHorizontal), mindkét tájoláshoz adjon hozzá vizuális anyagot. Ellenkező esetben egyes képernyőkön a tartalom vágva vagy lekicsinyítve jelenik meg. Lásd: A kampány vizuális anyagai – részletes tudnivalók.

5. A kampány létrehozása

curl -u "$AUTH" -X POST \
  "$API/api/campaign/company/$COMPANY" \
  -H "Content-Type: application/json" \
  --data @campaign-edited.json \
  -o response.json

export CAMPAIGN=$(jq -r '.id' response.json)
export GROUP=$(jq -r '.groupId' response.json)

A kampány piszkozatként jön létre, és sehol nem játszódik le. A válasz tartalmazza az elmentett kampányt a hozzárendelt id és groupId értékekkel. A sablonban már szerepel a state: 2 érték (piszkozat); minden más értéket a kiszolgáló a 409 hibával utasít el.

6. A kampány aktiválása

curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00/0"
  • +01:00: időzóna az UTC-től való eltolásként, amelyet a kampány követ. Közép-Európában télen ezt használja: +01:00 , nyári időszámításkor pedig ezt: +02:00 .
  • 0: a teljes kampány várható megjelenítésszáma. IMPRESSION módban érvényes; SLOT módban ezt használja: 0.

A ma vagy korábban kezdődő kampány aktívvá válik, és kezdete az aktiválás pillanatára módosul. A jövőbeli kezdésű kampány közzétett állapotba kerül, és az ütemezett napon indul.

A rendszer ezután újraszámítja a lejátszási tervet, és elküldi az érintett eszközöknek. Csatlakoztatott eszköznél ez általában néhány tíz másodpercet vesz igénybe; a kapcsolat nélküli eszköz a kapcsolat helyreállásakor kapja meg a tervet. Az eszközkapacitást az adminisztrációban ellenőrizze, lásd: Kampánykapacitás.

7. Kampányeredmények

curl -u "$AUTH" "$API/api/report/$COMPANY/campaign/$GROUP"
curl -u "$AUTH" "$API/api/report/$COMPANY/campaign/$GROUP/impression"

A jelentések a groupId értéket használják, nem pedig a kampány id értékét. Az első végpont a kampány összesítését, a második a rögzített megjelenítések számát adja vissza. Az eszközök folyamatosan, kötegekben küldik a bejegyzéseket, ezért az adatok nem valós időben érhetők el. Az adatok jelentéséhez lásd a Kampányjelentés útmutatóját.

Szüneteltetés, leállítás és törlés

# pause an active campaign; calling it again resumes it
curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00/0"

# stop permanently
curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00"

# delete
curl -u "$AUTH" -X DELETE \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN"

A 6. lépés végpontja kapcsolóként működik: szünetelteti az aktív vagy közzétett kampányt, a szüneteltetettet pedig folytatja. Meghívása előtt ellenőrizze a kampány aktuális állapotát (state a részletekben). A leállított kampány nem indítható újra, de a jelentéseivel együtt a listában marad. A törölt kampány eltűnik a listából.

Végpontok áttekintése

Az útvonalak az adminisztráció címéhez képest relatívak. {c} a Vállalat azonosítóját jelöli.

Fiók

MetódusÚtvonalRendeltetés
GET/api/public/loginEllenőrzi a hitelesítési adatokat, és visszaadja a felhasználói profilt, beleértve ezt: company.id.
GET/api/user/infoA bejelentkezett felhasználó adatai.
GET/api/user/checkA hitelesítési adatok érvényességének gyors ellenőrzése.

Médiafájlok

MetódusÚtvonalRendeltetés
PUT/api/resource/single/{c}Fájl feltöltése (file-* fejlécek, törzs = bináris adatok).
GET/api/resource/listing/{c}/1Médiafájlok listája; 1 = nincs típuskorlátozás.
GET/api/resource/single/{c}/{id}Médiafájl részletei.
DELETE/api/resource/single/{c}/{id}Médiafájl törlése.

Kampányok

MetódusÚtvonalRendeltetés
GET/api/campaign/company/{c}Új kampány sablonja.
POST/api/campaign/company/{c}Kampány létrehozása piszkozatként.
PATCH/api/campaign/company/{c}Meglévő kampány módosításainak mentése.
POST/api/campaign/listing/company/{c}Kampányok listája; a kéréstörzs szűrőt tartalmaz.
GET/api/campaign/company/{c}/{id}Kampány részletei.
GET/api/campaign/company/{c}/group/{groupId}Kampány részletei ez alapján: groupId.
PATCH/api/campaign/company/{c}/{id}/{tz}/{impressions}Kampány aktiválása, szüneteltetése vagy folytatása.
PATCH/api/campaign/company/{c}/{id}/{tz}Kampány végleges leállítása.
DELETE/api/campaign/company/{c}/{id}Kampány törlése.

Helyszínek és eszközök

MetódusÚtvonalRendeltetés
GET/api/location/listing/{c}Helyszínek listája.
GET/api/location/single/{id}Helyszín részletei, beleértve a nyitvatartási időt.
GET/api/device/listing/{c}/{locationId}A helyszín eszközeinek listája.
GET/api/device/single/{id}/{lang}Eszköz részletei; lang nyelvkód, például: en.

Jelentések

MetódusÚtvonalRendeltetés
GET/api/report/{c}/campaign/{groupId}Kampányösszesítés.
GET/api/report/{c}/campaign/{groupId}/impressionRögzített megjelenítések száma.

Kódtáblák

A kódtáblák értékei számként szerepelnek a JSON-ban.

Kampányállapot (state)

ÉrtékÁllapotJelentés
2PiszkozatElmentett kampány, amely nem játszódik le.
4KözzétettAktivált kampány, amely a kezdőnapjára vár.
8AktívA kampány lejátszása folyamatban van.
16BefejezettA kampány záróidőpontja elmúlt.
32LeállítottA kampányt véglegesen leállították.
64TöröltA kampányt törölték.
128SzüneteltetettA lejátszás átmenetileg szünetel.

Médiatípusok

type értékfile-type fejlécMédiafájlok
2IMAGEKép (JPG, PNG, WebP)
4VIDEOVideó
8PDFPDF-dokumentum
16WWW_APPWebalkalmazás
32TEXTHosszú szöveg
128VIDEO_ALPHAÁtlátszó hátterű videó
256AUDIOHang

Dokumentumoknál a file-type fejléc értéke PDF, nem pedig DOCUMENT.

Jogosultságok

A felület ugyanazokat a jogosultságokat alkalmazza, mint az adminisztráció, és minden kérésnél ellenőrzi őket. A bejelentkezési válaszban minden területet egy szám fejez ki, amely az egyes jogok összege:

ÉrtékJog a saját Vállalaton belül
4Megtekintés
8Hozzáadás
16Szerkesztés
32Törlés

Például: resource: 28 (4 + 8 + 16) azt jelenti, hogy a felhasználó megtekintheti, hozzáadhatja és szerkesztheti a médiafájlokat, de nem törölheti őket. A nagyobb értékek (128 – 1024) ugyanezeket a jogokat jelentik a saját Vállalaton kívül; az integrációnak ezekre nincs szüksége.

TerületA leírt munkafolyamat minimuma
resource – médiafájlok12 (megtekintés, hozzáadás)
device_layer_top – kampányok12 (megtekintés, hozzáadás)
report_layer_top – kampányjelentések4 (megtekintés)
location – helyszínek4 (megtekintés)
device_info – eszközök4 (megtekintés)

Kampány aktiválásához, szüneteltetéséhez és leállításához Hozzáadás jog szükséges. Aktivált kampány vagy médiafájl törléséhez Törlés jog kell; kampánypiszkozat e jog nélkül is törölhető. Jó kiindulópont a Vállalati hirdetéskezelő szerepkör, a szükségtelen jogok eltávolításával.

Hibakódok

KódJelentésTeendő
400Hibás kérésEllenőrizze az útvonalban szereplő azonosítókat, az időzónát és a kötelező adatokat.
401Hiányzó jogosultságA felhasználónak nincs meg a szükséges joga vagy hozzáférése a Vállalathoz. Kampányoknál leggyakrabban a Hozzáadás jog hiányzik.
404Nem találhatóA rekord nem létezik, vagy nem az adott Vállalathoz tartozik.
406Nem elfogadhatóÉrvénytelen hitelesítési adatok, vagy a kampány olyan állapotban van, amelyből nem engedélyezett a kért átmenet, például leállított.
409ÁllapotütközésA létrehozott kampány nem piszkozat.
413Túl nagy fájlCsökkentse a fájlméretet; a korlátokat a 2. lépés ismerteti.
500KiszolgálóhibaPróbálja újra később; ha a hiba fennmarad, forduljon a szolgáltatóhoz.
Megvalósítási ajánlások

Először tesztkörnyezetben vagy a nyilvánosság számára nem látható eszközön tesztelje az integrációt – az aktivált kampány az éles eszközökön ténylegesen lejátszódik. A helyszín nyitvatartási idején kívül nem játszódik le tartalom, még egész napra ütemezett kampánynál sem.

A médiafájlok és kampányok azonosítóit (id, groupId) tárolja saját rendszerében; a felület nem támogat kampánynév szerinti keresést. A médiafájlokat egyenként töltse fel, és ne kérjen jelentést néhány percnél gyakrabban. Csak az ebben az útmutatóban felsorolt végpontokra támaszkodjon.

Teljes példa

A szkript a kép feltöltésétől a kampány aktiválásáig tartó teljes folyamatot végrehajtja a Vállalat összes eszközén. Szükséges hozzá: curl és jq.

#!/usr/bin/env bash
set -euo pipefail

API="https://admin.example.org"
AUTH="${INTEGRATION_AUTH:?set INTEGRATION_AUTH=login:password}"
FILE="summer-sale.jpg"
NAME="Summer sale 2026"
FROM="2026-11-02T00:00:00"
TO="2026-11-09T00:00:00"
TZ_OFFSET="+01:00"

# 1) Company identifier
COMPANY=$(curl -sf -u "$AUTH" "$API/api/public/login" | jq -r '.company.id')

# 2) upload media
RESOURCE=$(curl -sf -u "$AUTH" -X PUT \
  "$API/api/resource/single/$COMPANY" \
  -H "file-type: IMAGE" \
  -H "file-mime: image/jpeg" \
  -H "file-name: $FILE" \
  -H "file-suffix: jpg" \
  --data-binary "@$FILE" | jq -r '.id')

# 3) campaign template
curl -sf -u "$AUTH" "$API/api/campaign/company/$COMPANY" > template.json

# 4) edit the template
jq --argjson res "$RESOURCE" --arg n "$NAME" --arg from "$FROM" --arg to "$TO" '
  .name = $n
  | .start = $from
  | .end = $to
  | .locations[].devices[].isActive = true
  | .visuals = [{
      id: 1, name: "Main visual", isPrimary: true, isCustom: true,
      res: [{ id: 1, conditionId: 0, resourceId: $res,
              name: $n, duration: 10000, type: 2 }]
    }]
' template.json > campaign.json

# 5) create a draft
RESPONSE=$(curl -sf -u "$AUTH" -X POST \
  "$API/api/campaign/company/$COMPANY" \
  -H "Content-Type: application/json" \
  --data @campaign.json)
CAMPAIGN=$(echo "$RESPONSE" | jq -r '.id')
GROUP=$(echo "$RESPONSE" | jq -r '.groupId')

# 6) activate
curl -sf -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/$TZ_OFFSET/0" > /dev/null

echo "Campaign $CAMPAIGN activated, report: $API/api/report/$COMPANY/campaign/$GROUP"
Nem találta meg, amit keresett?
Forduljon szoftverszolgáltatójához.