Pobieranie katalogów do rejestracji usług wiadomości

Pobierz opcje przed utworzeniem formularza rejestracyjnego

Korzystaj z aktualnego katalogu do rejestracji usług wiadomości, aby wypełniać listy wyboru, zamiast wpisywać wartości rejestru na stałe w kodzie. Dla formularza marki portal pobiera katalogi typów działalności, branż, typów alternatywnych identyfikatorów firm, relacji z marką, krajów, stanów USA i giełd. Dla formularza kampanii pobiera przypadki użycia, prawidłowe podrzędne przypadki użycia oraz partnerów zapewniających łączność. Zachowaj każdą zwróconą wartość maszynową wraz z jej etykietą wyświetlaną użytkownikowi; podczas tworzenia późniejszego żądania użyj wartości, a nie przetłumaczonej etykiety.

Wybierz katalog

Przetwarzaj odpowiedź TCR bezpośrednio

Treść odpowiedzi pochodzi bezpośrednio z API TCR. W przeciwieństwie do wielu starszych punktów końcowych /v3 nie ma dodanej otoczki status/response. Przed interpretacją treści sprawdź status HTTP. Katalog może zawierać etykiety w postaci ciągów znaków lub definicje strukturalne, więc nie zakładaj, że każda wartość ma te same pola. Jeśli żądanie HTTP zakończy się powodzeniem, ale treść nie jest prawidłowym dokumentem JSON o oczekiwanej strukturze, zgłoś niepowodzenie pobierania zamiast po cichu zastępować ją pustą listą.

Oddziel opcje katalogowe od kwalifikacji i ustalania cen

Ogólny katalog przypadków użycia nie wskazuje, do których przypadków użycia kwalifikuje się dana marka. Aktualny portal przed utworzeniem kampanii wykonuje zapytanie o kwalifikację konkretnej marki i sprawdza wybrane wymagania operatorów. Podobnie metadane opłat dostawcy nie stanowią ostatecznej ceny detalicznej dla konta. Osobno sprawdź cenę obowiązującą dla konta i warunki rejestracji. Pobranie katalogu nie zatwierdza marki, kampanii ani numeru do obsługi wiadomości.

Obsłuż niedostępność katalogów

Zachowaj dane wpisane przez klienta w formularzu, jeśli pobieranie się nie powiedzie. Wyświetl błąd, uwzględnij Retry-After po otrzymaniu tego nagłówka i stosuj coraz dłuższe odstępy między ponowieniami. Nie pobieraj wielokrotnie wszystkich katalogów ani nie traktuj błędu limitu częstotliwości żądań lub błędu transportu jako prawidłowego pustego katalogu. To żądanie GET nie wymaga klucza idempotencji i nie jest odtwarzane z magazynu idempotencji operacji zmieniających dane.

Żądanie

Użyj aktywnego konta API przez HTTPS z dozwolonego źródłowego adresu IP. Aktualna trasa obsługuje zasady uwierzytelniania konta, w tym uwierzytelnianie Basic oraz aktywne konta API z uwierzytelnianiem za pomocą tokena okaziciela. Nie używaj danych uwierzytelniających dostawcy.

GET z obsługiwaną nazwą katalogu w ścieżce. Przekaż odpowiednie filtry katalogu w ciągu zapytania. Treść żądania nie jest potrzebna.

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/tcr/v2/enum/usecase?validSubUsecase=true"

Odpowiedź

Ta trasa TCR zwraca treść rejestru bezpośrednio wraz z jego statusem HTTP. Nie używa starszej otoczki status.code/status.msg/response z v3. Struktury katalogów różnią się: niektóre przypisują wartościom obiekty opisowe, a inne przypisują wartościom ciągi znaków. Zachowaj klucze odczytywalne maszynowo podczas późniejszego wysyłania formularza. Skrócony, fikcyjny przykład usecase przedstawia mapę z obiektami jako wartościami, a nie aktualny katalog ani schemat o gwarantowanej kompletności. Sprawdź zarówno status HTTP, jak i oczekiwaną strukturę JSON.

Przykładowa struktura odpowiedzi; nie przedstawia bieżących danych konta ani aktualnej wyceny.

{
  "2FA": {
    "displayName": "Authentication",
    "description": "Example authentication use case"
  }
}

Błędy

• 401: Uwierzytelnianie konta nie powiodło się. Sprawdź dane uwierzytelniające API, stan aktywacji i obowiązujące ograniczenia źródłowych adresów IP.
• 400/404 i inne błędy rejestru: nieprawidłowy lub niedostępny katalog albo filtr. Aktualna trasa zachowuje status HTTP i treść odpowiedzi usługi nadrzędnej; nie istnieje uniwersalna otoczka błędów v3.
• 429: Osiągnięto limit żądań konta lub współdzielony limit żądań dostawcy. Uwzględnij Retry-After i ponawiaj żądanie z coraz dłuższymi odstępami.
• 502: Nie udało się połączyć z rejestrem. Dostępność jest nieznana; nie zwracaj pustej listy opcji jako pomyślnego wyniku.
• 503: Mechanizm ograniczania żądań lub usługa nadrzędna jest niedostępna. Przed ponowieniem sprawdź treść odpowiedzi i nagłówek Retry-After, jeśli występuje.

Dostępność i skutki uboczne

• To żądanie GET pobierające katalog w sprawdzonym przebiegu nie tworzy marki ani kampanii, nie wysyła zgłoszenia rejestracyjnego, nie rezerwuje zasobu ani nie nalicza opłaty rejestracyjnej. Kontaktuje się z dostawcą i zapisuje wpisy audytowe żądania.
• Definicje katalogowe i ewentualne metadane opłat dostawcy nie stanowią detalicznej wyceny dla klienta. Aktualny portal osobno pobiera detaliczne ceny kampanii; starszej funkcji pomocniczej getCampaignPrice i dawnych adnotacji cen w wyliczeniach nie wolno traktować jako wiążącej specyfikacji cen tej trasy.
• Obsługiwany wpis katalogowy nie dowodzi, że konkretna marka kwalifikuje się do danego przypadku użycia. Przed późniejszym żądaniem rejestracyjnym przeprowadź kwalifikację konkretnej marki, dopełnij wymaganych oświadczeń i zgód oraz sprawdź ceny obowiązujące dla konta.