Choisir un préfixe individuel
Utilisez les appels de découverte des pays et des zones, puis getprefixes sans regroupement. Copiez l’identifiant uuid du préfixe choisi. Si returns_numbers vaut 0, le préfixe attribue un numéro lors de la commande ; utilisez le lien next_function renvoyé au lieu d’exiger une liste de numéros individuels.
Parcourir un lot limité
Pour une recherche normale, utilisez compact=1 et indiquez la taille de lot souhaitée à la fois dans le chemin et dans le paramètre de requête quantity, comme ci-dessous. Il n’existe aucun paramètre de page ou de curseur. Un résultat compact est un échantillon ; répéter une requête ne garantit pas une page suivante sans recoupement. N’interprétez pas un résultat vide ou réduit comme le nombre total de numéros en stock.
Trouver une suite de chiffres facile à retenir
Fournissez number_filter_mode=contains ou ends_with avec number_filter_value. La valeur doit contenir 1–15 chiffres. La recherche peut récupérer des lots limités de candidats avant d’appliquer le filtre et ainsi manquer d’autres numéros correspondants en stock. Si vous avez besoin qu’une source prise en charge applique la recherche requise, obtenez un sélecteur pid auprès de MultiTEL et utilisez filter_required=1 ; une sélection absente ou non prise en charge entraîne une erreur de l’API.
Examiner le numéro choisi
Lisez number, info.uuid, le price[].uuid choisi, les noms de fonctionnalités disponibles et les exigences d’enregistrement dans le même résultat. Le tableau price peut proposer plusieurs forfaits avec des nombres de canaux et des tarifs différents. Les champs monétaires et les quantités peuvent être encodés sous forme de chaînes. Les métadonnées facultatives, notamment info.state, varient selon la source ; n’exigez pas une structure d’État ou de province universelle et ne déduisez pas les prix d’un identifiant.
Dans le parcours sans diffusion en continu, les candidats sont dédupliqués et répartis entre les sources avant que le lot choisi soit trié selon le prix mensuel du premier forfait. D’autres parcours peuvent commencer la diffusion plus tôt ; aucune garantie globale de tri ou de déduplication ne s’applique donc à toutes les requêtes. Le tri ne prouve pas non plus que l’échantillon renvoyé contient le numéro le moins cher de tout le catalogue.
Commander séparément et confirmer le résultat
Une recherche n’achète ni ne réserve rien. Conservez les identifiants du numéro et du forfait renvoyés pour le parcours de commande sous le même compte. Examinez le forfait réel, les exigences et les frais avant d’envoyer une commande. Les exigences d’enregistrement peuvent retarder l’activation ; un résultat de recherche ne fixe aucun délai d’activation garanti.
Requête
Utilisez un compte API MultiTEL activé : des identifiants HTTP Basic pour un compte à mot de passe, ou Authorization: Bearer pour un compte à jeton. Les autorisations du compte et ses restrictions IP s’appliquent. Consultez les consignes communes d’authentification.
Paramètres de chemin et paramètres de requête de l’URL. Utilisez GET pour le parcours de recherche public. Le traitement accepte aussi certaines valeurs de formulaire ou de requête, mais ce n’est pas une API de recherche avec corps JSON.
curl --fail-with-body --get \
--user "${MULTITEL_API_USERNAME}:${MULTITEL_API_PASSWORD}" \
--data-urlencode "compact=1" \
--data-urlencode "quantity=10" \
"https://api.multitel.net/v3/getnumbers/${PREFIX_ID}/10"| Nom | Type | Obligatoire | Description |
|---|---|---|---|
prefix_id | string | Oui | Identifiant de préfixe individuel renvoyé par une réponse getprefixes non regroupée. Copiez-le exactement ; ne le remplacez pas par un identifiant de pays, de zone, de préfixe regroupé ou de forfait tarifaire. |
quantity | integer | Non | Objectif de récupération, par défaut 1. Les valeurs non positives deviennent 1. Un paramètre quantity dans le chemin ne constitue pas à lui seul une limite globale fiable du nombre de résultats : une recherche sans source imposée et sans paramètre de requête quantity peut élargir la récupération et renvoyer jusqu’à 50 entrées par source avant les autres traitements. Pour une consultation ordinaire de lots limités, utilisez compact=1 et répétez la quantité souhaitée dans la requête, comme dans l’exemple. |
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
quantity | integer | Non | Taille finale de lot demandée. Les valeurs non vides sont converties en entiers, avec un minimum de 1. Dans le parcours sans diffusion en continu et sans source imposée, cela limite la répartition finale. Cela ne force pas le service à trouver autant de numéros. Les recherches compactes liées à une source peuvent renvoyer le lot compact de cette source plutôt que respecter cette limite. |
compact | string | Non | Utilisez 1, true ou on pour une réponse plus petite sans diffusion en continu, avec jusqu’à 10 entrées par source avant la répartition finale. Les résultats sont un échantillon du stock actuellement récupéré, pas un catalogue complet. |
number_filter_mode | string | Non | Mode facultatif de recherche de chiffres : contains ou ends_with. Fournissez aussi number_filter_value. Les résultats sont vérifiés sur les chiffres normalisés des numéros de téléphone ; la recherche ne parcourt pas tout le stock pour garantir toutes les correspondances possibles. |
number_filter_value | string | Non | Entre 1 et 15 chiffres, sans espaces, + ni ponctuation. Les zéros initiaux sont significatifs ; envoyez la valeur sous forme de texte. |
filter_required | string | Non | Avancé : 1, true, yes ou on exige une source de stock prise en charge, explicitement sélectionnée pour le mode de filtrage. Sinon, l’API renvoie status.code 422. Cela n’est pas nécessaire pour une consultation ordinaire du catalogue. |
pid | string | Non | Sélecteur de stock avancé fourni par MultiTEL. Les formes numériques et les formes hexadécimales prises en charge de 32 caractères sont acceptées ; les valeurs non reconnues sont ignorées silencieusement. Omettez-le pour une utilisation normale. Ne déduisez pas les sélecteurs des identifiants de prix et ne supposez pas qu’un sélecteur arbitraire impose une restriction exclusive du stock. |
Réponse
Un objet JSON contenant status et response. En cas de succès, status.code vaut 200 et response est un tableau d’entrées de numéros. status.results est le nombre d’éléments du tableau renvoyé ; status.msg peut valoir Results: N ou OK pour une réponse diffusée en continu. Sans compact=1, certaines recherches écrivent le tableau response progressivement et terminent par status ; attendez donc le corps JSON complet. Il ne s’agit pas de JSON délimité par des sauts de ligne. Vérifiez status.code même lorsque le transport HTTP réussit. Les champs habituels figurent ci-dessous ; les métadonnées propres aux sources et les champs facultatifs varient. Traitez chaque identifiant comme une valeur opaque et conservez ensemble le numéro et le price[].uuid choisi.
Exemple de structure de réponse ; il ne s’agit ni de données de compte en temps réel ni d’un devis actuel.
{
"status": {
"code": 200,
"msg": "Results: 1",
"results": 1
},
"response": [
{
"number": "12125550123",
"info": {
"uuid": "NUMBER_ID_FROM_RESPONSE",
"prefix_uuid": "PREFIX_ID_FROM_RESPONSE",
"area_uuid": "AREA_ID_FROM_RESPONSE",
"country_uuid": "COUNTRY_ID_FROM_RESPONSE",
"country_iso": "US",
"prefix": "+1212",
"name": "Example area",
"state": "US"
},
"price": [
{
"uuid": "PRICE_PLAN_ID_FROM_RESPONSE",
"per_minute": "0.01",
"per_sms": "0",
"per_mms": "0",
"free_minutes": "0",
"setup_price": "1.00",
"monthly_price": "2.00",
"yearly_price": "0",
"channels": "2"
}
],
"contract": {
"term": "1 month",
"renewal": "monthly",
"notice": "none"
},
"restrictions": {
"needs_registration": "0",
"restrictions": ""
},
"features": [
"voice"
],
"overflow": "0"
}
]
}Erreurs
- 401 : échec de l’authentification. Des identifiants invalides ou absents et un accès au compte API refusé ne produisent pas de résultats de recherche.
- 404 : Invalid prefix ID, Invalid country, Invalid area ou No numbers found. Lisez status.msg ; une réponse d’erreur n’est pas un tableau de numéros.
- 400 : NUMBER_FILTER_INVALID dans response.code : mode invalide, valeur autre qu’une suite de 1–15 chiffres, ou filter_required sans fournir à la fois le mode et la valeur.
- 422 : NUMBER_FILTER_UNSUPPORTED dans response.code : soit le préfixe attribue un numéro lors de la commande (reason=order_only_prefix et next_function identifie la route de commande), soit la source explicitement sélectionnée ne prend pas en charge le filtre requis.
Disponibilité et effets de bord
- Ce traitement recherche des numéros et prépare des devis ; il ne soumet pas de commande de numéro et ne débite pas de frais d’achat de numéro. Il peut actualiser les caches du catalogue, supprimer du stock périmé en cache, enregistrer des forfaits tarifaires propres au compte et écrire des journaux de recherche.
- La disponibilité reflète un instant donné ; ce n’est pas une réservation. Une commande ultérieure peut échouer ou indiquer une disponibilité différente. Vérifiez et rapprochez le résultat de la commande avant de réessayer un achat.
- Les prix sont propres au compte. Conservez l’identifiant du forfait choisi pour ce même compte et examinez séparément les conditions de commande et les frais ; ce point de terminaison seul ne prouve pas qu’un prix restera valable jusqu’à une commande ultérieure.
- Le numéro et les prix de l’exemple sont fictifs et illustrent la structure de réponse ; ils ne constituent pas un devis en temps réel. Les capacités, les nombres de canaux, la durée et les informations d’enregistrement doivent être lus dans le résultat réellement choisi.
- Certaines descriptions d’enregistrement contiennent du texte mis en forme ou des liens. Traitez les chaînes renvoyées comme des données non fiables lorsque vous les affichez dans votre application.
- La disponibilité mobile et les indicateurs dépendent de l’éligibilité du compte et du stock. Un préfixe du catalogue ou le seul indicateur is_mobile ne prouve pas les capacités mobiles d’un numéro donné.