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.
| Feladat | Ajánlott megoldás |
|---|---|
| Néhány médiafájl feltöltése és kampány indítása | Adminisztráció |
| Tartalom rendszeres, de kézi frissítése | Adminisztráció |
| Médiafájlok tömeges feltöltése saját rendszerből | API |
| Kampányok automatikus létrehozása saját ütemezőből | API |
| Kampányeredmények átvétele saját jelentéskészítő rendszerbe | API |
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/loginA 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
- Kérje le a Vállalat azonosítóját. Ezt fogja használni minden további hívásban.
- Töltsön fel egy médiafájlt. A válasz visszaadja annak azonosítóját.
- 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.
- Szerkessze a sablont – név, időszak, céleszközök és vizuális anyag.
- Hozza létre a kampányt. Piszkozatként jön létre, és még nem játszódik le.
- Aktiválja a kampányt. A rendszer új lejátszási tervet készít, és elküldi az eszközöknek.
- 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éc | Tartalom |
|---|---|
file-type | Médiatípus az alábbi táblázat szerint: Médiatípusok , például: IMAGE. |
file-mime | A fájl MIME-típusa, például: image/jpeg, video/mp4 vagy application/pdf. |
file-name | Az 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-suffix | A 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 adt_readymezőben. A képek előkészítése gyakorlatilag azonnali. - Hiányzó fejléc: e nélkül:
file-mime,file-namevagyfile-suffixa 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:idmielő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.jsonSablonpé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éttrueé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 |
|---|---|
id | A kampányon belül egyedi tetszőleges szám; létrehozáskor a kiszolgáló újraszámozza. |
isPrimary | true a fő vizuális anyagnál, false a többinél. |
isCustom | true – a vizuális anyag ehhez a kampányhoz tartozik. |
resourceId | A médiafájl azonosítója a 2. lépésből. |
duration | Megjelenítési időtartam milliszekundumban. |
type | Mé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.jsonHa 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 | Útvonal | Rendeltetés |
|---|---|---|
GET | /api/public/login | Ellenőrzi a hitelesítési adatokat, és visszaadja a felhasználói profilt, beleértve ezt: company.id. |
GET | /api/user/info | A bejelentkezett felhasználó adatai. |
GET | /api/user/check | A hitelesítési adatok érvényességének gyors ellenőrzése. |
Médiafájlok
| Metódus | Útvonal | Rendeltetés |
|---|---|---|
PUT | /api/resource/single/{c} | Fájl feltöltése (file-* fejlécek, törzs = bináris adatok). |
GET | /api/resource/listing/{c}/1 | Mé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 | Útvonal | Rendelteté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 | Útvonal | Rendelteté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 | Útvonal | Rendeltetés |
|---|---|---|
GET | /api/report/{c}/campaign/{groupId} | Kampányösszesítés. |
GET | /api/report/{c}/campaign/{groupId}/impression | Rö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 | Állapot | Jelentés |
|---|---|---|
2 | Piszkozat | Elmentett kampány, amely nem játszódik le. |
4 | Közzétett | Aktivált kampány, amely a kezdőnapjára vár. |
8 | Aktív | A kampány lejátszása folyamatban van. |
16 | Befejezett | A kampány záróidőpontja elmúlt. |
32 | Leállított | A kampányt véglegesen leállították. |
64 | Törölt | A kampányt törölték. |
128 | Szüneteltetett | A lejátszás átmenetileg szünetel. |
Médiatípusok
type érték | file-type fejléc | Médiafájlok |
|---|---|---|
2 | IMAGE | Kép (JPG, PNG, WebP) |
4 | VIDEO | Videó |
8 | PDF | PDF-dokumentum |
16 | WWW_APP | Webalkalmazás |
32 | TEXT | Hosszú szöveg |
128 | VIDEO_ALPHA | Átlátszó hátterű videó |
256 | AUDIO | Hang |
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ék | Jog a saját Vállalaton belül |
|---|---|
4 | Megtekintés |
8 | Hozzáadás |
16 | Szerkesztés |
32 | Tö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ület | A leírt munkafolyamat minimuma |
|---|---|
resource – médiafájlok | 12 (megtekintés, hozzáadás) |
device_layer_top – kampányok | 12 (megtekintés, hozzáadás) |
report_layer_top – kampányjelentések | 4 (megtekintés) |
location – helyszínek | 4 (megtekintés) |
device_info – eszközök | 4 (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ód | Jelentés | Teendő |
|---|---|---|
400 | Hibás kérés | Ellenőrizze az útvonalban szereplő azonosítókat, az időzónát és a kötelező adatokat. |
401 | Hiányzó jogosultság | A 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. |
404 | Nem található | A rekord nem létezik, vagy nem az adott Vállalathoz tartozik. |
406 | Nem 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és | A létrehozott kampány nem piszkozat. |
413 | Túl nagy fájl | Csökkentse a fájlméretet; a korlátokat a 2. lépés ismerteti. |
500 | Kiszolgálóhiba | Próbálja újra később; ha a hiba fennmarad, forduljon a szolgáltatóhoz. |
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"Kapcsolódó témák és következő lépések
← Vissza az áttekintéshez – Integrációk és tartalomkészítés
Forduljon szoftverszolgáltatójához.
