# API Insights

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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.thewalletcrew.io/fr/developper/guides/insights-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.