134 lines
4.6 KiB
Markdown
134 lines
4.6 KiB
Markdown
# 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) :
|
||
```bash
|
||
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 :
|
||
```bash
|
||
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 :
|
||
```bash
|
||
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`)
|