# Insights API

Le **API Insights** donne accès à la base de données d'utilisation de **The Wallet Crew (TWC)** plateforme. Interrogez les journaux, les événements et les métriques en utilisant [Kusto Query Language (KQL)](https://learn.microsoft.com/en-us/azure/data-explorer/kusto/query/).

Cette API est conçue pour **utilisateurs techniques extrayant des données de manière programmatique**, mais les requêtes restent compréhensibles pour des utilisateurs moyennement techniques également.

## Authentification et permissions

L'accès nécessite une **authentification TWC**.

* Permission requise : **`Insights:Read`**
* Flux d'authentification : utilisez votre jeton d'authentification TWC existant (par ex., depuis une connexion ou service-à-service).
* Périmètre mono-locataire : vous ne pouvez interroger que les données de votre propre locataire.

En-tête d'exemple :

```http
Authorization: Bearer <your_access_token>
```

## Rétention et limites de débit

* **Journaux** : conservés **45 jours**
* **Événements** : conservés **indéfiniment**
* **Métriques** : conservés **indéfiniment**

**Limite de débit** : 60 appels API par minute. Pour demander des limites plus élevées, ouvrez un ticket de support.

## Point de terminaison

Toutes les requêtes sont exécutées via :

```http
POST /api/{tenantId}/insights/query
```

* `{tenantId}`  = votre identifiant de locataire
* Le corps de la requête doit contenir une `requête` chaîne en **KQL**

## Tables et schéma

La base de données Insights contient trois tables :

### Journaux

| Colonne     | Type     |
| ----------- | -------- |
| eventId     | guid     |
| timestamp   | datetime |
| tenantId    | string   |
| eventType   | string   |
| operationId | string   |
| properties  | dynamic  |

Contient les erreurs et traces liées à l'activité de la plateforme. Utile pour le débogage et la surveillance de l'état.

### Événements

| Colonne     | Type     |
| ----------- | -------- |
| eventId     | guid     |
| timestamp   | datetime |
| tenantId    | string   |
| eventType   | string   |
| operationId | string   |
| properties  | dynamic  |

Contient :

* Vues de page
* Requêtes API
* Événements métiers personnalisés

### Métriques

| Colonne    | Type     |
| ---------- | -------- |
| metricId   | guid     |
| tenantId   | string   |
| metricType | string   |
| value      | dynamic  |
| properties | dynamic  |
| timestamp  | datetime |

Représente **instantanés de l'état du système**, pris toutes les heures.

## Exécuter des requêtes

### Exemple avec Axios (JavaScript)

```ts
const result = await axios.post<{ rows: Array<Array<unknown>> }>(
  `/api/${tenantId}/insights/query`,
  {
    query: `
Événements 
| where eventType == "Customer:Upserted" 
| summarize count()`,
  }
);

console.log(result.data.rows);
```

### Exemple avec cURL

```bash
curl -X POST "https://<your-host>/api/<tenantId>/insights/query" \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Events | where eventType == \"Customer:Upserted\" | summarize count()"
  }'
```

## Requêtes courantes

### Compter les nouveaux clients

```kql
Événements
| where eventType == "Customer:Upserted"
| summarize NewCustomers = count()
```

### Compter les installations de Pass

```kql
Événements
| where eventType == "Pass:Installed"
| summarize PassInstallations = count()
```

### Compter les requêtes par jour

```kql
Événements
| where eventType == "Request"
| summarize RequestsPerDay = count() by bin(timestamp, 1d)
```

### Compter les redirections par jour

```kql
Événements
| where eventType == "Redirect:Redirected"
| summarize RedirectsPerDay = count() by bin(timestamp, 1d)
```

### Compter les vues de page par navigateur

```kql
Événements
| where eventType == "PageView"
| extend browser = tostring(properties.browser)
| summarize PageViews = count() by browser
```

## Types d'événements courants

Voici quelques-uns des `eventType` valeurs que vous pourriez vouloir interroger :

* **Cycle de vie du client**
  * `Customer:Upserted`
  * `Y2:Customer:Created`
  * `Y2:Customer:Updated`
* **Cycle de vie des Pass**
  * `Pass:Created`
  * `Pass:Updated`
  * `Pass:Installed`
  * `Pass:Uninstalled`
* **Actions utilisateur**
  * `action:addToAppleWallet`
  * `action:addToGoogleWallet`
  * `action:loginWithGoogle`
  * `action:loginWithApple`
* **Suivi et analytique**
  * `Request`
  * `PageView`
  * `Redirect:Redirected`
  * `step:complete`
  * `step:changed`

## Dépannage

* **401 Non autorisé**
  * Assurez-vous que votre jeton est valide et inclut `Insights:Read`.
* **429 Trop de requêtes**
  * Vous avez dépassé la limite de débit (60 appels/minute). Mettez en place des tentatives avec backoff exponentiel.
* **La requête prend trop de temps**
  * Simplifiez la requête ou réduisez la fenêtre temporelle.
  * Évitez les requêtes sans bornes sur de grandes tables.

## FAQ

<details>

<summary>Puis-je exporter les résultats en CSV/JSON ?</summary>

Pas directement via l'API.

Consommez la réponse JSON et convertissez-la localement.

</details>

<details>

<summary>Puis-je interroger plusieurs locataires ?</summary>

Non.

L'accès est limité à votre seul locataire.

</details>

<details>

<summary>La base Insights contient-elle des données personnelles ?</summary>

Non.

Elle ne contient pas d'IPI.

</details>

<details>

<summary>Puis-je configurer des alertes (seuils, déclencheurs) ?</summary>

Pas pour le moment.

</details>