> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.review-collect.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Exporter vos invitations dans BigQuery ou Snowflake

Chargez l'historique de vos invitations d'avis dans BigQuery ou Snowflake, puis tenez-le à jour chaque jour avec l'API Review Collect.

## Obtenir votre clé API

1. Demandez votre clé API à **votre account manager**, depuis la bulle de chat ou par email
2. Stockez-la dans le gestionnaire de secrets de votre entrepôt, jamais dans un fichier partagé

| La clé donne accès aux données de votre compte uniquement. Elle se passe dans l'en-tête `X-Api-Key` de chaque requête.

## Charger l'historique

L'endpoint `GET /invitations` renvoie une invitation par client contacté, avec les messages envoyés, la note laissée et l'avis publié. La référence complète est sur [developers.review-collect.com](https://developers.review-collect.com).

1. Appelez l'endpoint avec `limit=1000`
2. Tant que `has_more` vaut `true`, rappelez-le avec `cursor` égal au `next_cursor` reçu
3. Écrivez chaque page dans votre table avant de demander la suivante

Modèle à copier-coller :

```
import requests

BASE = "https://api.review-collect.com/api:v1"
HEADERS = {"X-Api-Key": RC_API_KEY}

def invitations(**params):
    params = {"limit": 1000, **params}
    while True:
        page = requests.get(f"{BASE}/invitations", headers=HEADERS, params=params, timeout=60).json()
        yield from page["data"]
        if not page["has_more"]:
            return
        params["cursor"] = page["next_cursor"]

for invitation in invitations():
    write_to_warehouse(invitation)
```

| 100 000 invitations représentent 100 appels. Chargez-les en séquentiel : la limite est de 300 requêtes par minute et par clé.

## Créer la table

Une ligne par invitation, avec `id` comme clé. Les colonnes utiles pour l'analyse :

* **Identifiants** — `id`, `order.id`, `order.number`, `customer.email`, `customer.phone`
* **Envoi** — `source`, `sent_at`, `status`, `clicked_at`
* **Note laissée** — `review.rating`, `review.comment`, `review.submitted_at`
* **Suite donnée** — `routing.type`, `routing.destination`, `routing.published`, `routing.published_review.id`
* **Mise à jour** — `updated_at`

| `routing.published` et `routing.published_review` demandent le module **Connect** de Trustpilot, une option payante de Trustpilot Business connectée depuis la page [Intégrations](https://app.review-collect.com/home/integrations/). Sans ce module, ces deux champs restent vides.

Dans BigQuery, chargez chaque invitation telle quelle dans une colonne `JSON` et exposez ces colonnes dans une vue. Dans Snowflake, même principe avec une colonne `VARIANT`.

| Pour une ligne par message envoyé (initial, relance 1, relance 2), dépliez le tableau `messages` avec `UNNEST` dans BigQuery ou `LATERAL FLATTEN` dans Snowflake : chaque élément porte `step`, `channel` et `sent_at`.

## Mettre à jour chaque jour

1. Planifiez le script chaque matin
2. Passez le paramètre `since` avec l'heure de début de l'exécution précédente, moins cinq minutes
3. Fusionnez les lignes reçues sur `id` : mise à jour si la ligne existe, insertion sinon

Modèle BigQuery :

```
MERGE `dataset.invitations` t
USING `dataset.invitations_staging` s
ON t.id = s.id
WHEN MATCHED THEN UPDATE SET data = s.data, updated_at = s.updated_at
WHEN NOT MATCHED THEN INSERT (id, data, updated_at) VALUES (s.id, s.data, s.updated_at)
```

Le filtre `since` porte sur `updated_at` : une invitation envoyée en avril et notée en octobre revient dans l'exécution d'octobre. Une invitation revient à chaque changement, la fusion sur `id` la met simplement à jour.

| Les avis Trustpilot sont rapprochés sous 24 h. Pour un reporting hebdomadaire fiable, lisez la semaine deux jours après sa fin.