Envoyer une commande à une borne

Une commande s'adresse à un équipement précis d'une borne: l'imprimante, le terminal de paiement, le système. Wogeez la transmet à la passerelle à laquelle la borne est connectée, puis à l'agent de la borne, au hub qui gère l'équipement et enfin à l'équipement lui-même. Celui-ci exécute la commande et renvoie son résultat par le même chemin.

Chaque passage est enregistré. Vous savez donc à tout moment où en est la commande, et pourquoi elle n'a pas abouti si c'est le cas. Une commande est d'abord PENDING, puis prend l'un des états finaux ci-dessous.

Les commandes ne sont pas les mêmes d'une borne à l'autre: chaque équipement annonce les siennes dans l'état de santé que la borne remonte. Récupérez d'abord l'identifiant de la borne, ici par son nom.

DEVICE=$(curl -s "https://api-v2.wogeez.com/resources/search?type=DEVICE&company=$COMPANY&pageSize=100" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -r '.resources[] | select(.name == "Borne hall A") | .id')

La fiche de la borne contient ses hubs, puis pour chaque équipement la liste de ses commandes.

curl -s "https://api-v2.wogeez.com/companies/$COMPANY/resources/$DEVICE" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.item.resource.health.hubs[] | { hub: .uid, label, devices: [ .devices[] | { hubDevice: .uid, label, commands: [ .commands[]?.command ] } ] }'

Chaque hub s'affiche avec ses équipements.

{
  "hub": "b5d1e0a2-...",
  "label": "Wogeez Engine",
  "devices": [
    {
      "hubDevice": "7c4f9e31-...",
      "label": "Imprimante",
      "commands": [ "PRINT_TEST", "PRINTER_EJECT_PAPER", "PRINTER_CUT" ]
    }
  ]
}

Gardez l'identifiant du hub et celui de l'équipement. Une commande peut aussi déclarer des arguments. Chacun a un name et un type: VALUE pour une valeur libre, avec sa valeur par défaut, ou ENUMERATION pour un choix parmi les valeurs de values.

HUB=b5d1e0a2-...
HUB_DEVICE=7c4f9e31-...

Le corps de l'appel donne le nom exact de la commande et, dans payload, ses arguments par nom. Sans argument, envoyez un objet vide.

curl -s -X POST "https://api-v2.wogeez.com/companies/$COMPANY/resources/devices/$DEVICE/hubs/$HUB/devices/$HUB_DEVICE/commands" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "command": "PRINT_TEST", "payload": {} }'

L'API répond tout de suite, sans attendre que la borne ait exécuté la commande. La réponse contient l'identifiant de suivi de la commande.

{
  "item": "3e9a61f0-..."
}

COMMAND=$(curl -s -X POST "https://api-v2.wogeez.com/companies/$COMPANY/resources/devices/$DEVICE/hubs/$HUB/devices/$HUB_DEVICE/commands" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "command": "PRINT_TEST", "payload": {} }' | jq -r .item)

La commande apparaît aussi dans l'historique de la borne, dans le manager, avec le nom du compte qui l'a envoyée.

L'identifiant de suivi donne l'état de la commande, chaque étape franchie avec son heure et, à la fin, le message et le résultat renvoyés par l'équipement.

curl -s "https://api-v2.wogeez.com/companies/$COMPANY/resources/devices/$DEVICE/commands/$COMMAND" \
  -H "Authorization: Bearer $TOKEN"

{
  "item": {
    "id": "3e9a61f0-...",
    "command": "PRINT_TEST",
    "hub": "b5d1e0a2-...",
    "hubDevice": "7c4f9e31-...",
    "requestedBy": "Camille Martin",
    "requestedAt": "2026-11-10T10:42:00",
    "deadline": "2026-11-10T10:43:00",
    "state": "SUCCEEDED",
    "terminal": true,
    "message": "Ticket de test imprime",
    "result": null,
    "finishedAt": "2026-11-10T10:42:03",
    "steps": [
      { "step": "RECEIVED", "at": "2026-11-10T10:42:00" },
      { "step": "SENT_TO_GATEWAY", "at": "2026-11-10T10:42:00" },
      { "step": "SENT_TO_AGENT", "at": "2026-11-10T10:42:00" },
      { "step": "RECEIVED_BY_AGENT", "at": "2026-11-10T10:42:01" },
      { "step": "SENT_TO_HUB", "at": "2026-11-10T10:42:01" },
      { "step": "SENT_TO_DEVICE", "at": "2026-11-10T10:42:01" },
      { "step": "SUCCEEDED", "at": "2026-11-10T10:42:03" }
    ]
  }
}

terminal passe à true quand la commande a atteint un état final. result contient les données renvoyées par l'équipement, quand il en a. Son contenu dépend de la commande.

La dernière étape franchie indique où une commande s'est arrêtée. Une commande UNREACHABLE sans étape RECEIVED_BY_AGENT, par exemple, n'a jamais atteint la borne: vérifiez sa connexion avant de recommencer.

Plutôt que de relire la commande toutes les secondes, ouvrez son flux d'événements. Il envoie l'état actuel, puis un nouvel événement à chaque étape, et se ferme de lui-même après l'état final.

curl -s -N "https://api-v2.wogeez.com/companies/$COMPANY/resources/devices/$DEVICE/commands/$COMMAND/events" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream"

Chaque événement porte la commande complète, au même format que la lecture ci-dessus.

data:{"id":"3e9a61f0-...","state":"PENDING","terminal":false,"steps":[...]}

data:{"id":"3e9a61f0-...","state":"PENDING","terminal":false,"steps":[...]}

data:{"id":"3e9a61f0-...","state":"SUCCEEDED","terminal":true,"message":"Ticket de test imprime","steps":[...]}

Dans un navigateur, EventSource ne permet pas d'ajouter l'en-tête Authorization. Lisez le flux avec fetch, comme dans cet exemple en Node.js ou dans une page web.

const url = `https://api-v2.wogeez.com/companies/${company}/resources/devices/${device}/commands/${command}/events`;
const response = await fetch(url, {
  headers: { Authorization: `Bearer ${token}`, Accept: "text/event-stream" },
});

const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
let buffer = "";
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += value;
  const events = buffer.split("\n\n");
  buffer = events.pop();
  for (const event of events) {
    const data = event.split("\n").filter((line) => line.startsWith("data:")).map((line) => line.slice(5)).join("");
    if (!data) continue;
    const progress = JSON.parse(data);
    console.log(progress.state, progress.steps.at(-1)?.step);
  }
}

Si la connexion est coupée avant la fin, relisez la commande avec son identifiant: son état est conservé côté serveur.

Les dernières commandes d'une borne se lisent de la plus récente à la plus ancienne, 20 par défaut et jusqu'à 100 avec limit.

curl -s "https://api-v2.wogeez.com/companies/$COMPANY/resources/devices/$DEVICE/commands?limit=10" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.item[] | { command, state, requestedBy, requestedAt, message }'

Les commandes sont conservées 90 jours.

• Ne renvoyez pas une commande en cours. Tant qu'elle est PENDING, suivez-la avec son identifiant. Une seconde commande serait exécutée elle aussi, et un ticket serait imprimé deux fois.
• Lisez DELIVERED avec prudence. L'équipement a bien reçu la commande, mais il ne sait pas encore dire s'il l'a exécutée. Vérifiez sur place ou dans l'état de santé suivant de la borne.
• Relisez les commandes avant de les envoyer. Elles changent quand le matériel de la borne change. Une commande que l'équipement ne connaît pas finit en FAILED.
• Gardez l'identifiant de suivi dans vos propres outils, pour relier une action de votre supervision ou de votre ticketing à son résultat.

Les assistants IA connectés au serveur MCP utilisent les mêmes commandes et le même suivi. Le détail des points d'accès se trouve dans le Swagger.