Dostęp do konta i projektu
Korzystaj z aktywnego konta API przez HTTPS z dozwolonego adresu IP. Projekt musi należeć do tego konta i nie może być usunięty. Użyj unikalnego identyfikatora projektu z procesu obsługi zleceń przeniesienia, a nie jego liczbowego identyfikatora w bazie danych ani numeru telefonu. Podczas tworzenia żądania zakoduj identyfikator projektu zgodnie z zasadami kodowania adresów URL.
Przygotowanie do dodania numerów
Ta operacja zmienia istniejący projekt przenoszenia numerów. Najpierw potwierdź numery oraz upoważnienie klienta w ramach swojego procesu obsługi zleceń przeniesienia. Zapisz każdy numer jako pełny międzynarodowy ciąg cyfr, samodzielnie usuń duplikaty i sprawdź dotychczasową listę numerów projektu. Nie używaj tego punktu końcowego do testowania dowolnych numerów.
Obecny portal sprawdza poprawność numerów i normalizuje je przed wywołaniem tej ścieżki. Bezpośrednie wywołanie starszego punktu końcowego nie zapewnia takich samych zabezpieczeń: usuwa on spacje z początku i końca danych wejściowych, ale nie sprawdza formatu numeru telefonu, kodu kraju, duplikatów ani etapu obsługi projektu.
Żądanie POST
Utwórz lokalny plik numbers.json o poniższej strukturze. Numery są fikcyjne; zastąp je numerami, dla których uzyskano upoważnienie w ramach wybranego projektu.
{
"numbers": [
"12025550123",
"12025550124"
],
"isocode": "US"
}curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--header "Content-Type: application/json" \
--data-binary @numbers.json \
"https://api.multitel.net/v3/lnp/project/$PROJECT_ID/addnumbers"| Pole | Znaczenie |
|---|---|
| numbers | Wymagana niepusta tablica numerów zapisanych jako ciągi znaków albo ciąg znaków zawierający po jednym numerze w każdym wierszu. Puste wpisy są odrzucane, a spacje na początku i końcu usuwane. Tekst rozdzielony przecinkami nie jest dzielony na osobne numery. |
| isocode | Opcjonalny kod kraju dla dodawanych wpisów. Jeśli go pominięto lub jest pusty, używana jest lokalizacja projektu. Procedura obsługi usuwa spacje z początku i końca podanej wartości, ale nie zamienia liter na wielkie ani nie sprawdza jej poprawności. Samodzielnie podaj prawidłowy kod kraju zapisany wielkimi literami. |
W tym przykładzie użyj POST z application/json. Odczytywane są również dane formularza przesłane metodą POST. Metoda nie definiuje klucza idempotencji ani gwarantowanego bezpiecznego rozmiaru partii dla tego punktu końcowego; uzgadniaj stan dla partii o rozmiarze umożliwiającym kontrolę, zamiast polegać na odgadniętym limicie.
Zgłoszony wynik
Fikcyjny przykład odpowiedzi.
{
"status": {
"code": 200,
"msg": "Success add numbers"
},
"response": {
"uniqueid": "PROJECT_EXAMPLE",
"count": 2,
"numbers": [
{
"id": 21,
"number": "12025550123",
"status": 0,
"status_str": "Pending",
"isocode": "US"
},
{
"id": 22,
"number": "12025550124",
"status": 0,
"status_str": "Pending",
"isocode": "US"
}
]
}
}Odpowiedź oznacza próby dodania wpisów statusem Pending. Przed zgłoszeniem wyniku nie sprawdza rezultatu każdego wstawienia do bazy danych. Sama liczba wpisów lub zwrócony identyfikator nie stanowią zatem dowodu, że każdy wpis został trwale zapisany. Dodany wpis ze statusem Pending nie oznacza akceptacji przez operatora, zaplanowanego przeniesienia ani zakończonej aktywacji.
Uzgodnij stan przed ponowieniem żądania
- Przed dodaniem numerów odczytaj listę numerów projektu i zachowaj informacje o planowanych dodatkach we własnej ewidencji żądań.
- Wyślij żądanie dodania numerów jeden raz.
- Ponownie odczytaj listę numerów projektu i porównaj każdy numer, który miał zostać dodany. Sprawdź duplikaty oraz status każdego numeru.
- Jeśli żądanie przekroczy limit czasu, zwróci błąd lub zgłosi niejednoznaczny wynik, ponownie odczytaj stan przed ponowieniem żądania. Niektóre dodawane wpisy mogą już istnieć.
- Wyjaśnij brakujące lub zduplikowane wpisy w ramach procesu obsługi zleceń przeniesienia albo z pomocą działu wsparcia, zamiast bez sprawdzenia powtarzać całe żądanie.
Procedura obsługi wstawia wpisy pojedynczo, bez transakcji ani ochrony przed duplikatami. Przerwanie może pozostawić wcześniejsze zapisy; nieudane wstawienie zwracające false nadal może zostać uwzględnione w zgłoszonej liczbie wpisów. Powtórzenie żądania może dodać zduplikowane wpisy. Sama procedura obsługi nie zapisuje zdarzenia ani nie kończy przeniesienia numeru przez operatora.
Błędy starszego punktu końcowego
Metoda inna niż POST zwraca kod API 403. Brak projektu, projekt usunięty lub nienależący do konta powodują zwrócenie kodu API 404. Puste dane wejściowe numerów również powodują zwrócenie kodu API 404. Obowiązują wymagania dotyczące uwierzytelniania oraz ograniczenia źródłowych adresów IP. Te starsze kody nie dowodzą, że od rozpoczęcia przetwarzania nie doszło już do wstawienia wpisów.
Rozliczenia i zakres przeniesienia
Sprawdzona procedura obsługi wstawia do projektu wpisy numerów i nie zawiera bezpośredniego obciążenia konta ani przekazania zlecenia operatorowi. Nie oznacza to, że cała usługa przenoszenia numerów jest bezpłatna, ani nie uchyla uzgodnionych opłat za przeniesienie. Zanim zaczniesz oczekiwać przeniesienia, spełnij wymagania projektu dotyczące upoważnień, dokumentów i weryfikacji.