Référence de l'API
Clients
Créez, listez, mettez à jour et supprimez les personnes qui s'abonnent.
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
idstringIdentifiant unique du client.app_idstringL'application à laquelle appartient le client.namestringnullableLe nom du client.phone_numberstringnullableLe 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 anulljusqu'à ce qu'il paie. Son premier paiement réussi enregistre le numéro qui a payé et envoie un événementcustomer.updated.emailstringL'adresse e-mail du client. Abuna envoie à cette adresse tous les messages destinés au client.metadataobjectVos 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.languagestringnullableLa langue dans laquelle le client lit ses e-mails, ses messages Telegram, ses pages de paiement et son espace client :frouen. Le client peut la changer sur ces pages.nulljusqu'à 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.updatesobjectOù 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.Afficher les attributsMasquer les attributs
channelstringnullableLa messagerie choisie par le client :whatsapp,telegram, ounullpour l'e-mail seul.emailobjectContient unstatus, toujoursactive.telegramobjectContient unstatuset unconnected_at.connected_atest le moment où Telegram a été activé, en secondes Unix, etnulltant que le statut n'est pasactive. Le statut vautoff(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) oustopped(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 aussiconnect_url. Tant que le statut estpending, un lien qui active Telegram quand le client l'ouvre et appuie sur Démarrer, pour un bouton Activer les rappels dans votre application.nulldans tous les autres statuts.whatsappobjectContient unstatus, unconnected_atet unconnect_url, commetelegram.connected_atest le moment où le client a confirmé WhatsApp, en secondes Unix, etnulltant que le statut n'est pasactive. Le statut vautoff(non choisi, ou désactivé),active(activé, donc les messages vont aussi sur WhatsApp),stopped(le client a envoyéstopdans la discussion, donc les messages partent par e-mail seul jusqu'à ce qu'il confirme de nouveau son numéro) oufailed(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 jamaispending. Le client confirme son numéro avec un code quand il le choisit, donc il estactivedès qu'il l'a confirmé, etconnect_urlvaut toujoursnull.
created_attimestampQuand le client a été créé, en secondes Unix.
{
"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
Accepte un en-tête Idempotency-Key.
Crée un client.
Paramètres
emailstringobligatoireL'adresse e-mail du client.phone_numberstringobligatoireLe numéro de téléphone du client, avec son indicatif pays, comme+237671234567.namestringLe nom du client.metadataobjectVos propres clés et valeurs, comme l'ID de votre utilisateur. Voir Métadonnées pour les limites.languagestringfrouen: 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.
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"
}'{
"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
searchstringRenvoie 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 45trouve+237671234567.limitintegerCombien de clients renvoyer, de 1 à 100. Par défaut : 50.cursorstringLa valeurnext_cursorde la page précédente. Envoyez les mêmes filtres avec.
Attributs supplémentaires
telegram_connectedbooleanSi le client reçoit aussi ses messages sur Telegram.active_subscriptionsintegerCombien des abonnements du client sontactiveoupast_due(impayé).
Renvoie items et next_cursor, comme décrit dans Listes et filtres. 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.
curl "https://api.abuna.app/v1/apps/8ddhXCDW/customers?search=ana" \
-H "Authorization: Bearer sk_test_..."{
"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.
curl https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA \
-H "Authorization: Bearer sk_test_..."{
"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.
Paramètres
namestringLe nom du client. Envoyeznullpour l'effacer.emailstringL'adresse e-mail du client. Elle ne peut pas êtrenull.phone_numberstringLe numéro de téléphone du client, avec son indicatif pays. Abuna l'enregistre sous la forme+suivi de chiffres, donc00237 671-234-567devient+237671234567. Il ne peut pas êtrenull.metadataobjectRemplace le metadata du client par l'objet que vous envoyez.languagestringfrouen. Envoyeznullpour 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.
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"
}'{
"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 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
idstringL'ID du client.deletedbooleanToujourstrue.deleted_attimestampQuand le client a été supprimé, en secondes Unix.
Abuna envoie ensuite 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. 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
404avec le codenot_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.
curl -X DELETE https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA \
-H "Authorization: Bearer sk_test_..."{
"id": "Cu5tM8rA",
"deleted": true,
"deleted_at": 1727700000
}