# Fonctionnement

Captain Metrics est entièrement construit sur une API, cependant pour simplifier les choses, seul l'import des datas est documenté ici. N'hésitez pas à nous contacter si vous avez d'autres besoins.

{% hint style="warning" %}
La collecte des éléments de navigation web doit être effectuée par l'[Agent Web JS](https://docs.captainmetrics.com/integrations/agent-web-js), et non par l'API d'import des datas.
{% endhint %}

### Traitement des données

Captain Metrics a été construit pour supporter l'ingestion de données non-ordonnées temporellement (out-of-order time-series), de façon à pouvoir importer des données anciennes et obtenir une vision la plus complète possible.

Tous les types d'objets (`user`, `product`, `order`...) sont ingérés en mode `update-insert` et idempotents : l'import de deux `users` identiques aura pour résultat l'ajout d'un seul `user` dans la base de donnée.

Lorsqu'un objet importé est déjà présent dans la base de donnée, et qu'il contient des données nouvelles, les champs manquants sont alors fusionnés de façon à enrichir l'objet.

{% hint style="warning" %}
A la fin d'une requête d'import de données, tous les `users` concernés par cet import sont automatiquement repassés dans le moteur de segmentation et d'automatisation marketing. Nous vous conseillons donc de grouper les imports de données par `user` afin d'accélérer l'ingestion de vos données.
{% endhint %}

{% hint style="info" %}
De ce fait, tous les dashboards et analytics sont calculés en temps réel lors de l'affichage pour refléter l'état actuel de vos données.
{% endhint %}

### Endpoint

Toutes les données entrantes (imports par API, agent web JS, webhooks...) transitent par un service asynchrone qui assure la validation, la déduplication et le log des requêtes, avant qu'elles ne soient effectivement insérées dans votre projet Captain Metrics.

URL d'import par API :

**`POST https://photon.captainmetrics.com/data.import`**

### Format

Les données sont transmises dans le **`Body`** de la requête au format **`JSON`**. Vous pouvez transmettre un maximum de 100 items par requête.

| Propriété   | Type    | Description                                                                                                                                                                                                                                                                                                   |
| ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`        | string  | ID unique de votre import, il sera dé-dupliqué s'il a déjà transité par l'API. Nous vous conseillons de le générer avec hash SHA1 du contenu des **`items`**.                                                                                                                                                 |
| `projectId` | string  | ID du projet concerné par l'import.                                                                                                                                                                                                                                                                           |
| `items`     | \[]item | Liste de **100 `items` maximum** à traiter par l'API. [Détail des types d'items ici.](https://docs.captainmetrics.com/data-import-api/schemas)                                                                                                                                                                |
| `sync`      | boolean | <p><strong><code>False</code></strong> par défaut. Permet de tester le bon fonctionnement de votre intégration de façon synchrone si<strong><code>true</code></strong>. </p><p><strong>Laisser à <code>false</code> en production pour bénéficier de la résilience de l'architecture asynchrone.</strong></p> |

Exemple :

```
{
  "id": "import_request_unique_id",
  "projectId": "acme_demo",
  "items": [
    {"id": "xxx", "kind": "user", "user": {...}},
    {"id": "xxx", "kind": "order", "order": {...}},
    ...
  ]
}
```

### Authentification

L'authentification des requêtes d'import API requière un Service Account Token via le `Header` :

**`Authorization: Bearer SERVICE_ACCOUNT_TOKEN`**

Vous pouvez créer un Service Account dans le menu "Admins" de votre organisation comme ceci :

![](https://3988754291-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M3qLgc05uobPjWj6gZE%2F-MWBS3Kwo2zGiuCSe4Wd%2F-MWBVuN-BbJThdL21e_Q%2Fadmins.png?alt=media\&token=5abdfbe7-88ab-48b6-b2e9-df0e55395998)

![](https://3988754291-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M3qLgc05uobPjWj6gZE%2F-MWBS3Kwo2zGiuCSe4Wd%2F-MWBVxfUtM6u1m7e8SUo%2Fservice-account.png?alt=media\&token=18771289-0196-45ef-8d42-961221f7cf31)

![](https://3988754291-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M3qLgc05uobPjWj6gZE%2F-MWBS3Kwo2zGiuCSe4Wd%2F-MWBW0zLWcZof82Zdky1%2Fservice-account-token.png?alt=media\&token=0e225b31-9e99-44b3-b570-55ff5bad9126)
