Жалпы мәліметтер
Егер сізге Интернет-дүкеніңізден, 1С, CRM немесе басқа бағдарламалық жасақтама арқылы автоматты SMS-хабарламалар орнату қажет болса немесе Mobizon-ды CRM ретінде пайдалансаңыз - біздің API сізге бұл тапсырмаларды шешуге көмектеседі.
API серверімен байланысу үшін HTTP протоколы қолданылады, SSL қауіпсіз байланыстары мүмкіндігімен. Сұрауларды беру үшін GET және POST әдістері қолданылады. Сервер жауапты XML немесе JSON форматтарының бірінде қайтара алады. API-ге қосылу және сұрауларды орындау туралы толығырақ төменде сипатталған.
API-ге қосылу
API-ге сұраулар орындау үшін, Mobizon Басқару панелінде бұл функцияны қосу және баптау қажет:
- Басқару панелінде API параметрлерін ашыңыз:
- API қолжетімділігін қосу опциясын қосыңыз:
- API сұраулары орындалатын IP мекенжайларын көрсетіңіз.
Қолжетімділікті қосқаннан кейін сіз өзіңіздің API кілтіңізді көресіз. Сұрауларды орындау үшін осы кілтті өзіңіздің қосымшаңызда пайдаланыңыз.
Маңызды есте сақтаңыз! Кілт құпия болып табылады, оны жазуға немесе біреуге қажетсіз беруге болмайды, себебі сіздің кілтіңізді алған адам API арқылы сіздің аккаунтыңызбен кез келген операцияларды орындай алады.Есептік жазбаңыздың қауіпсіздігін қамтамасыз ету үшін API кілтіңізбен қолжетімділікке рұқсат берілетін IP мекенжайларының тізімін көрсету ұсынылады. API қолжетімділік IP мекенжайларының тізімі өрісіне серверлеріңіздің IP мекенжайларын енгізіңіз. Бірнеше мекенжайды үтірлермен бөліп, енгізуге болады, мысалы: 192.12.34.56,23.45.67.89,123.123.123.123.
Назар аударыңыз! Егер өріс бос қалса, API-мен кез келген IP мекенжайынан жұмыс істеуге болады, бірақ бұл қауіпсіз емес.API кілтін жаңарту батырмасын басу арқылы кілтті өзгертуге болады. Бұл жағдайда ескі кілтті пайдаланатын барлық қосымшалар API-ге қолжетімділігін жоғалтады. Қолжетімділікті қалпына келтіру үшін қосымшаңыздың параметрлерінде ескі кілтті жаңа кілтпен ауыстырыңыз.
API-пен жұмыс істеу
API кіру нүктесі
Барлық API сұраулары келесі мекенжай бойынша орындалады: https://api.mobizon.kz/service/
Назар аударыңыз! Сіз сұрауларды HTTP немесе HTTPS арқылы жіберуді таңдай аласыз. Қосымшаңыздың API Mobizon-пен байланысының қауіпсіздігін қамтамасыз ету үшін барлық сұрауларды HTTPS арқылы жіберуді ұсынамыз, бірақ егер сіздің бағдарламалық жасақтамаңыз қауіпсіз HTTP сұраулар жасау мүмкіндігін қолдамаса, онда сізге арналған API мекенжайы келесідей болады: http://api.mobizon.kz/service/.Құжаттамада және мысалдарда HTTPS барлық келесі ескертулерді HTTP ретінде қарастыруға болады.
Міндетті параметрлер
API-ге ең аз сұрау модульдің, әдістің атауын және API кілтін қамтиды:
https://api.mobizon.kz/service/user/getownbalance?apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK- user - API модулі,
- getownbalance — API әдісі,
сұрақ белгісінен кейін қосымша параметрлер көрсетіледі, бұл жағдайда apiKey.
Маңызды атап өту керек, сұрақ белгісінің алдында қиғаш сызық (слэш) болмауы керек, мұндай сұрау қате деп саналады:
https://api.mobizon.kz/service/user/getownbalance/?apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKҚосымша параметрлер
- output — серверден қайтаратын жауап форматы.
Қазіргі уақытта API серверінің екі жауап форматы қолдау көрсетіледі:- json — жауап json жол форматында қайтарылады (әдепкі бойынша)
- xml — жауап xml құжаты түрінде қайтарылады
Сұрау мысалы:
https://api.mobizon.kz/service/user/getownbalance?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
- api — API нұсқасы.
Ағымдағы API нұсқасы v1, бұл мән әдепкі бойынша пайдаланылады.
Сұрау мысалы:
https://api.mobizon.kz/service/user/getownbalance?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK - Басқа параметрлер.
Кез келген басқа параметрлер, соның ішінде әдіс параметрлері, GET немесе POST параметрлері ретінде берілуі мүмкін. GET сұрауының максималды ұзындығын және GET сұрауларына аралық желі түйіндерімен жауаптардың кэштенуін ескеру қажет, сондықтан біз барлық API сұрауларын POST әдісімен орындауды ұсынамыз.
API серверінің жауап форматтары
Сервер жауабы таңдалған деректер форматы түріндегі жол (XML немесе JSON) болып табылады, ол үш элементтен тұратын нысанды қамтиды: code, data және message. JSON форматындағы жауап мысалы:
{
"code":0,
"data":{
"balance":"4043.0656",
"currency":"KZT"
},
"message":""
}XML форматындағы жауап келесідей көрінеді:
<?xml version="1.0" encoding="UTF-8"?>
<root>
<code>0</code>
<data>
<balance>123.4567</balance>
<currency>KZT</currency>
</data>
<message></message>
</root>- code — API жауабының коды, API жауап кодтарын құжаттамадан қараңыз,
- data — API әдісімен орындалған форматтағы қайтарылған деректер, қате коды болған жағдайда қатенің себебін ашатын деректерді қамтуы мүмкін (мысалы, тексеру қатесі жағдайында қате өрістерінің тізімі және олардың сипаттамалары),
- message — қателік болған жағдайда әдетте қателіктің мәнін қысқаша сипаттайтын күй мәтіні.
API жауап кодтары
Қайтарылған нәтиже әрқашан сұрау нәтижесін көрсететін сандық мәні бар code өрісін қамтиды:
- 0 — жауап сәтті.
- 100 — жауап қате емес және операцияның фондық орындауға жіберілгенін білдіреді. Бұл жағдайда деректер өрісі API taskqueue/getstatus сұрауы арқылы фондық операцияның прогресі мен күйін бақылауға болатын фондық операцияның идентификаторын қамтиды.
- Кез келген басқа жауап коды — операцияны орындау кезінде қате. Қате кодтарын осы құжаттамадан қараңыз.
PHP клиент кітапханасы
Сіз MobizonApi ресми клиентін PHP-де пайдалана аласыз GitHub.com сайтынан. Пайдалану мысалдары GitHub.com сайтынан.
Сонымен қатар, осы модульді қосу мүмкіндігі бар Composer арқылы.
PHP клиенттік API модулімен жұмыс істеу мысалдары
Егер сізде пайдалану бойынша өз жұмыс мысалдары болса, оларды біздің сайтта орналастыруға қуаныштымыз. Бізге сілтемені немесе код мысалын support@mobizon.kz мекенжайына жіберіңіз
- Бір SMS хабарламасын жіберу
- Жаппай SMS тарату
- Баланс күйін алу
- Пайдалануға қолжетімді қолтаңбалар (альфа атаулар) тізімін алу
- Іздеу критерийлері бойынша SMS хабарламалар есебін сақтау
- Іздеу критерийлері бойынша SMS кампаниялары туралы жиынтық есепті сақтау
GET сұрауларын пайдалану мысалдары
Егер сіздің қосымшаңыз POST сұрауларды орындау мүмкіндігін қолдамаса, хабарламаларды қосымшаңыздан жіберу үшін келесі үлгідегі GET сұрауды пайдаланыңыз:
https://api.mobizon.kz/service/message/sendsmsmessage?recipient=NNNNNNNNNNN&from=PPPPPPP&text=Message+text+here%21&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK- NNN...NNN - алушының телефон нөмірі халықаралық форматта (+ символынсыз), мысалы, 77051708264.
- PPP...PPP - жіберушінің қолтаңбасы (альфа атауы). Қолтаңбаны көрсетпеуге болады, бұл жағдайда жалпы жүйелік қолтаңба немесе әдепкі бойынша сіздің қолтаңбаңыз пайдаланылады (егер ол бар болса).
- Message+text+here%21 - SMS хабарламаңыздың мәтіні url-encoded string форматында: Message text here!.
- KKK...KKK - Басқару панелінен алуға тиіс API кілтіңіз.
