ავთენტიფიკაცია და API პასუხები

გამოიყენეთ API ავთენტიფიკაციის მონაცემები

გაგზავნეთ v3 მოთხოვნები HTTPS-ით მისამართზე https://api.multitel.net. ამ სახელმძღვანელოში ყველა საბოლოო წერტილი ავთენტიფიკაციას მოითხოვს. შეინახეთ ავთენტიფიკაციის მონაცემები თქვენს სერვერზე და არასოდეს განათავსოთ ისინი ბრაუზერის JavaScript-ში, საჯარო გვერდებზე, ეკრანის ანაბეჭდებში ან ვერსიების კონტროლის სისტემაში.

გამოიყენეთ ავთენტიფიკაციის მონაცემების ერთ-ერთი ფორმა:

• HTTP Basic API მომხმარებლის სახელითა და პაროლით, რომელიც კონფიგურირებულია თქვენი MultiTEL ანგარიშისთვის.
• Bearer ტოკენი ერთ Authorization: Bearer YOUR_API_TOKEN სათაურში, ჩართული API ანგარიშისთვის, რომელიც კონფიგურირებულია ტოკენით ავთენტიფიკაციისთვის. ტოკენის მოთხოვნები მიიღება მხოლოდ იმ მისამართებიდან, რომლებიც ნებადართულია ამ API ანგარიშისთვის.

თუ IP ნებადართულთა სია კონფიგურირებულია თქვენი API ანგარიშისთვის, გაგზავნეთ ყველა მოთხოვნა ნებადართული მისამართებიდან.

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

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

ამ მაგალითებში ცვლადები არის ადგილმონაცვლეები ავთენტიფიკაციის მონაცემებისთვის, რომლებსაც თქვენ კონფიდენციალურად ინახავთ თქვენს გარემოში.

ავთენტიფიკაციის შეცდომების დამუშავება

ავთენტიფიკაციის შეცდომები იგზავნება HTTP სტატუსით 401. სხეული იყენებს სტანდარტულ კონვერტს, სადაც status.code დაყენებულია მნიშვნელობაზე 401 და ცარიელი სტრიქონი ველში response.

• ავთენტიფიკაციის მონაცემები არ არის: status.msg არის Username and password are required, და პასუხი მოიცავს Basic ავთენტიფიკაციის გამოწვევას.
• Bearer ტოკენი უარყოფილია: თუ Authorization სათაური იყენებს Bearer სქემას და ტოკენი უცნობია, გამორთულია ან თქვენი მისამართიდან ნებადართული არ არის, status.msg არის Invalid bearer token. სხვა ავთენტიფიკაციის მონაცემების შემოწმება არ ხდება, როდესაც Bearer სათაური არსებობს.
• არასწორი Basic ავთენტიფიკაციის მონაცემები: status.msg იწყება ტექსტით A valid username and password pair are required., და პასუხი მოიცავს Basic ავთენტიფიკაციის გამოწვევას. შეტყობინება შეიძლება შეიცავდეს დამატებით დიაგნოსტიკურ ტექსტს, ამიტომ არ გააანალიზოთ ის.

ნუ გაიმეორებთ ავტომატურად იმავე ავთენტიფიკაციის მონაცემებით. ერთი მისამართიდან მოკლე პერიოდში ბევრმა წარუმატებელმა მცდელობამ შეიძლება გამოიწვიოს შემდგომი მოთხოვნების დაბლოკვა იმ მისამართიდან.

წაიკითხეთ პასუხის სხეული

v3 საბოლოო წერტილების უმეტესობა, მათ შორის getcountries, getstates, getareas და other, აბრუნებს JSON ამ კონვერტში:

{
  "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"
    }
  ]
}

ეს არის საილუსტრაციო ქვეყნების სიის პასუხი და არა მიმდინარე მარაგის ან შესაძლებლობების შესახებ განცხადება.

შეცდომის პასუხი ასე გამოიყურება:

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

თუ პასუხი ვერ იკოდება, სხეულს აქვს status.code 500, status.msg Response encoding error, და ცარიელი ობიექტი ველში response.

ძველი GET /v3/countries საბოლოო წერტილი აბრუნებს {"code": 200, "data": [...]} სანაცვლოდ. შეამოწმეთ თითოეული საბოლოო წერტილის დოკუმენტირებული პასუხი. თუ სხეული არ არის ვალიდური JSON, მაგალითად მოულოდნელი სერვერის შეცდომის შემდეგ, ჩათვალეთ მოთხოვნა წარუმატებლად და სცადეთ მოგვიანებით.

API შედეგის კოდები და HTTP სტატუსი

status.code არის API შედეგის კოდი. ის არ არის HTTP სტატუსი. ავთენტიფიკაციის შეცდომები იგზავნება HTTP 401-ით. წინააღმდეგ შემთხვევაში, აღმოჩენის საბოლოო წერტილები ისეთ შედეგებს, როგორიცაა 404 და 500, მხოლოდ ველში status.code აფიქსირებენ და არ აყენებენ შესაბამის HTTP სტატუსს. ამიტომ შედეგი, რომელიც მიუთითებს, რომ ობიექტი ვერ მოიძებნა ან პარამეტრი აკლია, შეიძლება დაბრუნდეს წარმატებული HTTP სტატუსით. ველის status.code მნიშვნელობა ყოველთვის შეამოწმეთ ველის response გამოყენებამდე.

შედეგის კოდი 500 შეტყობინებით ISO Code parameter is required ნიშნავს, რომ სავალდებულო პარამეტრი აკლია. შეასწორეთ მოთხოვნა და ნუ ჩათვლით მას სერვერის გათიშვად.

მიჰყევით next_function-ს

აღმოჩენის შედეგები მოიცავს ველს next_function. ეს არის ფარდობითი გზა საწყისი დახრილი ხაზის გარეშე, ზოგჯერ მოთხოვნის სტრიქონით, როგორიცაა v3/getareas/US ან v3/getareas/US?state=NY. დაურთეთ წინ https://api.multitel.net/ შემდეგი მოთხოვნის შესაქმნელად და გაიარეთ ავთენტიფიკაცია იმავე გზით. არჩევითი ფილტრები, რომლებიც თქვენ გაგზავნეთ, როგორიცაა pid, არ გადადიან ველში next_function. დაამატეთ ისინი ისევ, თუ გჭირდებათ.

არჩევითი მარაგის სელექტორი (pid)

getcountries, getstates და getareas იღებენ არჩევით pid მოთხოვნის პარამეტრს, რომელიც შედეგებს ერთ მარაგის წყარომდე ავიწროებს. გამოიყენეთ ის მხოლოდ MultiTEL-ის მიერ მოწოდებული მნიშვნელობით, მისი რიცხვითი ფორმით ან 32-სიმბოლოიანი თექვსმეტობითი ფორმით. გამოტოვეთ ის ჩვეულებრივი გამოყენებისთვის. გაგზავნეთ pid მოთხოვნის სტრიქონში. თუ საბოლოო წერტილი ვერ ცნობს ან ვერ იღებს მნიშვნელობას, ის უგულებელყოფს მას შეცდომის გარეშე და მოთხოვნა იქცევა ისე, თითქოს pid გამოტოვებული ყოფილიყო.

განასხვავეთ აღმოჩენა შეკვეთებისგან

ქვეყნის, შტატისა და რეგიონის ძიებები არ ცვლის თქვენს ანგარიშს. სპეციალური ნომრების კატალოგი (other) აახლებს კატალოგის დეტალებს და ინახავს ფასების შეთავაზებებს თქვენი ანგარიშისთვის, მაგრამ არ აკეთებს შეკვეთას. აღმოჩენის არც ერთი მოთხოვნა არ ჯავშნის ნომერს და მარაგი შეიძლება შეიცვალოს მოთხოვნებს შორის. გადახედეთ მოთხოვნებსა და ფასს ნომრისთვის შეკვეთის საბოლოო წერტილის გამოყენებამდე.

შესყიდვების, მინიჭებების, შეტყობინებების, ფაქსის გაგზავნებისა და სხვა მოქმედებებისთვის მიჰყევით იმ საბოლოო წერტილის საკუთარ გამეორების წესებს. თუ მოქმედების მოთხოვნის გაგზავნის შემდეგ ლოდინის დრო ამოიწურა, შეამოწმეთ მისი სტატუსი ან თქვენი ანგარიშის ჩანაწერები მის გამეორებამდე. დაკარგული პასუხი არ ადასტურებს, რომ მოქმედება წარუმატებელი იყო.