> ## Documentation Index
> Fetch the complete documentation index at: https://help.withallo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vue d'ensemble

> Faites tourner votre propre produit sur l'API d'Allo : gérez les membres, les numéros, les eSIM, les suspensions et les Sender ID des comptes que vous créez, sous votre marque.

La **marque blanche** s'adresse aux partenaires qui construisent leur propre produit sur l'API d'Allo. Leurs utilisateurs finaux n'utilisent jamais l'application Allo : ils utilisent l'outil du partenaire, et leur numéro Allo fait sonner une eSIM dans leur téléphone. Le logiciel du partenaire gère tout le reste par l'API : membres, numéros, eSIM, suspensions et Sender ID.

Si vous revendez Allo et que vos clients utilisent l'application Allo, les endpoints [Partenaires](https://help.withallo.com/fr/v2/api-reference/partner/overview.md) vous suffisent.

Les endpoints marque blanche utilisent la même clé `PARTNER`, la même authentification et la même facturation que les endpoints Partenaires. Commencez par la [vue d'ensemble Partenaires](https://help.withallo.com/fr/v2/api-reference/partner/overview.md) pour obtenir l'accès, puis créez chaque compte avec [Créer un compte](https://help.withallo.com/fr/v2/api-reference/partner/create-account.md).

## Comment ajouter des numéros et des membres à un compte

Un compte démarre avec un numéro. Vous pouvez ensuite le compléter depuis l'API :

* [Ajouter un numéro](https://help.withallo.com/fr/v2/api-reference/white-label/add-number.md) donne un numéro de plus au compte. Il est facturé sur l'abonnement du compte, sauf si le compte paie déjà un emplacement de numéro libre. Appelez d'abord [Obtenir le prix d'un numéro](https://help.withallo.com/fr/v2/api-reference/white-label/get-number-price.md) pour connaître le montant.
* [Ajouter un membre](https://help.withallo.com/fr/v2/api-reference/white-label/add-member.md) ajoute un collaborateur au compte, avec son propre numéro. Le membre occupe un siège sur l'abonnement du compte, et ce siège inclut son numéro. Allo n'envoie aucun email d'invitation au membre : c'est vous qui l'accompagnez.
* [Lister les membres](https://help.withallo.com/fr/v2/api-reference/white-label/list-members.md) renvoie les membres du compte et leurs numéros.
* [Retirer un membre](https://help.withallo.com/fr/v2/api-reference/white-label/remove-member.md) retire un membre du compte et garde ses numéros sur le compte.

Allo vérifie qu'un numéro est disponible avant tout débit. Si aucun ne correspond, la requête échoue avec `409 NO_NUMBER_AVAILABLE` et rien n'est débité.

## Comment fournir une eSIM à un compte

Une eSIM installe le numéro Allo du compte dans le téléphone de votre client, comme une deuxième SIM. Les appels arrivent sur le téléphone par le réseau mobile français. Les eSIM sont disponibles en France uniquement, sur des numéros créés pour elles.

**1. Créez le compte avec un numéro eSIM**

Appelez [Créer un compte](https://help.withallo.com/fr/v2/api-reference/partner/create-account.md) avec `number_preference: {"country": "FR", "esim": true}`. Ajoutez un `prefix`, par exemple `"7"`, pour choisir le début du numéro. Le compte reçoit un numéro mobile français qui peut porter une eSIM. [Ajouter un numéro](https://help.withallo.com/fr/v2/api-reference/white-label/add-number.md) et [Ajouter un membre](https://help.withallo.com/fr/v2/api-reference/white-label/add-member.md) acceptent le même `esim: true` pour les numéros ajoutés ensuite.

**2. Obtenez l'offre**

Appelez [Obtenir l'offre eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/get-esim-offer.md) pour connaître les frais de mise en service et les paliers de données. Les prix suivent l'abonnement que vous payez pour ce compte : sa devise, sa périodicité de facturation et votre remise partenaire.

**3. Commandez l'eSIM**

Appelez [Commander une eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/order-esim.md) avec le numéro, un palier et l'identité de l'entreprise à laquelle la ligne est enregistrée. Pour le numéro d'un membre, envoyez l'`id` du membre comme `holder_id`. Allo débite la commande sur votre crédit prépayé en priorité, puis sur votre carte enregistrée, et renvoie l'eSIM avec le statut `PROVISIONING`. Envoyez un en-tête `Idempotency-Key` pour qu'une nouvelle tentative ne vous débite jamais deux fois.

**4. Attendez que l'eSIM soit prête**

L'eSIM est en général prête 5 à 15 minutes plus tard. Allo envoie alors [`partner.esim.ready`](https://help.withallo.com/fr/v2/api-reference/webhooks/event-catalog#partneresimready) à votre propre endpoint webhook, pas à celui du compte. À partir de ce moment, les appels vers le numéro sonnent sur l'eSIM. Si la commande échoue, vous recevez [`partner.esim.failed`](https://help.withallo.com/fr/v2/api-reference/webhooks/event-catalog#partneresimfailed) à la place. Sans endpoint webhook, interrogez [Obtenir une eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/get-esim.md).

**5. Obtenez le code d'activation**

Appelez [Obtenir le code d'activation d'une eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/get-esim-activation-code.md). Il renvoie un QR code, les valeurs pour la saisie manuelle et le code pour construire un lien d'installation sur iPhone.

**6. Remettez l'eSIM à votre client**

Envoyez le QR code ou le lien d'installation à votre client, sous votre propre marque. Votre client installe l'eSIM sur son téléphone.

> [!NOTE]
>
> Allo n'envoie jamais d'email à votre client au sujet de l'eSIM. C'est vous qui lui remettez le code d'activation. Allo ne détecte pas l'installation de l'eSIM par votre client.

## Comment suspendre un compte pour factures impayées

Quand votre client ne vous paie plus, appelez [Suspendre un compte](https://help.withallo.com/fr/v2/api-reference/white-label/suspend-account.md). Les appels, les SMS sortants, la réceptionniste IA et les lignes eSIM du compte s'arrêtent immédiatement, pour tous les membres. Le compte garde ses numéros, ses eSIM et son historique.

Quand votre client a payé, appelez [Réactiver un compte](https://help.withallo.com/fr/v2/api-reference/white-label/resume-account.md). Tout fonctionne à nouveau, sur les mêmes numéros.

* Une suspension ne change pas la facturation : l'abonnement que vous payez pour le compte continue. Pour ne plus payer le compte, [désactivez-le](https://help.withallo.com/fr/v2/api-reference/partner/delete-account.md) à la place.
* Allo envoie [`partner.account.suspended`](https://help.withallo.com/fr/v2/api-reference/webhooks/event-catalog#partneraccountsuspended) et [`partner.account.resumed`](https://help.withallo.com/fr/v2/api-reference/webhooks/event-catalog#partneraccountresumed) à votre endpoint webhook. Tant que le compte est suspendu, [Obtenir un compte](https://help.withallo.com/fr/v2/api-reference/partner/get-account.md) renvoie `status: SUSPENDED`, tout comme chaque membre dans [Lister les membres](https://help.withallo.com/fr/v2/api-reference/white-label/list-members.md).

## Comment remplacer un collaborateur qui part

Quand un collaborateur quitte l'entreprise de votre client, vous pouvez couper son téléphone, puis donner son numéro, avec son historique, à la personne qui le remplace.

**1. Retirez le collaborateur**

Appelez [Retirer un membre](https://help.withallo.com/fr/v2/api-reference/white-label/remove-member.md) (`DELETE /v2/api/partner/accounts/{id}/members/{member_id}`). Allo révoque ses eSIM immédiatement : son téléphone cesse de sonner. Ses numéros restent sur le compte et sonnent sur les apps Allo. Son siège reste payé jusqu'à la fin de la période en cours, puis les numéros sont facturés comme numéros supplémentaires.

**2. Ajoutez le nouveau collaborateur sur le même numéro**

Appelez [Ajouter un membre](https://help.withallo.com/fr/v2/api-reference/white-label/add-member.md) avec le numéro conservé comme `phone_number`, à la place de `number_preference`. Le nouveau membre reprend le numéro avec son historique d'appels et de messages, sur un siège facturé comme pour tout nouveau membre. Comme le siège inclut le numéro, Allo retire un numéro supplémentaire de l'abonnement.

**3. Donnez une eSIM au nouveau collaborateur**

Appelez [Commander une eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/order-esim.md) avec le même `phone_number` et l'`id` du nouveau membre comme `holder_id`. La commande facture les frais de mise en service. Remettez ensuite l'eSIM comme d'habitude, dès réception de [`partner.esim.ready`](https://help.withallo.com/fr/v2/api-reference/webhooks/event-catalog#partneresimready).

Pour couper une seule eSIM sans retirer personne, par exemple pour un téléphone perdu, appelez [Révoquer une eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/revoke-esim.md).

## Comment permettre à un compte d'envoyer des SMS sous le nom de sa marque

Un Sender ID est le nom que les destinataires voient à la place d'un numéro, par exemple `PLOMBMARTIN`. En France, les SMS automatisés ne peuvent pas partir d'un numéro mobile : le Sender ID est donc ce qui permet à votre logiciel d'écrire aux clients du compte.

**1. Déclarez le Sender ID**

Appelez [Déclarer un Sender ID](https://help.withallo.com/fr/v2/api-reference/white-label/create-sender-id.md) avec le nom, de 1 à 11 lettres ou chiffres, et un exemple de message optionnel. Un Sender ID n'appartient qu'à un seul compte Allo, et un compte en détient au plus 3. Le Sender ID démarre avec le statut `PENDING`.

**2. Attendez la validation d'Allo**

Allo valide le Sender ID à la main, en général en 1 à 5 jours ouvrés. Allo envoie ensuite [`partner.sender_id.validated`](https://help.withallo.com/fr/v2/api-reference/webhooks/event-catalog#partnersender_idvalidated) ou [`partner.sender_id.failed`](https://help.withallo.com/fr/v2/api-reference/webhooks/event-catalog#partnersender_idfailed) à votre propre endpoint webhook, pas à celui du compte. Sans endpoint webhook, interrogez [Obtenir un Sender ID](https://help.withallo.com/fr/v2/api-reference/white-label/get-sender-id.md).

**3. Envoyez des SMS avec lui**

Une fois le Sender ID `VALIDATED`, le compte envoie des SMS avec [Envoyer un SMS (France)](https://help.withallo.com/fr/v2/api-reference/sms/send-sms-france.md) : `POST /v1/api/sms` avec `sender_id` à la place de `from`, avec la clé API du compte, qui doit porter le scope `SMS_SEND`.

```json theme={null}
{
  "sender_id": "PLOMBMARTIN",
  "to": "+33612345678",
  "message": "Bonjour, votre intervention est confirmée demain à 9h."
}
```

> [!NOTE]
>
> Allo peut désactiver un Sender ID après l'avoir validé. Son statut passe à `DISABLED` et l'envoi avec lui est refusé. Aucun webhook n'est envoyé pour ce changement : consultez [Obtenir un Sender ID](https://help.withallo.com/fr/v2/api-reference/white-label/get-sender-id.md) ou [Lister les Sender ID](https://help.withallo.com/fr/v2/api-reference/white-label/list-sender-ids.md) pour le vérifier.

## Comment modifier les données d'une eSIM

Chaque eSIM a un palier de données, renouvelé avec l'abonnement que vous payez pour le compte. Vous pouvez le changer, ou ajouter des données pour le mois en cours, depuis l'API :

* [Changer le palier d'une eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/change-esim-tier.md) fait passer l'eSIM à un autre palier. Une montée de palier est débitée tout de suite, au prorata du reste de la période de facturation, et ses données en plus sont ajoutées en une minute environ. Une baisse de palier s'applique à la fin de la période déjà payée, et rien n'est remboursé.
* [Acheter une recharge de données eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/buy-esim-topup.md) ajoute 5, 10 ou 20 Go à l'eSIM pour le mois civil en cours (heure de Paris), contre un débit unique. Les données de recharge non utilisées sont perdues à la fin de ce mois.

Les deux sont débités comme tout débit partenaire : crédit prépayé d'abord, puis carte enregistrée. [Obtenir l'offre eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/get-esim-offer.md) renvoie le prix des paliers et des recharges. Envoyez un en-tête `Idempotency-Key` avec ces deux requêtes, pour qu'une nouvelle tentative ne vous débite jamais deux fois. Il est obligatoire pour acheter une recharge.

[Obtenir une eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/get-esim.md) renvoie les données utilisées ce mois-ci dans `data`. Quand une eSIM atteint son quota, les données mobiles s'arrêtent jusqu'au mois suivant ou jusqu'à une recharge, mais les appels et les SMS continuent de fonctionner. Allo envoie [`partner.esim.data_low`](https://help.withallo.com/fr/v2/api-reference/webhooks/event-catalog#partneresimdata_low) à 80 % du quota et [`partner.esim.data_exhausted`](https://help.withallo.com/fr/v2/api-reference/webhooks/event-catalog#partneresimdata_exhausted) à 100 %.

## Endpoints

| Méthode | Chemin | Description |
| - | - | - |
| `POST` | `/v2/api/partner/accounts/{id}/suspend` | Suspendre un compte immédiatement : appels, SMS et lignes eSIM s'arrêtent, numéros et facturation restent |
| `POST` | `/v2/api/partner/accounts/{id}/resume` | Réactiver un compte suspendu |
| `GET` | `/v2/api/partner/accounts/{id}/numbers/price` | Obtenir le prix d'un numéro de plus sur un compte |
| `POST` | `/v2/api/partner/accounts/{id}/numbers` | Ajouter un numéro à un compte, facturé sur son abonnement |
| `POST` | `/v2/api/partner/accounts/{id}/members` | Ajouter un membre à un compte, avec un nouveau numéro ou un numéro que le compte détient déjà |
| `GET` | `/v2/api/partner/accounts/{id}/members` | Lister les membres d'un compte |
| `DELETE` | `/v2/api/partner/accounts/{id}/members/{member_id}` | Retirer un membre : ses eSIM sont révoquées, ses numéros restent sur le compte |
| `GET` | `/v2/api/partner/accounts/{account_id}/esims/offer` | Obtenir les frais de mise en service, les paliers et les recharges eSIM d'un compte |
| `POST` | `/v2/api/partner/accounts/{account_id}/esims` | Commander une eSIM pour l'un des numéros du compte, qui vous est facturée |
| `GET` | `/v2/api/partner/esims/{id}` | Obtenir le statut d'une eSIM (`PROVISIONING`, `ACTIVE`, `FAILED`, `REVOKED`), son palier et sa consommation du mois |
| `PUT` | `/v2/api/partner/esims/{id}/tier` | Changer le palier de données d'une eSIM (une montée de palier vous est facturée) |
| `POST` | `/v2/api/partner/esims/{id}/topups` | Acheter une recharge de données pour une eSIM pour le mois en cours, qui vous est facturée |
| `POST` | `/v2/api/partner/esims/{id}/revoke` | Révoquer une eSIM immédiatement : elle cesse de fonctionner, son numéro reste sur le compte |
| `GET` | `/v2/api/partner/esims/{id}/activation_code` | Obtenir le code d'activation et le QR code d'une eSIM prête |
| `POST` | `/v2/api/partner/accounts/{account_id}/sender_ids` | Déclarer un Sender ID sur un compte, validé par Allo |
| `GET` | `/v2/api/partner/accounts/{account_id}/sender_ids` | Lister les Sender ID d'un compte |
| `GET` | `/v2/api/partner/accounts/{account_id}/sender_ids/{id}` | Obtenir le statut d'un Sender ID (`PENDING`, `VALIDATED`, `FAILED`, `DISABLED`) |

Les comptes se tarifent, se créent, se consultent et se désactivent avec les endpoints [Partenaires](https://help.withallo.com/fr/v2/api-reference/partner/overview.md#endpoints).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.