# Ajouter un numéro

> Ajoute un numéro de téléphone à l'un de vos comptes. La réponse renvoie le nouveau numéro et indique s'il a été facturé. Appelez d'abord Obtenir le prix d'un…

`POST /v2/api/partner/accounts/{id}/numbers`

<Note>
**Scope requis :** `PARTNER`
</Note>

Ajoute un numéro de téléphone à l'un de vos comptes. La réponse renvoie le nouveau numéro et indique s'il a été facturé. Appelez d'abord [Obtenir le prix d'un numéro](/fr/docs/white-label/get-number-price) pour connaître le montant.

## Requête

Le corps est une préférence de numéro, identique à `number_preference` sur [Créer un compte](/fr/docs/partner/create-account) :

- `country` est requis (code pays ISO, par exemple `FR`). Un pays inconnu échoue avec `INVALID_NUMBER_PREFERENCE`.
- `prefix` est optionnel : les chiffres par lesquels le numéro doit commencer, par exemple `7` ou `+337`.
- `esim` est optionnel, `false` par défaut. Passez-le à `true` pour obtenir un numéro mobile français qui peut porter une eSIM, à commander ensuite avec [Commander une eSIM](/fr/docs/white-label/order-esim). Avec un `country` autre que `FR`, la requête échoue avec `ESIM_NOT_AVAILABLE_IN_COUNTRY`.

`{id}` est l'identifiant du compte renvoyé par Créer un compte. Un compte que votre API key n'a pas créé, ou déjà désactivé, renvoie `404 PARTNER_ACCOUNT_NOT_FOUND`.

## Facturation

- Le numéro est facturé sur l'abonnement du compte, que vous payez. Allo prélève d'abord votre [crédit prépayé](/fr/docs/partner/get-credit), puis débite le reste sur votre carte enregistrée. Allo ne facture jamais votre client.
- Allo débite tout de suite le reste de la période de facturation en cours du compte, avec la remise de l'abonnement appliquée. Le numéro se renouvelle ensuite avec l'abonnement.
- Si le compte paie déjà un emplacement de numéro qu'aucun numéro n'occupe, le nouveau numéro prend cet emplacement et rien n'est débité. La réponse indique alors `charged: false`.
- Allo vérifie qu'un numéro est disponible avant tout débit. Si aucun ne correspond au pays et au préfixe, la requête échoue avec `409 NO_NUMBER_AVAILABLE` et rien n'est débité. Un pays qui demande d'abord la vérification réglementaire du compte échoue avec `409 REGULATORY_VERIFICATION_REQUIRED`, là aussi avant tout débit.
- Si votre crédit prépayé ne couvre pas le montant et qu'aucune carte n'est enregistrée, la requête échoue avec `402 PARTNER_CREDIT_INSUFFICIENT` et rien n'est créé. Rechargez votre crédit ou ajoutez une carte, puis réessayez avec une nouvelle `Idempotency-Key`.
- Une carte refusée échoue avec `402 PARTNER_BILLING_FAILED`, et rien n'est créé.
- Si le numéro ne peut pas être configuré après le débit, Allo retire le montant de l'abonnement et crédite la période non utilisée sur votre solde.

## Nouvelles tentatives

Envoyez un en-tête `Idempotency-Key` (8 à 100 lettres, chiffres, `-` ou `_`, par exemple un UUID) et réutilisez-le pour réessayer la même requête. Une nouvelle tentative avec la même clé ne vous débite pas deux fois. Une clé dans un autre format échoue avec `INVALID_IDEMPOTENCY_KEY`.

Si vous ne savez pas si une tentative précédente a abouti, vérifiez les `phone_numbers` du compte avec [Obtenir un compte](/fr/docs/partner/get-account) avant de réessayer.

## Erreurs

| Code | Signification |
|------|---------------|
| `PARTNER_ACCOUNT_BUSY` | Un autre numéro ou membre est en cours d'ajout sur ce compte. Toujours `retryable: true` : réessayez dans quelques secondes. |
| `IDEMPOTENCY_KEY_ALREADY_USED` | Une tentative précédente a déjà utilisé cette `Idempotency-Key`. Vérifiez les numéros du compte avec [Obtenir un compte](/fr/docs/partner/get-account) avant de réessayer avec une nouvelle clé. |
| `PARTNER_ACCOUNT_DEACTIVATING` | Le compte est en cours de désactivation à la fin de sa période de facturation : il ne prend plus de numéros. |
| `PARTNER_ACCOUNT_SUBSCRIPTION_CONFLICT` | L'abonnement du compte ne peut pas être facturé pour le moment. Si `retryable` vaut `true`, réessayez dans quelques minutes. Sinon, écrivez à [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co). |
| `PARTNER_SUBSCRIPTION_NOT_BILLABLE` | Le compte n'a pas d'abonnement qu'Allo peut facturer (`402`). |
| `PARTNER_BILLING_UNAVAILABLE` | La facturation est temporairement indisponible (`500`). Réessayez avec la même `Idempotency-Key`, qui reprend le même débit. |
| `PARTNER_NUMBER_SETUP_FAILED` | Le numéro n'a pas pu être configuré (`500`), et le débit a été annulé. Ne réessayez pas : écrivez à [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co). |
| `PARTNER_NUMBER_KEPT` | Le numéro a été attribué mais sa configuration n'a pas abouti (`500`). Il reste sur le compte et sur sa facturation. Ne réessayez pas, une nouvelle tentative ajouterait un autre numéro : écrivez à [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co) en indiquant le numéro. |

## Réponse

- `phone_number` est le nouveau numéro, au format E.164. Il apparaît aussi dans les `phone_numbers` du compte sur [Obtenir un compte](/fr/docs/partner/get-account).
- `country` est le pays tel qu'Allo le nomme : `GB` revient sous la forme `UK`.
- `charged` vaut `true` quand un nouvel emplacement a été facturé, `false` quand le numéro a pris un emplacement déjà payé par le compte.
