API Neyos

L'API Neyos est une API REST qui vous permet de piloter votre parc depuis vos propres outils : consulter l'état de vos balises, leur envoyer des commandes à distance et gérer les webhooks qui alimentent vos systèmes en temps réel.

Authentification

Chaque requête doit porter votre jeton client dans l'en-tête Authorization :

curl https://api.neyos-equipment.com/api/v1/trackers \
  -H "Authorization: Bearer ctk_xxxxxxxxxxxxxxxxxxxxxxx"

Un appel sans jeton, ou avec un jeton invalide, expiré ou révoqué, renvoie 401 Unauthorized.

Conventions

Identifiants

Les balises sont référencées par leur serial, le numéro de série gravé sur le boîtier. Les autres ressources portent un identifiant préfixé :

Dates

Sur l'API, toutes les dates sont sérialisées en millisecondes Unix (number) ou null.

Pagination

Les endpoints de liste acceptent les paramètres suivants :

Une réponse paginée a toujours la forme suivante :

{
  "meta": {
    "total": 142,
    "perPage": 25,
    "currentPage": 1,
    "lastPage": 6,
    "firstPage": 1
  },
  "data": [ ]
}

Modèles

Types de commandes

Deux types de commandes peuvent être créés via l'API publique :

D'autres types (load_config, send_config, time_sync…) sont générés par la plateforme et peuvent apparaître dans l'historique d'une balise ou dans vos webhooks, sans pouvoir être créés depuis l'API.

États d'une commande

Cycle de vie typique : waiting → pending → received → success ou failed.

Trackers

Lister les balises

GET /api/v1/trackers

Paramètres : page, perPage, sort (défaut serial), order, search (filtre sur serial et alias).

Filtres additionnels — plusieurs valeurs peuvent être séparées par une virgule :

curl "https://api.neyos-equipment.com/api/v1/trackers?perPage=10&connected=true&search=depot" \
  -H "Authorization: Bearer ctk_xxxxx"

Réponse 200 — objet paginé contenant un tableau de Tracker dans data.

Récupérer une balise

GET /api/v1/trackers/:serial

Réponse 200 — un objet Tracker. Erreur 404 — la balise n'existe pas ou n'appartient pas à votre organisation.

Modifier une balise

PATCH /api/v1/trackers/:serial

Seuls les champs alias et notes sont modifiables. Les deux sont optionnels et peuvent être remis à null.

{
  "alias": "Camion 12 - dépôt nord",
  "notes": "Affecté à la tournée Lyon-Grenoble"
}

Réponse 200 — la balise mise à jour.

Historique des commandes d'une balise

GET /api/v1/trackers/:serial/actions

Paramètres : page, perPage, sort (défaut createdAt), order (défaut desc).

Réponse 200 — objet paginé de TrackerAction.

Commandes

Envoyer une commande à une balise

POST /api/v1/trackers/:serial/actions

{
  "type": "custom_commands",
  "commands": ["gnss set --rate=5000", "modem set --network_1=0"],
  "priority": 50
}

{
  "type": "power_off"
}

Réponse 201 — la commande a été créée et mise en file :

{
  "status": "created",
  "data": { }
}

Réponse 200 — la balise est déjà dans l'état demandé, aucune commande n'a été créée :

{
  "status": "already_up_to_date",
  "message": "Tracker is already up to date"
}

Erreurs : 404 (balise inconnue), 422 (validation).

Envoyer des commandes à plusieurs balises

POST /api/v1/actions/_bulk

{
  "trackerActions": [
    { "serial": "AB123", "type": "power_off" },
    { "serial": "AB124", "type": "custom_commands", "commands": ["gnss set --rate=10000"] },
    { "serial": "AB125", "type": "custom_commands", "commands": ["modem set --apn=mybiz"], "priority": 20 }
  ]
}

Chaque entrée est traitée indépendamment : une erreur unitaire (balise hors organisation, commande invalide…) ne fait pas échouer les autres.

Réponse 201

{
  "total": 3,
  "created": 2,
  "failed": 1,
  "results": [
    { "index": 0, "status": "created", "id": "tac_xxx", "data": { } },
    { "index": 1, "status": "created", "id": "tac_yyy", "data": { } }
  ],
  "errors": [
    { "index": 2, "status": "error", "message": "Tracker not found", "input": { } }
  ]
}

Le champ index correspond à la position de l'entrée dans le tableau envoyé, ce qui permet de rattacher chaque résultat à sa demande d'origine.

Suivre une commande

GET /api/v1/actions/:id

Réponse 200 — un TrackerAction avec sa relation attempts : chaque tentative d'envoi contient sentAt, receivedAt et response.

Annuler une commande

PUT /api/v1/actions/:id/cancel

Une commande ne peut être annulée que tant qu'elle n'a pas été transmise à la balise, c'est-à-dire au statut waiting. Une commande déjà envoyée ne peut plus être rappelée.

Réponse 200

{ "status": "canceled" }

Webhooks

Les webhooks poussent en POST les événements de votre organisation vers l'URL de votre choix. Tous les webhooks activés rattachés à votre compte reçoivent chaque événement.

Pour la mise en place côté serveur, le détail des payloads et les exemples complets, voir la page Webhook.

Lister vos webhooks

GET /api/v1/webhooks

Paramètres : page, perPage, sort (défaut createdAt), order (défaut desc), search (filtre sur url).

Récupérer un webhook

GET /api/v1/webhooks/:id

Créer un webhook

POST /api/v1/webhooks

{
  "url": "https://app.mon-domaine.com/integrations/neyos",
  "description": "Webhook production",
  "enabled": true
}

Réponse 201 — le webhook créé, accompagné de son signingSecret :

{
  "id": "end_xxx",
  "url": "https://app.mon-domaine.com/integrations/neyos",
  "description": "Webhook production",
  "enabled": true,
  "signingSecret": "whsec_2aB3cD...",
  "createdAt": 1737031800000,
  "updatedAt": 1737031800000
}

Modifier un webhook

PUT /api/v1/webhooks/:id

Mêmes champs qu'à la création, tous optionnels : seuls les champs fournis sont modifiés. Réponse 200 — le webhook mis à jour.

Supprimer un webhook

DELETE /api/v1/webhooks/:id

Réponse 204 — pas de contenu.

Types d'événements émis

Chaque notification a la même enveloppe :

{
  "type": "tracker.updated",
  "data": { }
}

Format des dates

Le format des dates dépend de l'événement — c'est le principal piège d'intégration :

Garanties de livraison

• Les webhooks désactivés (enabled: false) ne reçoivent aucun appel.
• Réponse attendue : un code 200. Toute autre réponse, ainsi qu'un timeout ou un hôte injoignable, est consignée comme un échec.
• Les appels sont asynchrones, via une file de jobs : deux notifications proches dans le temps peuvent arriver dans le désordre. Fiez-vous aux horodatages du payload, pas à l'ordre de réception.
• Un même événement peut être reçu plusieurs fois : utilisez l'en-tête X-Neyos-Event-Id comme clé d'idempotence.
• Chaque notification est tracée côté Neyos (URL, corps envoyé, code HTTP, temps de réponse, statut), et le champ sentAt du webhook est mis à jour à chaque envoi.

Signature des notifications

Chaque appel webhook sortant est signé en HMAC-SHA256 à l'aide du signingSecret retourné à la création du webhook, et accompagné des en-têtes X-Neyos-Timestamp, X-Neyos-Signature et X-Neyos-Event-Id.

Codes d'erreur

Les erreurs de validation 422 détaillent les champs en faute :

{
  "errors": [
    { "message": "The url field must be a valid URL", "rule": "url", "field": "url" }
  ]
}

Besoin d'un jeton d'accès ou d'aide sur votre intégration ?