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 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 :
countryest requis (code pays ISO, par exempleFR). Un pays inconnu échoue avecINVALID_NUMBER_PREFERENCE.prefixest optionnel : les chiffres par lesquels le numéro doit commencer, par exemple7ou+337.esimest optionnel,falsepar défaut. Passez-le àtruepour obtenir un numéro mobile français qui peut porter une eSIM, à commander ensuite avec Commander une eSIM. Avec uncountryautre queFR, la requête échoue avecESIM_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é, 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_AVAILABLEet rien n'est débité. Un pays qui demande d'abord la vérification réglementaire du compte échoue avec409 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_INSUFFICIENTet rien n'est créé. Rechargez votre crédit ou ajoutez une carte, puis réessayez avec une nouvelleIdempotency-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 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 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 à [email protected]. |
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 à [email protected]. |
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 à [email protected] en indiquant le numéro. |
Réponse
phone_numberest le nouveau numéro, au format E.164. Il apparaît aussi dans lesphone_numbersdu compte sur Obtenir un compte.countryest le pays tel qu'Allo le nomme :GBrevient sous la formeUK.chargedvauttruequand un nouvel emplacement a été facturé,falsequand le numéro a pris un emplacement déjà payé par le compte.