> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chataigne.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Vue d’ensemble de la gestion des clients

> Listez les clients et consultez leur activité limitée à un établissement ou à une organisation Chataigne.

L’API de gestion des clients fournit une vue en lecture seule des clients ayant interagi avec un établissement ou une organisation Chataigne. Elle est destinée aux restaurants et aux intégrateurs qui ont besoin de l’identité du client, de son consentement marketing et de son activité commerciale limitée au bon périmètre, sans recevoir d’identifiants fournisseur ni de données personnelles inutiles.

## Endpoints

| Besoin                                             | Opération                                                         |
| -------------------------------------------------- | ----------------------------------------------------------------- |
| Lister les clients visibles dans un établissement  | `GET /v1/locations/{location_id}/customers`                       |
| Consulter un client dans un établissement          | `GET /v1/locations/{location_id}/customers/{customer_id}`         |
| Lister les clients d’une organisation              | `GET /v1/organizations/{organization_id}/customers`               |
| Consulter un client à l’échelle d’une organisation | `GET /v1/organizations/{organization_id}/customers/{customer_id}` |

Chaque opération nécessite `customers.read`. Le `customer_id` est l’identifiant stable du profil client Chataigne, limité à son propriétaire et retourné par les endpoints de liste.

## Le périmètre détermine chaque agrégat

La route — et non la portée maximale de la clé API — détermine l’activité incluse dans le détail d’un client :

* Une route d’établissement compte uniquement les commandes et interactions de cet établissement.
* Une route d’organisation compte l’activité de cette organisation et de ses établissements.
* Une clé d’organisation parente qui appelle une route d’établissement reçoit toujours des totaux limités à cet établissement.
* Un identifiant client qui n’est pas visible dans le périmètre demandé retourne `404`.

Par exemple, si un client a effectué 100 USD de commandes terminées dans une organisation, dont 30 USD dans un établissement donné, le détail de l’établissement retourne 30 USD. Le détail de l’organisation retourne 100 USD.

<Warning>
  N’additionnez jamais les totaux d’un établissement à ceux de l’organisation. Le montant de
  l’établissement est déjà inclus dans celui de l’organisation.
</Warning>

## Lister les clients

Les listes utilisent l’enveloppe de pagination par curseur standard. Chaque élément contient les champs nécessaires pour identifier et contacter un client, ainsi que son consentement marketing :

```json theme={null}
{
  "id": "5ab32816-690d-4f09-874c-16c4cc72624d",
  "object": "customer",
  "created_at": "2026-07-01T10:00:00.000Z",
  "updated_at": "2026-07-12T15:30:00.000Z",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "ada@example.com",
  "phone": "+33612345678",
  "language": "fr",
  "marketing_consent": {
    "status": "opted_in",
    "changed_at": "2026-07-10T14:30:00.000Z"
  },
  "completed_orders_count": 8
}
```

Utilisez `limit`, `starting_after` et `ending_before` comme décrit dans [Pagination](/fr/concepts/pagination). Les filtres `created_after`, `created_before`, `updated_after` et `updated_before` s’appliquent aux horodatages du profil client.

## Filtrer les listes de clients

Les listes de clients proposent deux filtres de segmentation côté serveur :

* **`marketing_consent_status`** accepte `opted_in`, `opted_out` ou `unknown`. Il retourne les clients ayant ce statut ; une absence d’enregistrement de consentement correspond à `unknown`.
* **`min_completed_orders`** accepte un entier positif ou nul. Il retourne les clients ayant au moins ce nombre de commandes terminées dans le périmètre demandé par la route.

Par exemple, cette requête retourne les clients ayant accepté les communications marketing et terminé au moins deux commandes dans l’établissement sélectionné :

```http theme={null}
GET /v1/locations/{location_id}/customers?marketing_consent_status=opted_in&min_completed_orders=2
```

Les filtres se combinent avec un opérateur `AND` et s’appliquent avant la pagination par curseur. La valeur `completed_orders_count` de chaque élément utilise le même périmètre que `min_completed_orders` : un seul établissement pour les routes d’établissement, ou l’organisation et ses établissements pour les routes d’organisation.

## Consulter le détail d’un client

Le détail ajoute l’activité et les agrégats des commandes terminées dans le périmètre de la route :

```json theme={null}
{
  "id": "5ab32816-690d-4f09-874c-16c4cc72624d",
  "object": "customer",
  "created_at": "2026-07-01T10:00:00.000Z",
  "updated_at": "2026-07-12T15:30:00.000Z",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "ada@example.com",
  "phone": "+33612345678",
  "language": "fr",
  "marketing_consent": {
    "status": "opted_in",
    "changed_at": "2026-07-10T14:30:00.000Z"
  },
  "first_interaction_at": "2026-07-01T10:00:00.000Z",
  "last_interaction_at": "2026-07-12T15:30:00.000Z",
  "last_order_at": "2026-07-10T19:45:00.000Z",
  "completed_orders_count": 8,
  "total_spent": [
    {
      "amount": 184.5,
      "currency": "EUR"
    }
  ]
}
```

`total_spent` est un tableau, car une organisation peut contenir des établissements utilisant des devises différentes. Les montants de devises différentes ne sont jamais additionnés. `last_order_at` correspond à la commande la plus récente, quel que soit son statut, tandis que `completed_orders_count` et `total_spent` incluent uniquement les commandes terminées.

## Consentement marketing

`marketing_consent.status` accepte trois valeurs :

| Statut      | Signification                                           |
| ----------- | ------------------------------------------------------- |
| `opted_in`  | Le client accepte explicitement les messages marketing. |
| `opted_out` | Le client refuse explicitement les messages marketing.  |
| `unknown`   | Chataigne ne dispose d’aucune décision explicite.       |

`changed_at` vaut `null` lorsque le statut est `unknown` et qu’aucune décision n’existe. Traitez `unknown` comme un état distinct ; ne l’interprétez pas comme un opt-in.

## Données volontairement exclues

Cette première version ne retourne ni adresse, ni identifiant ou URL de commande, ni donnée de paiement, ni identifiant Stripe, WhatsApp ou Instagram, ni mémoire IA, ni ancien identifiant client, ni identifiant global de la personne. Les profils clients effacés sont exclus des listes et ne peuvent pas être consultés.