# 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`)