API pour connecter votre système

Référence technique

Guide technique pour les développeurs d’intégrations

Commencez par les conventions d’appel communes et la connexion. Suivez ensuite le parcours du téléversement d’un média au lancement d’une campagne, puis consultez les points de terminaison disponibles.

Connexion

L’identifiant de connexion n’est pas une adresse e-mail, mais un code de huit caractères généré lors de la création de l’utilisateur, par exemple A1B2C3D4. Créez un utilisateur dédié avec les autorisations minimales nécessaires ; son accès pourra être révoqué à tout moment sans affecter les autres utilisateurs.

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

Le mot de passe est transmis à chaque requête. Conservez-le comme un secret, par exemple dans une variable d’environnement ou un coffre-fort de mots de passe, jamais dans le code source, un dépôt ou les journaux.

Les exemples suivants supposent que ces variables sont définies :

export API="https://admin.example.org"
export AUTH="A1B2C3D4:votre-mot-de-passe"

Les exemples utilisent curl car cet outil ne dépend d’aucun langage de programmation. L’interface repose sur HTTP et peut être appelée depuis tout langage ou outil prenant en charge Basic Auth, comme Python, JavaScript, PHP, Postman ou Make.

Parcours : du fichier à la campagne diffusée

1. Obtenir l’identifiant de l’entreprise. Il sera utilisé dans tous les appels suivants.
2. Téléverser un média. La réponse renvoie son identifiant.
3. Charger un modèle de campagne. Le serveur le préremplit avec les paramètres de l’entreprise et la liste des sites et appareils.
4. Modifier le modèle : nom, période, appareils ciblés et visuel.
5. Créer la campagne. Elle est créée comme brouillon et n’est pas encore diffusée.
6. Activer la campagne. Le système prépare un nouveau plan de lecture et l’envoie aux appareils.
7. Suivre les résultats dans le rapport de campagne.

1. Identifiant de l’entreprise

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

Réponse abrégée :

{
  "id": 1715714421868,
  "name": "Intégration – boutique en ligne",
  "login": "A1B2C3D4",
  "company": { "id": 1698234512001, "name": "Agence publicitaire SARL" },
  "permission": {
    "resource": 12,
    "device_layer_top": 12,
    "report_layer_top": 4
  }
}

Conservez la valeur de company.id; les exemples l’utilisent dans la variable COMPANY. La section permission énumère les autorisations de l’utilisateur ; leur signification est décrite dans Droits d’accès.

2. Téléversement d’un média

Le fichier est envoyé comme corps binaire de la requête avec PUT; ses propriétés sont indiquées dans les en-têtes.

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

Le même appel en Python :

import requests

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

La réponse contient l’identifiant du média (id) et son type (type) ; ces deux valeurs seront utilisées dans le visuel de campagne.

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

• Taille : fichiers ordinaires jusqu’à environ 1,1 Go, vidéos avec transparence jusqu’à environ 2,1 Go. Le serveur rejette les fichiers plus volumineux avec 413.
• Préparation vidéo : la vidéo est convertie en arrière-plan après le téléversement. Elle est prête dès que la fiche du média (GET /api/resource/single/{companyId}/{id}) contient une valeur dans dt_ready. Les images sont prêtes presque immédiatement.
• En-tête manquant : sans file-mime, file-name ou file-suffix le serveur renvoie 204 et ne crée pas le média. Vérifiez toujours que la réponse contient id avant de continuer.

3. Modèle de campagne

Ne construisez pas la campagne à la main. Demandez un modèle que le serveur préremplit avec une période par défaut d’un mois à partir d’aujourd’hui, les paramètres de l’entreprise et tous les sites et appareils. Chaque appareil y est marqué isActive: false.

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

Exemple de modèle abrégé :

{
  "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": "Centre commercial du centre-ville",
      "days": [ { "day": 1, "start": "09:00", "end": "21:00" } ],
      "devices": [
        {
          "id": 1698234512201,
          "name": "Entrée A",
          "screenRatio": 32,
          "isHorizontal": true,
          "isActive": false
        }
      ]
    }
  ],
  "visuals": []
}

La valeur de settings.type détermine le mode de lecture de l’entreprise: 2 = SLOT, 4 = IMPRESSION. Le fournisseur définit ce mode ; il ne peut pas être modifié via l’API.

4. Modification du modèle

• name: nom de la campagne affiché dans l’administration et les rapports.
• start, end: début et fin de la campagne.
• isActive: définir sur true pour les appareils devant diffuser la campagne.
• visuals: ajouter un visuel contenant le média téléversé.

"visuals": [
  {
    "id": 1,
    "name": "Visuel principal",
    "isPrimary": true,
    "isCustom": true,
    "res": [
      {
        "id": 1,
        "conditionId": 0,
        "resourceId": 1724832015443,
        "name": "offre-ete",
        "duration": 10000,
        "type": 2
      }
    ]
  }
]

Le modèle peut être modifié par un script, par exemple avec jq:

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

Si la campagne cible des écrans en paysage et en portrait (isHorizontal), ajoutez un visuel par orientation. Sinon, le contenu sera recadré ou réduit sur certains écrans. Voir Visuels des campagnes pour en savoir plus.

5. Création de la campagne

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 campagne est créée comme brouillon et n’est diffusée nulle part. La réponse contient la campagne enregistrée avec les valeurs attribuées de id et groupId. Le modèle contient déjà state: 2 (brouillon) ; le serveur rejette toute autre valeur avec 409.

6. Activation de la campagne

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

• +01:00: fuseau horaire de la campagne sous forme de décalage UTC. Pour l’Europe centrale, utilisez +01:00 en hiver et +02:00 à l’heure d’été.
• 0: nombre d’impressions attendu pour toute la campagne. S’applique en mode IMPRESSION ; en mode SLOT, utilisez 0.

Une campagne commençant aujourd’hui ou avant devient active ; son début est fixé à l’instant d’activation. Une campagne commençant dans le futur devient publiée et démarre le jour prévu.

Le système recalcule ensuite le plan de lecture et l’envoie aux appareils concernés. Cela prend généralement quelques dizaines de secondes pour les appareils connectés ; un appareil déconnecté reçoit le plan au rétablissement de la connexion. Vérifiez la capacité dans l’administration ; voir Capacité des campagnes.

7. Résultats de la campagne

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

Les rapports utilisent groupId, et non l’identifiant de campagne id. Le premier point de terminaison renvoie le récapitulatif de la campagne, le second le nombre d’impressions enregistrées. Les appareils transmettent les données par lots en continu ; les chiffres ne sont donc pas disponibles en temps réel. Consultez Rapport de campagne pour comprendre les chiffres.

Mise en pause, arrêt et suppression

# Mettre en pause une campagne active ; un nouvel appel la reprend
curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00/0"

# Arrêter définitivement
curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00"

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

Le point de terminaison de l’étape 6 fonctionne comme une bascule : il met en pause une campagne active ou publiée et reprend une campagne en pause. Vérifiez l’état actuel (state dans la fiche) avant l’appel. Une campagne arrêtée ne peut plus être relancée, mais reste dans la liste avec ses rapports. Une campagne supprimée disparaît de la liste.

Vue d’ensemble des points de terminaison

Les chemins sont relatifs à l’adresse de l’administration. {c} représente l’identifiant de l’entreprise.

Compte

Médias

Campagnes

Sites et appareils

Rapports

Listes de valeurs

Les valeurs des listes sont représentées par des nombres en JSON.

État de la campagne (state)

Types de médias

Pour les documents, l’en-tête file-type utilise la valeur PDF, et non DOCUMENT.

Droits d’accès

L’interface applique les mêmes autorisations que l’administration et les vérifie à chaque requête. Dans la réponse de connexion, chaque domaine est exprimé par un nombre égal à la somme des droits individuels :

Par exemple, resource: 28 (4 + 8 + 16) signifie que l’utilisateur peut consulter, ajouter et modifier des médias, mais pas les supprimer. Les valeurs plus élevées (128 sur 1024) représentent les mêmes droits en dehors de l’entreprise de l’utilisateur ; l’intégration n’en a pas besoin.

L’activation, la mise en pause et l’arrêt d’une campagne nécessitent le droit Ajouter. Supprimer une campagne activée ou un média nécessite le droit Supprimer ; un brouillon peut être supprimé sans ce droit. Un bon point de départ est le rôle Gestionnaire publicitaire de l’entreprise, en retirant les droits inutiles.

Codes d’erreur

Exemple complet

Le script exécute tout le parcours, du téléversement d’une image à l’activation d’une campagne sur tous les appareils de l’entreprise. Il nécessite curl et jq.

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

API="https://admin.example.org"
AUTH="${INTEGRATION_AUTH:?definir INTEGRATION_AUTH=identifiant:mot-de-passe}"
FILE="offre-ete.jpg"
NAME="Offre estivale 2026"
FROM="2026-11-02T00:00:00"
TO="2026-11-09T00:00:00"
TZ_OFFSET="+01:00"

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

# 2) Téléverser le média
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) Modèle de campagne
curl -sf -u "$AUTH" "$API/api/campaign/company/$COMPANY" > template.json

# 4) Modifier le modèle
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: "Visuel principal", isPrimary: true, isCustom: true,
      res: [{ id: 1, conditionId: 0, resourceId: $res,
              name: $n, duration: 10000, type: 2 }]
    }]
' template.json > campaign.json

# 5) Créer un brouillon
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) Activer
curl -sf -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/$TZ_OFFSET/0" > /dev/null

echo "Campagne $CAMPAIGN activée, rapport : $API/api/report/$COMPANY/campaign/$GROUP"