Skip to content
ABUNA
DocumentationClients

Référence de l'API

Clients

Créez, listez, mettez à jour et supprimez les personnes qui s'abonnent.

Voir en Markdown

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

  • idstring

    Identifiant unique du client.
  • app_idstring

    L'application à laquelle appartient le client.
  • namestringnullable

    Le nom du client.
  • phone_numberstringnullable

    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 customer.updated.
  • emailstring

    L'adresse e-mail du client. Abuna envoie à cette adresse tous les messages destinés au client.
  • metadataobject

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

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

    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.
    Afficher les attributsMasquer les attributs
    • channelstringnullable

      La messagerie choisie par le client : whatsapp, telegram, ou null pour l'e-mail seul.
    • emailobject

      Contient un status, toujours active.
    • telegramobject

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

      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_attimestamp

    Quand le client a été créé, en secondes Unix.
L'objet customer
{
  "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

  • emailstringobligatoire

    L'adresse e-mail du client.
  • phone_numberstringobligatoire

    Le numéro de téléphone du client, avec son indicatif pays, comme +237671234567.
  • namestring

    Le nom du client.
  • metadataobject

    Vos propres clés et valeurs, comme l'ID de votre utilisateur. Voir Métadonnées pour les limites.
  • languagestring

    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 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"
  }'
Réponse
{
  "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

  • searchstring

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

    Combien de clients renvoyer, de 1 à 100. Par défaut : 50.
  • cursorstring

    La valeur next_cursor de la page précédente. Envoyez les mêmes filtres avec.

Attributs supplémentaires

  • telegram_connectedboolean

    Si le client reçoit aussi ses messages sur Telegram.
  • active_subscriptionsinteger

    Combien des abonnements du client sont active ou past_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.

GET /v1/apps/{appID}/customers
curl "https://api.abuna.app/v1/apps/8ddhXCDW/customers?search=ana" \
  -H "Authorization: Bearer sk_test_..."
Réponse
{
  "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 https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA \
  -H "Authorization: Bearer sk_test_..."
Réponse
{
  "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

  • namestring

    Le nom du client. Envoyez null pour l'effacer.
  • emailstring

    L'adresse e-mail du client. Elle ne peut pas être null.
  • phone_numberstring

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

    Remplace le metadata du client par l'objet que vous envoyez.
  • languagestring

    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 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"
  }'
Réponse
{
  "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

  • idstring

    L'ID du client.
  • deletedboolean

    Toujours true.
  • deleted_attimestamp

    Quand 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 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 -X DELETE https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA \
  -H "Authorization: Bearer sk_test_..."
Réponse
{
  "id": "Cu5tM8rA",
  "deleted": true,
  "deleted_at": 1727700000
}

Étapes suivantes