API за свързване с вашата система

Техническа справка

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

Първо се запознайте с общите правила за извикване и с влизането. След това преминете през процедурата от качването на медиен файл до стартирането на кампания и прегледа на наличните адреси.

Вход

Потребителското име не е имейл адрес, а осемзнаков код, генериран от системата при създаването на потребителя, например A1B2C3D4. За интеграцията създайте отделен потребител с минимално необходимите права; достъпът му може да бъде премахнат по всяко време, без това да засегне другите потребители.

curl -u "A1B2C3D4:vashata-parola" https://admin.example.org/api/public/login

Паролата се изпраща с всяка заявка. Съхранявайте я като тайна, например в променлива на средата или в трезор за пароли — никога в изходния код, хранилището или журналите.

Примерите по-долу предполагат зададени променливи:

export API="https://admin.example.org"
export AUTH="A1B2C3D4:vashata-parola"

Примерите използват инструмента 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", "vashata-parola"),
        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": "Вход А",
          "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/+02:00/0"

• +02:00: часовата зона като отместване спрямо UTC, по която се ръководи кампанията. За България +02:00 през зимното и +03: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/+02:00/0"

# окончателно спиране
curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+02: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:parola}"
FILE="summer-sale.jpg"
NAME="Лятно намаление 2026"
FROM="2026-11-02T00:00:00"
TO="2026-11-09T00:00:00"
TZ_OFFSET="+02: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"