API per collegare il Suo sistema

Riferimento tecnico

Guida tecnica per gli sviluppatori di integrazioni

Inizi dalle convenzioni comuni per le chiamate e dall'autenticazione. Segua poi la procedura dal caricamento di un file multimediale all'avvio di una campagna e consulti la panoramica degli endpoint disponibili.

Accesso

Il nome di accesso non è un indirizzo e-mail, ma un codice di otto caratteri generato dal sistema alla creazione dell'utente, per esempio A1B2C3D4. Create a dedicated user with the minimum necessary permissions for the integration; its access can then be revoked at any time without affecting other users.

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

La password viene inviata con ogni richiesta. La conservi come dato riservato, per esempio in una variabile d'ambiente o in un gestore di segreti, mai nel codice sorgente, in un repository o nei log.

Gli esempi seguenti presuppongono che siano impostate queste variabili:

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

Gli esempi utilizzano curl because it does not depend on a programming language. The interface is plain HTTP, so it can be called from any language or tool that supports Basic Auth, for example Python, JavaScript, PHP, Postman or Make.

Procedura: da un file a una campagna in esecuzione

1. Recuperi l'identificatore dell’azienda. Lo utilizzerà in tutte le chiamate successive.
2. Carichi un file multimediale. La risposta restituisce il relativo identificatore.
3. Carichi un modello di campagna. Il server lo precompila con le impostazioni dell’azienda e l'elenco di sedi e dispositivi.
4. Modifichi il modello — nome, periodo, dispositivi di destinazione e creatività.
5. Crei la campagna. La campagna viene creata come bozza e non è ancora riprodotta.
6. Attivi la campagna. Il sistema prepara un nuovo piano di riproduzione e lo invia ai dispositivi.
7. Controlli i risultati nel report della campagna.

1. Identificatore dell’azienda

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

Risposta abbreviata:

{
  "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
  }
}

Conservi il valore di company.id; the examples use it as the variable COMPANY. The permission section lists the user’s permissions; their meaning is described under Autorizzazioni.

2. Caricamento di un file multimediale

Il file viene inviato come corpo binario della richiesta utilizzando PUT; its properties are given in headers.

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

La stessa chiamata in 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"]

La risposta contiene l'identificatore del contenuto multimediale (id) and its type (type); you will use both values in the campaign visual.

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

• Dimensioni: file normali fino a circa 1,1 GB, video con trasparenza fino a circa 2,1 GB. Il server rifiuta i file più grandi con 413.
• Preparazione dei video: il video viene convertito in background dopo il caricamento. È pronto quando i dettagli del contenuto multimediale (GET /api/resource/single/{companyId}/{id}) contains a value in dt_ready. For images, preparation is practically immediate.
• Intestazione mancante: senza file-mime, file-name or file-suffix the server returns 204 and does not create the media file. Always check that the response contains id before continuing.

3. Modello di campagna

Non componga la campagna manualmente. Richieda un modello che il server precompila con un periodo predefinito di un mese a partire da oggi, le impostazioni dell’azienda e l'elenco di tutte le sedi e i dispositivi. Ogni dispositivo al suo interno è contrassegnato come isActive: false.

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

Esempio di modello abbreviato:

{
  "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": []
}

Il valore di settings.type determines the Company’s modalità di riproduzione: 2 = SLOT, 4 = IMPRESSION. The mode is set by the provider and cannot be changed via the API.

4. Modifica del modello

• name: nome della campagna mostrato nell'amministrazione e nei report.
• start, end: inizio e fine della campagna.
• isActive: imposti su true for the devices on which the campaign should play.
• visuals: aggiunga una creatività con il file multimediale caricato.

"visuals": [
  {
    "id": 1,
    "name": "Main visual",
    "isPrimary": true,
    "isCustom": true,
    "res": [
      {
        "id": 1,
        "conditionId": 0,
        "resourceId": 1724832015443,
        "name": "summer-sale",
        "duration": 10000,
        "type": 2
      }
    ]
  }
]

Il modello può essere modificato da uno script, per esempio con 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

Se la campagna è destinata sia a schermi orizzontali sia a schermi verticali (isHorizontal), add a visual for each orientation. Otherwise the content will be cropped or scaled down on some screens. See Creatività delle campagne per maggiori dettagli.

5. Creazione della campagna

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)

La campagna viene creata come bozza e non viene riprodotta su alcun dispositivo. La risposta contiene la campagna salvata con l'identificatore assegnato id and groupId. The template already has state: 2 (draft); the server rejects any other value with 409.

6. Attivazione della campagna

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

• +01:00: fuso orario espresso come scostamento da UTC seguito dalla campagna. Per l'Europa centrale utilizzi +01:00 in winter and +02:00 in summer time.
• 0: numero previsto di impressioni per l'intera campagna. Si applica nella modalità IMPRESSION; nella modalità SLOT utilizzi 0.

Una campagna che inizia oggi o prima diventa attiva e il suo inizio viene impostato al momento dell'attivazione. Una campagna con inizio futuro diventa pubblicata e parte nel giorno pianificato.

Il sistema ricalcola quindi il piano di riproduzione e lo invia ai dispositivi interessati. Per i dispositivi collegati sono normalmente necessarie alcune decine di secondi; un dispositivo disconnesso riceve il piano al ripristino della connessione. Controlli la capacità dei dispositivi nell'amministrazione; consulti Capacità delle campagne.

7. Risultati della campagna

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

I report utilizzano groupId, not the campaign id. The first endpoint returns the campaign summary, the second the numbers of recorded impressions. Devices send records continuously in batches, so the figures are not available in real time. See Report della campagna per il significato delle cifre.

Sospensione, arresto ed eliminazione

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

L'endpoint del passaggio 6 funziona come commutatore: mette in pausa una campagna attiva o pubblicata e riprende una campagna in pausa. Controlli lo stato corrente della campagna (state in the detail) before calling it. A stopped campaign cannot be started again, but it remains in the list together with its reports. A deleted campaign disappears from the list.

Panoramica degli endpoint dell'API

I percorsi sono relativi all'indirizzo dell'amministrazione. {c} stands for the Company identifier.

Account

Contenuti multimediali

Campagne

Sedi e dispositivi

Report

Elenchi di codici

I valori degli elenchi di codici sono scritti come numeri in JSON.

Stato della campagna (state)

Tipi di contenuti multimediali

Per i documenti, il file-type header uses the value PDF, not DOCUMENT.

Autorizzazioni

L'interfaccia applica le stesse autorizzazioni dell'amministrazione e le verifica a ogni richiesta. Nella risposta di accesso, ciascuna area è espressa come un numero pari alla somma dei singoli diritti:

Per esempio, resource: 28 (4 + 8 + 16) means the user may view, add and edit media, but not delete them. Higher values (128 to 1024) represent the same rights outside the user’s own Company; an integration does not need them.

Attivazione, sospensione e arresto di una campagna richiedono il diritto Aggiungi. L'eliminazione di una campagna attivata o di un file multimediale richiede il diritto Elimina; una bozza di campagna può essere eliminata senza questo diritto. Un buon punto di partenza è il ruolo Gestore pubblicità dell’azienda con la rimozione dei diritti non necessari.

Codici di errore

Esempio completo

Lo script esegue l'intera procedura, dal caricamento di un'immagine all'attivazione di una campagna su tutti i dispositivi dell’azienda. Richiede curl and 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"