Kimlik doğrulama ve API yanıtları

API kimlik bilgilerini kullanın

v3 isteklerini HTTPS üzerinden şuraya gönderin: https://api.multitel.net. Bu kılavuzdaki her uç nokta kimlik doğrulama gerektirir. Kimlik bilgilerini kendi sunucunuzda tutun ve bunları asla tarayıcı JavaScript koduna, herkese açık sayfalara, ekran görüntülerine veya kaynak denetimine koymayın.

Bu kimlik bilgisi biçimlerinden birini kullanın:

• HTTP Basic API kullanıcı adı ve parolası ile; bu bilgiler MultiTEL hesabınız için yapılandırılmıştır.
• Bearer jetonu bir Authorization: Bearer YOUR_API_TOKEN başlığında; bu, jeton kimlik doğrulaması için yapılandırılmış, etkin bir API hesabı içindir. Jeton istekleri yalnızca ilgili API hesabı için izin verilen adreslerden kabul edilir.

Eğer bir IP izin listesi API hesabınız için yapılandırılmışsa, tüm istekleri izin verilen adreslerden gönderin.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getcountries'

curl --header "Authorization: Bearer $API_TOKEN" 'https://api.multitel.net/v3/getcountries'

Bu örneklerdeki değişkenler, ortamınızda özel olarak sakladığınız kimlik bilgileri için yer tutuculardır.

Kimlik doğrulama hatalarını işleme

Kimlik doğrulama hataları HTTP 401 durumuyla gönderilir. Gövde standart zarfı kullanır; bu zarfta status.code değeri 401 ve boş dize şu alan olarak yer alır: response.

• Kimlik bilgisi yok: status.msg şudur: Username and password are required, ve yanıt bir Basic kimlik doğrulama sınaması içerir.
• Bearer jetonu reddedildi: eğer Authorization başlığı Bearer şemasını kullanıyorsa ve jeton bilinmiyorsa, devre dışıysa veya adresinizden izin verilmiyorsa, status.msg şudur: Invalid bearer token. Başka hiçbir kimlik bilgisi denenmez, bir Bearer başlığı mevcut olduğunda.
• Geçersiz Basic kimlik bilgileri: status.msg şununla başlar: A valid username and password pair are required., ve yanıt bir Basic kimlik doğrulama sınaması içerir. İleti daha fazla tanı metni içerebilir, bu nedenle onu ayrıştırmayın.

Aynı kimlik bilgileriyle otomatik olarak yeniden denemeyin. Kısa süre içinde bir adresten gelen çok sayıda başarısız girişim, o adresten gelen diğer isteklerin engellenmesine neden olabilir.

Yanıt gövdesini okuma

Çoğu v3 uç noktası (örneğin getcountries, getstates, getareas ve other) bu zarfta JSON döndürür:

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "countrycode": "1",
      "name": "United States",
      "description": "United States",
      "isocode": "US",
      "is_mobile": 0,
      "sms_coverage": 1,
      "latitude": "38.0000",
      "longitude": "-97.0000",
      "next_function": "v3/getareas/US"
    }
  ]
}

Bu, açıklayıcı bir ülke listesi yanıtıdır; güncel envantere veya yeteneklere ilişkin bir açıklama değildir.

Bir hata yanıtı şuna benzer:

{
  "status": {
    "code": 404,
    "msg": "No areas found"
  },
  "response": ""
}

Bir yanıt kodlanamazsa, gövde şunları içerir: status.code 500, status.msg Response encoding error, ve boş nesne şu alan olarak bulunur: response.

Eski GET /v3/countries uç noktası bunun yerine şunu döndürür: {"code": 200, "data": [...]}. Her uç noktanın belgelenmiş yanıtını denetleyin. Bir gövde geçerli JSON değilse, örneğin beklenmeyen bir sunucu hatasından sonra, isteği başarısız sayın ve daha sonra yeniden deneyin.

API sonuç kodları ve HTTP durumu

status.code API sonuç kodudur. HTTP durumu değildir. Kimlik doğrulama hataları HTTP 401 ile gönderilir. Aksi takdirde keşif uç noktaları şu tür sonuçları bildirir: 404 ve 500 yalnızca status.code alanında bildirilir ve eşleşen bir HTTP durumu ayarlanmaz. Bu nedenle bulunamadı veya eksik parametre sonucu başarılı bir HTTP durumuyla gelebilir. status.code alanını denetlemeden response alanını kullanmayın.

Sonuç kodu 500 şu iletiyle birlikte: ISO Code parameter is required gerekli bir parametrenin eksik olduğu anlamına gelir. Bunu sunucu kesintisi olarak değerlendirmeyin, isteği düzeltin.

next_function alanını izleyin

Keşif sonuçları şunu içerir: next_function. Bu, başında eğik çizgi olmayan göreli bir yoldur; bazen sorgu dizesi içerir, örneğin v3/getareas/US veya v3/getareas/US?state=NY. Önüne şunu ekleyin: https://api.multitel.net/ Bu, sonraki isteği oluşturmak içindir; bu isteğin kimliğini aynı şekilde doğrulayın. Gönderdiğiniz isteğe bağlı filtreler, örneğin pid, şuna aktarılmaz: next_function. Gerekiyorsa bunları yeniden ekleyin.

İsteğe bağlı envanter seçici (pid)

getcountries, getstates ve getareas şu isteğe bağlı sorgu parametresini kabul eder: pid. Bu parametre, sonuçları tek bir envanter kaynağına daraltır. Bunu yalnızca MultiTEL tarafından sağlanan bir değerle, sayısal biçimde veya 32 karakterlik onaltılık biçimde kullanın. Normal kullanım için bunu atlayın. Şunu gönderin: pid sorgu dizesinde. Uç nokta değeri tanımaz veya kabul etmezse, onu hatasız yok sayar ve istek sanki pid atlanmış gibi davranır.

Keşfi siparişlerden ayırma

Ülke, eyalet ve alan aramaları hesabınızı değiştirmez. Özel numara kataloğu (other) katalog ayrıntılarını yeniler ve hesabınız için fiyat tekliflerini kaydeder, ancak sipariş oluşturmaz. Hiçbir keşif isteği numara ayırtmaz ve envanter istekler arasında değişebilir. Bir sipariş uç noktasını kullanmadan önce bir numaranın gerekliliklerini ve fiyatını inceleyin.

Satın alımlar, atamalar, iletiler, faks gönderimleri ve diğer işlemler için ilgili uç noktanın kendi yeniden deneme kurallarını izleyin. Bir işlem gönderimden sonra zaman aşımına uğrarsa, onu yinelemeden önce durumunu veya hesap kayıtlarınızı denetleyin. Kaybolan bir yanıt, işlemin başarısız olduğunu kanıtlamaz.