API zur Anbindung Ihres Systems

Technische Referenz

Technischer Leitfaden für Integrationsentwickler

Beginnen Sie mit den allgemeinen Aufrufkonventionen und der Anmeldung. Folgen Sie dann dem Ablauf vom Medienupload bis zum Kampagnenstart und nutzen Sie die Übersicht der verfügbaren Endpunkte.

Anmeldung

Der Anmeldename ist keine E-Mail-Adresse, sondern ein beim Anlegen des Benutzers automatisch erzeugter Code aus acht Zeichen, zum Beispiel A1B2C3D4. Erstellen Sie für die Integration einen separaten Benutzer mit den minimal erforderlichen Berechtigungen. Sein Zugriff kann dann jederzeit ohne Auswirkungen auf andere Benutzer widerrufen werden.

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

Das Passwort wird bei jeder Anfrage übermittelt. Speichern Sie es als Geheimnis, etwa in einer Umgebungsvariablen oder einem Passworttresor, niemals im Quellcode, in einem Repository oder in Protokollen.

Die folgenden Beispiele setzen voraus, dass diese Variablen gesetzt sind:

export API="https://admin.example.org"
export AUTH="A1B2C3D4:ihr-passwort"

Die Beispiele verwenden curl, da es von keiner Programmiersprache abhängt. Die Schnittstelle basiert auf HTTP und lässt sich daher mit jeder Sprache und jedem Werkzeug aufrufen, das Basic Auth unterstützt, etwa Python, JavaScript, PHP, Postman oder Make.

Ablauf: von der Datei zur laufenden Kampagne

1. Unternehmenskennung abrufen. Sie benötigen sie für alle weiteren Aufrufe.
2. Mediendatei hochladen. Die Antwort enthält seine Kennung.
3. Kampagnenvorlage laden. Der Server füllt sie mit den Unternehmenseinstellungen sowie der Standort- und Geräteliste vor.
4. Vorlage bearbeiten : Name, Zeitraum, Zielgeräte und Motiv.
5. Kampagne erstellen. Sie wird als Entwurf erstellt und noch nicht abgespielt.
6. Kampagne aktivieren. Das System erstellt einen neuen Wiedergabeplan und sendet ihn an die Geräte.
7. Ergebnisse im Kampagnenbericht verfolgen.

1. Unternehmenskennung

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

Antwort (gekürzt):

{
  "id": 1715714421868,
  "name": "Integration – Onlineshop",
  "login": "A1B2C3D4",
  "company": { "id": 1698234512001, "name": "Werbeagentur GmbH" },
  "permission": {
    "resource": 12,
    "device_layer_top": 12,
    "report_layer_top": 4
  }
}

Speichern Sie den Wert von company.id; die Beispiele verwenden ihn als Variable COMPANY. Der Abschnitt permission listet die Benutzerberechtigungen auf. Ihre Bedeutung finden Sie unter Berechtigungen.

2. Mediendatei hochladen

Die Datei wird als binärer Anfragekörper mit PUT gesendet; ihre Eigenschaften stehen in den Headern.

curl -u "$AUTH" -X PUT \
  "$API/api/resource/single/$COMPANY" \
  -H "file-type: IMAGE" \
  -H "file-mime: image/jpeg" \
  -H "file-name: sommeraktion.jpg" \
  -H "file-suffix: jpg" \
  --data-binary @sommeraktion.jpg

Derselbe Aufruf in Python:

import requests

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

Die Antwort enthält die Medienkennung (id) und den Medientyp (type). Beide Werte werden im Kampagnenmotiv verwendet.

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

• Größe: Normale Dateien bis etwa 1,1 GB, Videos mit Transparenz bis etwa 2,1 GB. Größere Dateien lehnt der Server mit 413.
• Videoaufbereitung: Videos werden nach dem Upload im Hintergrund konvertiert. Sie sind bereit, sobald die Mediendetails (GET /api/resource/single/{companyId}/{id}) einen Wert in dt_ready enthalten. Bilder sind praktisch sofort bereit.
• Fehlender Header: Ohne file-mime, file-name oder file-suffix gibt der Server 204 zurück und erstellt keine Mediendatei. Prüfen Sie stets, ob die Antwort id enthält, bevor Sie fortfahren.

3. Kampagnenvorlage

Stellen Sie die Kampagne nicht von Hand zusammen. Fordern Sie eine Vorlage an. Der Server füllt sie mit einem Standardzeitraum von einem Monat ab heute, den Unternehmenseinstellungen und sämtlichen Standorten und Geräten vor. Jedes Gerät ist darin mit isActive: false.

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

Vorlagenbeispiel (gekürzt):

{
  "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": "Einkaufszentrum Stadtmitte",
      "days": [ { "day": 1, "start": "09:00", "end": "21:00" } ],
      "devices": [
        {
          "id": 1698234512201,
          "name": "Eingang A",
          "screenRatio": 32,
          "isHorizontal": true,
          "isActive": false
        }
      ]
    }
  ],
  "visuals": []
}

Der Wert von settings.type bestimmt den Wiedergabemodus des Unternehmens: 2 = SLOT, 4 = IMPRESSION. Der Anbieter legt den Modus fest; er kann nicht über die API geändert werden.

4. Vorlage bearbeiten

• name: Kampagnenname in Verwaltung und Berichten.
• start, end: Beginn und Ende der Kampagne.
• isActive: auf true für die Geräte setzen, auf denen die Kampagne laufen soll.
• visuals: Motiv mit der hochgeladenen Mediendatei hinzufügen.

"visuals": [
  {
    "id": 1,
    "name": "Primäres Motiv",
    "isPrimary": true,
    "isCustom": true,
    "res": [
      {
        "id": 1,
        "conditionId": 0,
        "resourceId": 1724832015443,
        "name": "sommeraktion",
        "duration": 10000,
        "type": 2
      }
    ]
  }
]

Die Vorlage lässt sich per Skript bearbeiten, etwa mit jq:

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

Wenn die Kampagne auf Bildschirmen im Quer- und Hochformat laufen soll (isHorizontal), fügen Sie für jede Ausrichtung ein Motiv hinzu. Andernfalls werden Inhalte auf einigen Bildschirmen beschnitten oder verkleinert. Siehe Kampagnenmotive für weitere Informationen.

5. Kampagne erstellen

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)

Die Kampagne wird als Entwurf erstellt und nirgends abgespielt. Die Antwort enthält die gespeicherte Kampagne mit den zugewiesenen Werten id und groupId. Die Vorlage enthält bereits state: 2 (Entwurf); jeden anderen Wert lehnt der Server mit 409.

6. Kampagne aktivieren

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

• +01:00: Zeitzone als UTC-Abweichung, nach der sich die Kampagne richtet. Verwenden Sie für Mitteleuropa +01:00 im Winter und +02:00 während der Sommerzeit.
• 0: erwartete Anzahl der Einblendungen für die gesamte Kampagne. Gilt im IMPRESSION-Modus; verwenden Sie im SLOT-Modus 0.

Eine Kampagne mit Beginn heute oder früher wird aktiv; ihr Beginn wird auf den Aktivierungszeitpunkt gesetzt. Eine Kampagne mit künftigem Beginn wird veröffentlicht und startet am geplanten Tag.

Anschließend berechnet das System den Wiedergabeplan neu und sendet ihn an die betroffenen Geräte. Bei verbundenen Geräten dauert dies üblicherweise einige zehn Sekunden. Ein getrenntes Gerät erhält den Plan nach Wiederherstellung der Verbindung. Prüfen Sie die Gerätekapazität in der Verwaltung; siehe Kampagnenkapazität.

7. Kampagnenergebnisse

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

Berichte verwenden groupId und nicht die Kampagnenkennung id. Der erste Endpunkt liefert die Kampagnenübersicht, der zweite die Anzahl erfasster Einblendungen. Geräte senden laufend Datensätze in Paketen; die Zahlen stehen daher nicht in Echtzeit bereit. Siehe Kampagnenbericht für die Bedeutung der Zahlen.

Pausieren, Beenden und Löschen

# Aktive Kampagne pausieren; ein erneuter Aufruf setzt sie fort
curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00/0"

# Endgültig beenden
curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00"

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

Der Endpunkt aus Schritt 6 ist ein Umschalter: Er pausiert aktive oder veröffentlichte Kampagnen und setzt pausierte Kampagnen fort. Prüfen Sie vor dem Aufruf den aktuellen Kampagnenstatus (state in den Details). Eine beendete Kampagne kann nicht neu gestartet werden, bleibt aber mit ihren Berichten in der Liste. Eine gelöschte Kampagne verschwindet aus der Liste.

Endpunktübersicht

Pfade sind relativ zur Verwaltungsadresse. {c} steht für die Unternehmenskennung.

Konto

Medien

Kampagnen

Standorte und Geräte

Berichte

Wertelisten

Werte aus Wertelisten werden in JSON als Zahlen angegeben.

Kampagnenstatus (state)

Medientypen

Bei Dokumenten verwendet der Header file-type den Wert PDF, nicht DOCUMENT.

Berechtigungen

Die Schnittstelle verwendet dieselben Berechtigungen wie die Verwaltung und prüft sie bei jeder Anfrage. In der Anmeldeantwort wird jeder Bereich als Zahl dargestellt, die sich aus den einzelnen Rechten zusammensetzt:

Beispielsweise bedeutet resource: 28 (4 + 8 + 16), dass der Benutzer Medien anzeigen, hinzufügen und bearbeiten, aber nicht löschen darf. Höhere Werte (128 auf 1024) stehen für dieselben Rechte außerhalb des eigenen Unternehmens. Eine Integration benötigt sie nicht.

Zum Aktivieren, Pausieren und Beenden einer Kampagne ist das Recht „Hinzufügen“ erforderlich. Zum Löschen einer aktivierten Kampagne oder einer Mediendatei ist das Recht „Löschen“ erforderlich; ein Kampagnenentwurf lässt sich ohne dieses Recht löschen. Als Ausgangspunkt eignet sich die Rolle Werbemanager des Unternehmens, aus der Sie nicht benötigte Rechte entfernen.

Fehlercodes

Vollständiges Beispiel

Das Skript führt den gesamten Ablauf aus: vom Bildupload bis zum Aktivieren einer Kampagne auf allen Geräten des Unternehmens. Erforderlich sind curl und jq.

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

API="https://admin.example.org"
AUTH="${INTEGRATION_AUTH:?INTEGRATION_AUTH=anmeldename:passwort setzen}"
FILE="sommeraktion.jpg"
NAME="Sommeraktion 2026"
FROM="2026-11-02T00:00:00"
TO="2026-11-09T00:00:00"
TZ_OFFSET="+01:00"

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

# 2) Medien hochladen
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) Kampagnenvorlage
curl -sf -u "$AUTH" "$API/api/campaign/company/$COMPANY" > template.json

# 4) Vorlage bearbeiten
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: "Primäres Motiv", isPrimary: true, isCustom: true,
      res: [{ id: 1, conditionId: 0, resourceId: $res,
              name: $n, duration: 10000, type: 2 }]
    }]
' template.json > campaign.json

# 5) Entwurf erstellen
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) Aktivieren
curl -sf -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/$TZ_OFFSET/0" > /dev/null

echo "Kampagne $CAMPAIGN aktiviert, Bericht: $API/api/report/$COMPANY/campaign/$GROUP"