Skip to main content
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

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.
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.

​
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 :
Utilisez limit, starting_after et ending_before comme décrit dans 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é :
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 :
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 : 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.