Skip to content
ABUNA
S'inscrire
DocumentationClients

Référence de l'API

Clients

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

Un client est une personne qui vous paie. Vous créez un client, puis démarrez un abonnement pour lui.

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 les clients à vos utilisateurs par e-mail : un client peut changer son e-mail dans son espace client, et deux personnes peuvent en partager un.

L'objet customer

Attributs

  • idstring

    Identifiant unique du client.

  • app_idstring

    L'application à laquelle appartient le client.

  • namestringnullable

    Le nom du client.

  • phone_numberstring

    Le numéro de téléphone du client. Les demandes de paiement par mobile money vont à ce numéro.

  • emailstring

    L'adresse e-mail du client. Abuna envoie ici les avis 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 et ses pages de paiement et d'abonnement : 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.

  • 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
}

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
}

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 avis sur Telegram.

  • active_subscriptionsinteger

    Combien des abonnements du client sont active ou past_due.

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,
      "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
}

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

Étapes suivantes