API за поврзување на Вашиот систем

Техничка референца

Технички водич за развивачи на интеграции

Започнете со заедничките правила за повикување и најавувањето. Потоа следете ја постапката од прикачување медиумска датотека до активирање кампања и разгледајте го прегледот на достапните крајни точки.

Најавување

Корисничкото име не е е-пошта, туку код од осум знаци што системот го генерира при создавањето на корисникот, на пример A1B2C3D4. За интеграцијата создадете посебен корисник со најмалите потребни дозволи; потоа може да му се одземе пристапот во секое време, без да се влијае врз другите корисници.

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

Лозинката се испраќа со секое барање. Чувајте ја како таен податок, на пример во променлива на околината или во сеф за лозинки — никогаш во изворниот код, репозиториум или дневници.

Следните примери претпоставуваат дека се поставени овие променливи:

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

Примерите користат curl бидејќи не зависи од програмскиот јазик. Интерфејсот се заснова на HTTP, па може да се повикува од кој било јазик или алатка што поддржува Basic Auth, на пример Python, JavaScript, PHP, Postman или Make.

Постапка: од датотека до активна кампања

1. Преземете го идентификаторот на Компанијата. Ќе го користите во сите понатамошни повици.
2. Прикачете медиумска датотека. Во одговорот се враќа нејзиниот идентификатор.
3. Вчитајте образец за кампања. Серверот однапред го пополнува со поставките на Компанијата и со списокот на локации и уреди.
4. Уредете го образецот — име, период, целни уреди и визуел.
5. Создајте ја кампањата. Се создава како нацрт и сѐ уште не се репродуцира.
6. Активирајте ја кампањата. Системот подготвува нов план за репродукција и го испраќа до уредите.
7. Следете ги резултатите во извештајот за кампања.

1. Идентификатор на Компанијата

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

Одговор (скратен):

{
  "id": 1715714421868,
  "name": "Интеграција – е-продавница",
  "login": "A1B2C3D4",
  "company": { "id": 1698234512001, "name": "Рекламна агенција ДОО" },
  "permission": {
    "resource": 12,
    "device_layer_top": 12,
    "report_layer_top": 4
  }
}

Зачувајте ја вредноста на company.id; примерите ја користат како променлива COMPANY. Секцијата permission ги наведува дозволите на корисникот; нивното значење е опишано во Дозволи.

2. Прикачување медиумска датотека

Датотеката се испраќа како бинарно тело на барањето со PUT; нејзините својства се наведуваат во заглавијата.

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

Истиот повик во Python:

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"]

Одговорот ги содржи идентификаторот на медиумот (id) и неговиот вид (type); двете вредности ќе ги користите во визуелот на кампањата.

{
  "id": 1724832015443,
  "type": 2,
  "name": "summer-sale",
  "width": 1920,
  "height": 1080,
  "duration": 0,
  "aspectRatio": 32
}

• Големина: обични датотеки до приближно 1,1 GB, видео со проѕирност до приближно 2,1 GB. Серверот ги одбива поголемите датотеки со 413.
• Подготовка на видеото: по прикачувањето, видеото се конвертира во заднина. Подготвено е кога деталите за медиумот (GET /api/resource/single/{companyId}/{id}) содржат вредност во dt_ready. За слики, подготовката е речиси моментална.
• Заглавие што недостига: без file-mime, file-name или file-suffix серверот враќа 204 и не ја создава медиумската датотека. Секогаш проверувајте дали одговорот содржи id пред да продолжите.

3. Образец за кампања

Не составувајте ја кампањата рачно. Побарајте образец што серверот однапред го пополнува со стандарден период (еден месец од денес), поставките на Компанијата и списокот на сите локации и уреди. Секој уред во него е означен со isActive: false.

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

Пример на образец (скратен):

{
  "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": "Градски трговски центар",
      "days": [ { "day": 1, "start": "09:00", "end": "21:00" } ],
      "devices": [
        {
          "id": 1698234512201,
          "name": "Влез A",
          "screenRatio": 32,
          "isHorizontal": true,
          "isActive": false
        }
      ]
    }
  ],
  "visuals": []
}

Вредноста на settings.type го одредува режимот на репродукција на Компанијата: 2 = SLOT, 4 = IMPRESSION. Режимот го поставува добавувачот и не може да се промени преку API.

4. Уредување на образецот

• name: име на кампањата што се прикажува во администрацијата и во извештаите.
• start, end: почеток и крај на кампањата.
• isActive: поставете true за уредите на кои треба да се репродуцира кампањата.
• visuals: додајте визуел со прикачената медиумска датотека.

"visuals": [
  {
    "id": 1,
    "name": "Основен визуел",
    "isPrimary": true,
    "isCustom": true,
    "res": [
      {
        "id": 1,
        "conditionId": 0,
        "resourceId": 1724832015443,
        "name": "summer-sale",
        "duration": 10000,
        "type": 2
      }
    ]
  }
]

Образецот може да го уредите со скрипта, на пример со jq:

jq --argjson res "$RESOURCE" '
  .name = "Летна распродажба 2026"
  | .start = "2026-11-02T00:00:00"
  | .end   = "2026-11-09T00:00:00"
  | .locations[].devices[].isActive = true
  | .visuals = [{
      id: 1, name: "Основен визуел", isPrimary: true, isCustom: true,
      res: [{ id: 1, conditionId: 0, resourceId: $res,
              name: "summer-sale", duration: 10000, type: 2 }]
    }]
' campaign.json > campaign-edited.json

Ако кампањата е наменета и за хоризонтални и за вертикални екрани (isHorizontal), додајте визуел за секоја ориентација. Во спротивно, содржината на некои екрани ќе се отсече или ќе се намали. Видете Визуели на кампањите.

5. Создавање на кампањата

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)

Кампањата се создава како нацрт и не се репродуцира никаде. Одговорот ја содржи зачуваната кампања со доделен id и groupId. Во образецот веќе е поставено state: 2 (нацрт); серверот ја одбива секоја друга вредност со 409.

6. Активирање на кампањата

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

• +01:00: временската зона како отстапување од UTC според кое работи кампањата. За Средна Европа користете +01:00 во зимскиот период и +02:00 во периодот на летното сметање на времето.
• 0: очекуваниот број прикажувања за целата кампања. Важи во режимот IMPRESSION; во режимот SLOT користете 0.

Кампања со почеток денес или порано станува активна, а нејзиниот почеток се поставува на моментот на активирање. Кампања со почеток во иднина станува објавена и започнува на планираниот ден.

Системот потоа повторно го пресметува планот за репродукција и го испраќа до засегнатите уреди. За поврзаните уреди тоа обично трае неколку десетици секунди; исклучениот уред го добива планот откако ќе се воспостави врската. Проверете го капацитетот на уредите во администрацијата, видете Капацитет за кампањи.

7. Резултати од кампањата

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

Извештаите користат groupId, а не id на кампањата. Првата крајна точка враќа преглед на кампањата, а втората — број на евидентирани прикажувања. Уредите ги испраќаат записите континуирано, во пакети, па бројките не се достапни во реално време. Видете Извештај за кампања за значењето на бројките.

Паузирање, запирање и бришење

# паузирај активна кампања; повторниот повик ја продолжува
curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00/0"

# запре трајно
curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00"

# избриши
curl -u "$AUTH" -X DELETE \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN"

Крајната точка од чекор 6 работи како прекинувач: паузира активна или објавена кампања и продолжува паузирана кампања. Пред да ја повикате, проверете ја тековната состојба на кампањата (state во деталите). Запрена кампања не може повторно да се активира, но останува во списокот заедно со своите извештаи. Избришана кампања исчезнува од списокот.

Преглед на крајните точки

Патеките се релативни во однос на адресата на администрацијата. {c} го означува идентификаторот на Компанијата.

Сметка

Медиуми

Кампањи

Локации и уреди

Извештаи

Шифрарници

Вредностите од шифрарниците во JSON се запишуваат како броеви.

Состојба на кампања (state)

Видови медиуми

За документи, заглавието file-type ја користи вредноста PDF, а не DOCUMENT.

Дозволи

Интерфејсот ги применува истите дозволи како администрацијата и ги проверува при секое барање. Во одговорот при најавување, секоја област е изразена со број што е збир од поединечните права:

На пример, resource: 28 (4 + 8 + 16) значи дека корисникот може да прегледува, додава и уредува медиуми, но не и да ги брише. Повисоките вредности (128 до 1024) ги претставуваат истите права надвор од Компанијата на корисникот; на интеграцијата не ѝ се потребни.

За активирање, паузирање и запирање кампања е потребно правото Додавање. За бришење активирана кампања или медиумска датотека е потребно правото Бришење; нацрт на кампања може да се избрише и без него. Добра појдовна основа е улогата Менаџер за реклами на компанијата со отстранети непотребни права.

Кодови на грешки

Целосен пример

Скриптата ја извршува целата постапка од прикачување слика до активирање кампања на сите уреди на Компанијата. Потребни се curl и jq.

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

API="https://admin.example.org"
AUTH="${INTEGRATION_AUTH:?поставете INTEGRATION_AUTH=login:password}"
FILE="summer-sale.jpg"
NAME="Летна распродажба 2026"
FROM="2026-11-02T00:00:00"
TO="2026-11-09T00:00:00"
TZ_OFFSET="+01:00"

# 1) Идентификатор на Компанијата
COMPANY=$(curl -sf -u "$AUTH" "$API/api/public/login" | jq -r '.company.id')

# 2) прикачување медиум
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) образец за кампања
curl -sf -u "$AUTH" "$API/api/campaign/company/$COMPANY" > template.json

# 4) уредување на образецот
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: "Основен визуел", isPrimary: true, isCustom: true,
      res: [{ id: 1, conditionId: 0, resourceId: $res,
              name: $n, duration: 10000, type: 2 }]
    }]
' template.json > campaign.json

# 5) создавање нацрт
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) активирање
curl -sf -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/$TZ_OFFSET/0" > /dev/null

echo "Кампањата $CAMPAIGN е активирана, извештај: $API/api/report/$COMPANY/campaign/$GROUP"