# Clients > Créez, listez, mettez à jour et supprimez les personnes qui s'abonnent. Source : https://abuna.app/docs/api/customers?hl=fr Créez, listez, récupérez, modifiez et supprimez les clients que vous facturez. Vous créez d'abord le client, puis vous lui démarrez un abonnement. Pour lier un client à un utilisateur de votre propre application, placez l'ID de votre utilisateur dans le `metadata` du client, ou stockez l'`id` du client à côté de votre utilisateur. Ne reliez pas vos clients à vos utilisateurs par leur e-mail. Un client peut changer d'e-mail depuis son espace client, et deux personnes peuvent partager la même adresse. ## L'objet customer **Attributs** - `id` (string): Identifiant unique du client. - `app_id` (string): L'application à laquelle appartient le client. - `name` (string, nullable): Le nom du client. - `phone_number` (string, nullable): Le numéro de téléphone du client. Les demandes de paiement par mobile money vont à ce numéro. La page d'abonnement le demande à l'étape de paiement, donc un client venu par la page d'abonnement a `null` jusqu'à ce qu'il paie. Son premier paiement réussi enregistre le numéro qui a payé et envoie un [événement](https://abuna.app/docs/api/events.md?hl=fr#customer-updated) `customer.updated`. - `email` (string): L'adresse e-mail du client. Abuna envoie à cette adresse tous les messages destinés au client. - `metadata` (object): Vos propres clés et valeurs, comme l'ID de votre utilisateur. `{}` quand il n'y en a aucune. Les événements sur le client le portent. Les limites sont les mêmes que pour le [metadata d'abonnement](https://abuna.app/docs/api/subscriptions.md?hl=fr#metadata). - `language` (string, nullable): La langue dans laquelle le client lit ses e-mails, ses messages Telegram, ses pages de paiement et son espace client : `fr` ou `en`. Le client peut la changer sur ces pages. `null` jusqu'à ce que vous ou le client la définissiez : ses pages suivent alors la langue de son navigateur, et tout le reste est en français. - `updates` (object): Où vont les messages et les rappels de paiement du client. L'e-mail part toujours, et une messagerie peut s'y ajouter. Abuna n'affiche jamais ici d'identifiant de conversation ni de numéro de téléphone. - `channel` (string, nullable): La messagerie choisie par le client : `whatsapp`, `telegram`, ou `null` pour l'e-mail seul. - `email` (object): Contient un `status`, toujours `active`. - `telegram` (object): Contient un `status` et un `connected_at`. `connected_at` est le moment où Telegram a été activé, en secondes Unix, et `null` tant que le statut n'est pas `active`. Le statut vaut `off` (non choisi, ou désactivé), `pending` (choisi, en attente que le client l'active dans Telegram), `active` (activé, donc les messages vont aussi sur Telegram) ou `stopped` (le client l'a arrêté depuis Telegram, donc les messages partent par e-mail seul jusqu'à ce qu'il le réactive). Il contient aussi `connect_url`. Tant que le statut est `pending`, un lien qui active Telegram quand le client l'ouvre et appuie sur **Démarrer**, pour un bouton **Activer les rappels** dans votre application. `null` dans tous les autres statuts. - `whatsapp` (object): Contient un `status`, un `connected_at` et un `connect_url`, comme `telegram`. `connected_at` est le moment où le client a confirmé WhatsApp, en secondes Unix, et `null` tant que le statut n'est pas `active`. Le statut vaut `off` (non choisi, ou désactivé), `active` (activé, donc les messages vont aussi sur WhatsApp), `stopped` (le client a envoyé `stop` dans la discussion, donc les messages partent par e-mail seul jusqu'à ce qu'il confirme de nouveau son numéro) ou `failed` (le numéro ne peut pas recevoir de messages WhatsApp, donc les messages partent par e-mail seul jusqu'à ce que le client donne un autre numéro). WhatsApp n'est jamais `pending`. Le client confirme son numéro avec un code quand il le choisit, donc il est `active` dès qu'il l'a confirmé, et `connect_url` vaut toujours `null`. - `created_at` (timestamp): Quand le client a été créé, en secondes Unix. **L'objet customer** ```json { "id": "Cu5tM8rA", "app_id": "8ddhXCDW", "name": "Jane Doe", "phone_number": "+237671234567", "email": "jane@example.com", "metadata": { "user_id": "42" }, "language": "fr", "created_at": 1727600000, "updates": { "channel": "telegram", "email": { "status": "active" }, "telegram": { "status": "active", "connected_at": 1727600300, "connect_url": null }, "whatsapp": { "status": "off", "connected_at": null, "connect_url": null } } } ``` ## Créer un client `POST /v1/apps/{appID}/customers` Crée un client. **Paramètres** - `email` (string, obligatoire): L'adresse e-mail du client. - `phone_number` (string, obligatoire): Le numéro de téléphone du client, avec son indicatif pays, comme `+237671234567`. - `name` (string): Le nom du client. - `metadata` (object): Vos propres clés et valeurs, comme l'ID de votre utilisateur. Voir [Métadonnées](https://abuna.app/docs/api/subscriptions.md?hl=fr#metadata) pour les limites. - `language` (string): `fr` ou `en` : la langue des e-mails, des messages Telegram et des pages du client. Laissez-le de côté si vous ne la connaissez pas. Renvoie le client avec le statut `201`. Un e-mail ou un numéro de téléphone manquant renvoie `422` avec le code `invalid`, et de même pour un `metadata` au-delà de ses limites et toute `language` autre que `fr` ou `en`. Un champ inconnu renvoie `400` avec le code `invalid_json`. **POST /v1/apps/{appID}/customers** cURL : ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/customers \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{ "name": "Jane Doe", "email": "jane@example.com", "phone_number": "+237671234567", "metadata": {"user_id": "42"}, "language": "fr" }' ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/customers", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ name: "Jane Doe", email: "jane@example.com", phone_number: "+237671234567", metadata: { user_id: "42" }, language: "fr", }), }); const customer = await response.json(); ``` Python : ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/customers", headers={"Authorization": "Bearer sk_test_..."}, json={ "name": "Jane Doe", "email": "jane@example.com", "phone_number": "+237671234567", "metadata": {"user_id": "42"}, "language": "fr", }, ) customer = response.json() ``` PHP : ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "name" => "Jane Doe", "email" => "jane@example.com", "phone_number" => "+237671234567", "metadata" => ["user_id" => "42"], "language" => "fr", ]), CURLOPT_RETURNTRANSFER => true, ]); $customer = json_decode(curl_exec($ch), true); ``` Go : ```go body, _ := json.Marshal(map[string]any{ "name": "Jane Doe", "email": "jane@example.com", "phone_number": "+237671234567", "metadata": map[string]any{"user_id": "42"}, "language": "fr", }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/customers", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var customer map[string]any json.NewDecoder(res.Body).Decode(&customer) ``` **Réponse** ```json { "id": "Cu5tM8rA", "app_id": "8ddhXCDW", "name": "Jane Doe", "phone_number": "+237671234567", "email": "jane@example.com", "metadata": { "user_id": "42" }, "language": "fr", "created_at": 1727600000, "updates": { "channel": "telegram", "email": { "status": "active" }, "telegram": { "status": "active", "connected_at": 1727600300, "connect_url": null }, "whatsapp": { "status": "off", "connected_at": null, "connect_url": null } } } ``` ## Lister les clients `GET /v1/apps/{appID}/customers` Liste les clients de l'application, du plus récent au plus ancien, une page à la fois. Chacun a deux champs de plus que l'objet customer. **Paramètres de requête** - `search` (string): Renvoie uniquement les clients dont le nom ou l'e-mail contient ce texte. La casse n'a pas d'importance. Une recherche qui ressemble à un numéro de téléphone, des chiffres avec un `+` facultatif, des espaces, des tirets, des points ou des parenthèses, correspond aussi aux numéros de téléphone sur les seuls chiffres : `671 23 45` trouve `+237671234567`. - `limit` (integer): Combien de clients renvoyer, de 1 à 100. Par défaut : 50. - `cursor` (string): La valeur `next_cursor` de la page précédente. Envoyez les mêmes filtres avec. **Attributs supplémentaires** - `telegram_connected` (boolean): Si le client reçoit aussi ses messages sur Telegram. - `active_subscriptions` (integer): Combien des abonnements du client sont `active` ou `past_due` (impayé). Renvoie `items` et `next_cursor`, comme décrit dans [Listes et filtres](https://abuna.app/docs/lists-and-filters.md?hl=fr#pages). Une valeur non autorisée, comme un `limit` supérieur à 100, renvoie `422` avec le code `invalid` et le nom du paramètre dans `errors`. **GET /v1/apps/{appID}/customers** cURL : ```bash curl "https://api.abuna.app/v1/apps/8ddhXCDW/customers?search=ana" \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/customers?search=ana", { headers: { Authorization: "Bearer sk_test_..." }, }); const page = await response.json(); ``` Python : ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/customers?search=ana", headers={"Authorization": "Bearer sk_test_..."}, ) page = response.json() ``` PHP : ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $page = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/customers?search=ana", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var page map[string]any json.NewDecoder(res.Body).Decode(&page) ``` **Réponse** ```json { "items": [ { "id": "Cu5tM8rA", "app_id": "8ddhXCDW", "name": "Jane Doe", "phone_number": "+237671234567", "email": "jane@example.com", "metadata": { "user_id": "42" }, "language": "fr", "created_at": 1727600000, "updates": { "channel": null, "email": { "status": "active" }, "telegram": { "status": "off", "connected_at": null, "connect_url": null }, "whatsapp": { "status": "off", "connected_at": null, "connect_url": null } }, "telegram_connected": false, "active_subscriptions": 1 } ], "next_cursor": null } ``` ## Récupérer un client `GET /v1/apps/{appID}/customers/{id}` Récupère un client. Renvoie le client. Si l'application n'a aucun client avec cet ID, renvoie `404` avec le code `not_found`. **GET /v1/apps/{appID}/customers/{id}** cURL : ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA", { headers: { Authorization: "Bearer sk_test_..." }, }); const customer = await response.json(); ``` Python : ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA", headers={"Authorization": "Bearer sk_test_..."}, ) customer = response.json() ``` PHP : ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $customer = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var customer map[string]any json.NewDecoder(res.Body).Decode(&customer) ``` **Réponse** ```json { "id": "Cu5tM8rA", "app_id": "8ddhXCDW", "name": "Jane Doe", "phone_number": "+237671234567", "email": "jane@example.com", "metadata": { "user_id": "42" }, "language": "fr", "created_at": 1727600000, "updates": { "channel": "telegram", "email": { "status": "active" }, "telegram": { "status": "active", "connected_at": 1727600300, "connect_url": null }, "whatsapp": { "status": "off", "connected_at": null, "connect_url": null } } } ``` ## Mettre à jour un client `PATCH /v1/apps/{appID}/customers/{id}` Met à jour les champs que vous envoyez et laisse les autres tels quels. Si le nom, l'e-mail, le numéro de téléphone ou le metadata a changé, Abuna enregistre un `customer.updated` [événement](https://abuna.app/docs/api/events.md?hl=fr). **Paramètres** - `name` (string): Le nom du client. Envoyez `null` pour l'effacer. - `email` (string): L'adresse e-mail du client. Elle ne peut pas être `null`. - `phone_number` (string): Le numéro de téléphone du client, avec son indicatif pays. Abuna l'enregistre sous la forme `+` suivi de chiffres, donc `00237 671-234-567` devient `+237671234567`. Il ne peut pas être `null`. - `metadata` (object): Remplace le metadata du client par l'objet que vous envoyez. - `language` (string): `fr` ou `en`. Envoyez `null` pour l'effacer, afin que les pages du client suivent son navigateur et que tout le reste soit en français. Renvoie le client. Un champ invalide ou un champ inconnu renvoie `422` avec le code `invalid`. Un `name`, `email`, `phone_number` ou `language` qui n'est ni une chaîne ni `null` renvoie `400` avec le code `invalid_json` et un élément `errors` pour ce champ. Si l'application n'a aucun client avec cet ID, renvoie `404` avec le code `not_found`. **PATCH /v1/apps/{appID}/customers/{id}** cURL : ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -X PATCH \ -d '{ "email": "jane.doe@example.com" }' ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA", { method: "PATCH", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ email: "jane.doe@example.com", }), }); const customer = await response.json(); ``` Python : ```python import requests response = requests.patch( "https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA", headers={"Authorization": "Bearer sk_test_..."}, json={ "email": "jane.doe@example.com", }, ) customer = response.json() ``` PHP : ```php "PATCH", CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "email" => "jane.doe@example.com", ]), CURLOPT_RETURNTRANSFER => true, ]); $customer = json_decode(curl_exec($ch), true); ``` Go : ```go body, _ := json.Marshal(map[string]any{ "email": "jane.doe@example.com", }) req, _ := http.NewRequest("PATCH", "https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var customer map[string]any json.NewDecoder(res.Body).Decode(&customer) ``` **Réponse** ```json { "id": "Cu5tM8rA", "app_id": "8ddhXCDW", "name": "Jane Doe", "phone_number": "+237671234567", "email": "jane.doe@example.com", "metadata": { "user_id": "42" }, "language": "fr", "created_at": 1727600000, "updates": { "channel": "telegram", "email": { "status": "active" }, "telegram": { "status": "active", "connected_at": 1727600300, "connect_url": null }, "whatsapp": { "status": "off", "connected_at": null, "connect_url": null } } } ``` ## Supprimer un client `DELETE /v1/apps/{appID}/customers/{id}` Supprime un client et efface ses données personnelles. Utilisez-le quand un client vous demande de supprimer ses données. Vous ne pouvez pas l'annuler. D'abord, chaque abonnement du client qui n'a pas pris fin (`pending`, `trialing`, `active` ou `past_due`) prend fin tout de suite, comme si vous l'aviez résilié. Chacun envoie [`subscription.canceled`](https://abuna.app/docs/api/events.md?hl=fr#subscription-canceled) avec la raison `merchant`, et le client reçoit le message habituel qui lui annonce la fin de son abonnement. Ensuite, Abuna efface le nom, l'e-mail, le numéro de téléphone, les informations Telegram et WhatsApp et le metadata du client, y compris sur ses anciennes factures, ses messages et ses événements. L'ID du client, ses factures, leurs numéros, ses paiements et leurs montants restent, donc vos totaux ne changent pas. **Attributs de la réponse** - `id` (string): L'ID du client. - `deleted` (boolean): Toujours `true`. - `deleted_at` (timestamp): Quand le client a été supprimé, en secondes Unix. Abuna envoie ensuite [`customer.deleted`](https://abuna.app/docs/api/events.md?hl=fr#customer-deleted). Quand vous le recevez, supprimez votre propre copie des données du client. Supprimer un client déjà supprimé renvoie la même réponse et n'envoie aucun nouvel événement. Comme les autres écritures, il accepte un [`Idempotency-Key`](https://abuna.app/docs/errors.md?hl=fr#idempotency). Si l'application n'a aucun client avec cet ID, renvoie `404` avec le code `not_found`. Une fois le client supprimé : - Le récupérer, le mettre à jour, lui démarrer un abonnement ou créer une session pour lui renvoie `404` avec le code `not_found`. - La liste des clients ne l'inclut plus. - Ses liens de paiement, d'espace client et de résiliation ouvrent une page qui indique que le lien a expiré. Votre clé secrète peut toujours supprimer un client. Dans le tableau de bord, seuls les propriétaires d'équipe le peuvent. **DELETE /v1/apps/{appID}/customers/{id}** cURL : ```bash curl -X DELETE https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA", { method: "DELETE", headers: { Authorization: "Bearer sk_test_..." }, }); const deleted = await response.json(); ``` Python : ```python import requests response = requests.delete( "https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA", headers={"Authorization": "Bearer sk_test_..."}, ) deleted = response.json() ``` PHP : ```php "DELETE", CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $deleted = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("DELETE", "https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var deleted map[string]any json.NewDecoder(res.Body).Decode(&deleted) ``` **Réponse** ```json { "id": "Cu5tM8rA", "deleted": true, "deleted_at": 1727700000 } ```