Vælg et enkelt præfiks
Brug kaldene til at finde lande og dækningsområder, og kald derefter getprefixes uden gruppering. Kopiér det valgte præfiks' uuid. Hvis returns_numbers er 0, tildeles der et nummer under præfikset ved bestilling; brug den returnerede next_function frem for at kræve en liste over individuelle numre.
Gennemse et afgrænset antal resultater
Ved en normal søgning skal du bruge compact=1 og angive det ønskede antal resultater både i stien og i forespørgselsparameteren quantity, som vist nedenfor. Der er ingen side- eller markørparameter. Et kompakt resultat er en stikprøve; gentagelse af en forespørgsel garanterer ikke en ny side uden overlap. Et tomt resultat eller et resultat med få numre må ikke fortolkes som det samlede antal tilgængelige numre.
Find et ciffermønster, der er let at huske
Angiv number_filter_mode=contains eller ends_with sammen med number_filter_value. Værdien skal indeholde 1–15 cifre. En søgning kan hente afgrænsede portioner af kandidatnumre, før filteret anvendes, og kan derfor overse andre tilgængelige numre, der matcher. Hvis du har brug for en understøttet kilde til at udføre den krævede søgning, skal du få en pid-selektor fra MultiTEL og bruge filter_required=1; et manglende eller ikke-understøttet valg medfører en API-fejl.
Gennemgå det valgte nummer
Læs number, info.uuid, den valgte price[].uuid, navnene på tilgængelige funktioner og registreringskravene fra det samme resultat. Arrayet price kan indeholde flere prisplaner med forskellige kanalantal og takster. Beløbsfelter og antal kan være kodet som strenge. Valgfrie metadata, herunder info.state, varierer mellem kilderne; kræv ikke ét universelt format for delstatsoplysninger, og udled ikke priser af et ID.
Ved behandling uden streaming fjernes dubletter blandt kandidatnumrene, og der foretages en fordeling på tværs af kilderne, før den valgte resultatportion sorteres efter den første prisplans månedspris. Andre behandlingsforløb kan begynde at streame tidligere, så der gælder ingen garanti for samlet sortering eller fjernelse af dubletter for alle forespørgsler. Sorteringen beviser heller ikke, at den returnerede stikprøve indeholder det billigste nummer i hele kataloget.
Bestil separat, og bekræft resultatet
En søgning hverken køber eller reserverer noget. Gem det returnerede nummer og prisplanernes identifikatorer til bestillingsforløbet under samme konto. Gennemgå den faktiske prisplan, kravene og omkostningerne, før du afgiver en bestilling. Registreringskrav kan forsinke aktiveringen; et søgeresultat fastlægger ingen bestemt aktiveringsfrist.
Forespørgsel
Brug en aktiveret MultiTEL API-konto: HTTP Basic-loginoplysninger til en konto med adgangskode eller Authorization: Bearer til en konto med token. Kontoens tilladelser og IP-begrænsninger gælder. Se den fælles vejledning om autentificering.
Stiparametre og URL-forespørgselsparametre. Brug GET til det offentlige søgeforløb. Forespørgselsbehandleren accepterer også udvalgte formular- og forespørgselsværdier, men er ikke en søge-API med JSON i forespørgselskroppen.
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"| Navn | Type | Påkrævet | Beskrivelse |
|---|---|---|---|
prefix_id | string | Ja | Et ID for et enkelt præfiks, returneret i et ugrupperet getprefixes-svar. Kopiér det nøjagtigt; erstat det ikke med et ID for et land, et dækningsområde, et grupperet præfiks eller en prisplan. |
quantity | integer | Nej | Mål for antallet, der hentes; standardværdien er 1. Værdier, der ikke er positive, bliver til 1. quantity i stien alene er ikke en pålidelig grænse for det samlede antal resultater: En søgning, der ikke er bundet til en kilde og ikke har forespørgselsparameteren quantity, kan udvide hentningen og returnere op til 50 poster pr. kilde før anden behandling. Ved almindelig gennemgang af et afgrænset antal resultater skal du bruge compact=1 og gentage det ønskede antal i forespørgslen som i eksemplet. |
| Navn | Type | Påkrævet | Beskrivelse |
|---|---|---|---|
quantity | integer | Nej | Det ønskede endelige antal resultater. Ikke-tomme værdier konverteres til heltal med en minimumsværdi på 1. Ved behandling uden streaming, hvor søgningen ikke er bundet til en kilde, begrænser dette den endelige fordeling. Det tvinger ikke tjenesten til at finde så mange numre. Kompakte søgninger, der er bundet til en kilde, kan returnere kildens kompakte resultatportion frem for at følge denne grænse. |
compact | string | Nej | Brug 1, true eller on for at få et mindre svar uden streaming med op til 10 poster pr. kilde før den endelige fordeling. Resultaterne er en stikprøve af de numre, der aktuelt er hentet, ikke et komplet katalog. |
number_filter_mode | string | Nej | Valgfri tilstand for ciffermønster: contains eller ends_with. Angiv også number_filter_value. Resultaterne kontrolleres mod telefonnumrenes normaliserede cifre; søgningen gennemgår ikke alle tilgængelige numre for at garantere alle mulige match. |
number_filter_value | string | Nej | Mellem 1 og 15 cifre uden mellemrum, + eller tegnsætning. Foranstillede nuller har betydning; send værdien som tekst. |
filter_required | string | Nej | Avanceret: 1, true, yes eller on kræver en understøttet, udtrykkeligt valgt kilde til tilgængelige numre for filtertilstanden. Ellers returnerer API'en status.code 422. Dette er ikke nødvendigt ved almindelig gennemgang af kataloget. |
pid | string | Nej | Avanceret selektor til nummerudbuddet, leveret af MultiTEL. Numeriske former og understøttede hexadecimale former på 32 tegn accepteres; ukendte værdier ignoreres uden besked. Udelad den ved normal brug. Udled ikke selektorer af pris-ID'er, og antag ikke, at en vilkårlig selektor udelukkende begrænser nummerudbuddet til det valgte. |
Svar
Ét JSON-objekt, der indeholder status og response. Ved succes er status.code 200, og response er et array af nummerposter. status.results er antallet af poster i det returnerede array; status.msg kan være Results: N eller OK ved et streamet svar. Uden compact=1 skriver nogle søgninger arrayet response løbende og afslutter med status, så vent på hele JSON-svarkroppen. Dette er ikke JSON opdelt med linjeskift. Kontrollér status.code, selv når HTTP-overførslen lykkes. Typiske felter vises nedenfor; kildespecifikke metadata og valgfrie felter varierer. Behandl hver identifikator som en uigennemsigtig værdi, og gem nummeret sammen med dets valgte price[].uuid.
Illustration af svarstrukturen; hverken aktuelle kontodata eller et aktuelt pristilbud.
{
"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"
}
]
}Fejl
- 401: Autentificeringen mislykkedes. Ugyldige eller manglende loginoplysninger og afvist adgang til API-kontoen giver ingen søgeresultater.
- 404: Invalid prefix ID, Invalid country, Invalid area eller No numbers found. Læs status.msg; et fejlsvar er ikke et array af numre.
- 400: NUMBER_FILTER_INVALID i response.code: ugyldig tilstand, en værdi, der ikke består af 1–15 cifre, eller filter_required uden både tilstand og værdi.
- 422: NUMBER_FILTER_UNSUPPORTED i response.code: enten tildeles der et nummer under præfikset ved bestilling (reason=order_only_prefix, og next_function angiver bestillingsruten), eller den udtrykkeligt valgte kilde kan ikke understøtte det krævede filter.
Tilgængelighed og sideeffekter
- Denne forespørgselsbehandler søger og udarbejder pristilbud; den afgiver ikke en nummerbestilling og debiterer ikke et beløb for nummerkøb. Den kan opdatere katalogcacher, fjerne forældede cachelagrede nummerposter, gemme kontospecifikke prisplaner og skrive søgelogfiler.
- Tilgængeligheden er et øjebliksbillede, ikke en reservation. En efterfølgende bestilling kan mislykkes eller vise en anden tilgængelighed. Afstem bestillingsresultatet, før du forsøger at købe igen.
- Priserne er kontospecifikke. Gem det valgte prisplan-ID til brug med samme konto, og gennemgå bestillingsvilkårene og omkostningerne separat; dette endpoint alene beviser ikke, at en pris forbliver gyldig frem til en senere bestilling.
- Nummeret og priserne i eksemplet er fiktive illustrationer af svarstrukturen, ikke et aktuelt pristilbud. Funktioner, kanalantal, løbetid og registreringsoplysninger skal læses fra det faktisk valgte resultat.
- Nogle registreringsbeskrivelser indeholder formateret tekst eller links. Behandl returnerede strenge som data, der ikke er tillid til, når du viser dem i din egen applikation.
- Tilgængeligheden af mobilnumre og tilhørende flag afhænger af, hvad kontoen er berettiget til, og af nummerudbuddet. Et katalogpræfiks eller et is_mobile-flag alene fastslår ikke et bestemt nummers mobilfunktioner.