stock.geolock.fr/docs/teltonika-fota-api.md

Teltonika FOTA API (consultation)

Objectif

Cette page sert de documentation interne pour consulter l’API Teltonika FOTA afin de :

• récupérer les informations d’un appareil à partir d’un IMEI (lookup)
• mettre à jour l’appareil (ex: affectation à un groupe / une organisation côté FOTA)
• comprendre les contraintes (auth, throttling, headers requis)

Source : Swagger officiel Teltonika

• UI: https://api.teltonika.lt/documents/index.html
• OpenAPI JSON: https://api.teltonika.lt/swagger/v1/swagger.json

Base URL

• https://api.teltonika.lt

Authentification

L’API utilise un Bearer token dans le header Authorization.

Headers minimum :

• Authorization: Bearer <FOTA_API_TOKEN>
• User-Agent: <company>/<app>/<version> (requis)
• Accept: application/json
• Content-Type: application/json (pour les requêtes JSON)

Notes :

• Le token doit être stocké côté serveur (API), via une variable d’environnement.
• Ne jamais exposer ce token dans le front.

Limites / throttling

• Teltonika indique une limite indicative de ~100 requêtes / minute.
• Pour des actions de masse, privilégier les endpoints bulk* quand disponibles.

Formats date/heure

• Les champs date/heure sont en UTC et formatés yyyy-MM-dd HH:mm:ss.

Endpoints utiles (lookup + move)

1) Lister des appareils (filtrage par IMEI)

GET /devices

Paramètres de requête utiles :

• imei (array[int64]) : filtrer par IMEI
• query (string) : recherche plein texte
• query_field (string) : champ de recherche (imei, serial, description, iccid)
• group_id (array[int64]) : filtrer par groupe
• company_id (array[int64]) : filtrer par organisation/compagnie

Exemple (lookup par IMEI) :

curl -sS 'https://api.teltonika.lt/devices?imei=352625691450983' \
  -H 'Authorization: Bearer <FOTA_API_TOKEN>' \
  -H 'User-Agent: localiztoi/stock-app/0.1' \
  -H 'Accept: application/json'

Réponse : un résultat paginé (schema DevicePagedResult).

2) Récupérer un appareil (détails) par IMEI

GET /devices/{deviceImei}

Exemple :

curl -sS 'https://api.teltonika.lt/devices/352625691450983' \
  -H 'Authorization: Bearer <FOTA_API_TOKEN>' \
  -H 'User-Agent: localiztoi/stock-app/0.1' \
  -H 'Accept: application/json'

Champs intéressants (selon swagger) :

• imei (int64)
• serial (string)
• model (string)
• current_firmware (string)
• activity_status (int32)
• company_id (int64) + company_name
• group_id (int64) + group_name
• seen_at (datetime string UTC)
• iccid, imsi (si présent)

3) Mettre à jour un appareil (affectation groupe / company)

PUT /devices/{deviceImei} ou PATCH /devices/{deviceImei}

Le swagger indique que les champs suivants peuvent être modifiés :

• description (string) optionnel
• company_id (int64) optionnel
• group_id (int64) optionnel

Exemple : affecter un appareil à un groupe :

curl -sS -X PATCH 'https://api.teltonika.lt/devices/352625691450983' \
  -H 'Authorization: Bearer <FOTA_API_TOKEN>' \
  -H 'User-Agent: localiztoi/stock-app/0.1' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data '{"group_id": 12345}'

Remarque: selon votre configuration FOTA, le “move” vers « vente amazon » peut correspondre à un group_id (et parfois aussi company_id).

4) Groupes (si besoin)

• GET /groups : lister les groupes
• GET /groups/{groupId} : détail

Déplacer un groupe vers une autre company

POST /groups/{groupId}/move

Body :

• target_company_id (int64)

Réponse : action asynchrone avec background_action_id (suivable via GET /backgroundActions/{backgroundActionId})

5) Background actions (suivi des jobs asynchrones)

GET /backgroundActions/{backgroundActionId}

Utile quand un endpoint renvoie un background_action_id.

Mapping recommandé pour notre app

Pour un scan IMEI :

1. insérer l’IMEI dans la commande
2. appeler GET /devices/{imei} (ou GET /devices?imei=...)
3. stocker dans notre DB : model, serial, current_firmware, activity_status, seen_at, company_id/name, group_id/name
4. déplacer le device dans le bon groupe : PATCH /devices/{imei} avec group_id (et éventuellement company_id)

Sécurité / bonnes pratiques

• Le token doit être dans une variable d’environnement côté API (ex: TELTONIKA_FOTA_API_TOKEN).
• Ne pas logger le token.
• Ajouter un User-Agent stable (obligatoire).
• Prévoir retries + backoff et gestion 429.

Prochaine étape (à valider)

Pour implémenter le move « vente de boitier → vente amazon », il faut confirmer :

• l’ID de la company (organization) cible (company_id)
• l’ID du groupe cible (group_id)