uBill ծրագրավորողներ REST API · v1 Աշխատանքային միջավայր
Ամբողջական API փաստաթղթեր
SMS և բիլինգ API-ի ռեսուրսները մեկ տեղում՝ ճշգրիտ վերջնակետեր, Postman-ի ամբողջական նկարագրություններ, վերնագրեր, հարցման մարմիններ, պատասխանների օրինակներ և պատրաստի կոդ։
Պաշտպանված վերջնակետերի հարցումները պետք է պարունակեն ընկերության գաղտնի API բանալին։ Մեծ մասում այն փոխանցվում է հետևյալ վերնագրով՝ key վերնագրում, իսկ որոշ հին GET/XML վերջնակետեր օգտագործում են key հարցման պարամետրը։
Մի բացահայտեք API բանալին
Բանալին պահեք սերվերի միջավայրի փոփոխականում։ Մի տեղադրեք frontend JavaScript-ում, բջջային հավելվածում կամ հանրային Git պահոցում։
Հարցման վերնագրեր
key: YOUR_API_KEY
Content-Type: application/json
02
ԿԱՆՈՆՆԵՐ
Ձևաչափեր և կարգավիճակներ
API-ն հիմնականում վերադարձնում է JSON պատասխաններ։ statusID դաշտը ցույց է տալիս արդյունքը․ հաջող հարցման արժեքն է 0 ։ XML վերջնակետը վերադարձնում է XML պատասխան։
0 SMS-ն ուղարկված է
1 Ստացված
2 Չառաքված
3 Կարգավիճակի սպասում
4 Սխալ
API ՏԵՂԵԿԱՏՈՒ
Բոլոր ռեսուրսներն ու վերջնակետերը
Ստորև տեղեկությունը համաժամացված է հանրային Postman հավաքածուի վերջին տարբերակի հետ։
API ԽՈՒՄԲ
SMS API
11 վերջնակետ
SMS API / Ստեղծել ուղարկողի անուն
Ստեղծել ուղարկողի անուն
API բանալի · Վերնագիր
POSThttps://api.ubill.dev/v1/sms/brandNameCreate
Պատասխանի կարգավիճակ
statusID
Նկարագրություն
0
Ուղարկողի անունը ստեղծված է
10
brandName դաշտը դատարկ է
20
brandName-ը պետք է ունենա 2–11 նիշ
30
brandName-ը պարունակում է չթույլատրված նշաններ
40
brandName-ն արդեն ավելացված է
50
Սպասեք վերջին ավելացված brandName-ի հաստատմանը
60
The description field is required. Specify your website, Facebook/Instagram page or application and how you will use the brandName.
Հարցումների նույնականացման գաղտնի API բանալի։ Դիտեք և կառավարեք ընկերության կարգավորումներում։
brandID
Ապրանքանիշի եզակի նույնացուցիչը համակարգում։
numbers
Ստորակետով բաժանված բջջային համարներ։ Պետք է լինեն միջազգային ձևաչափով առանց 00 կամ +.
text
SMS բովանդակությունը։ Աջակցվում են Unicode-ի բոլոր նիշերը։
Ընտրովի պարամետրեր
Պարամետր
Նկարագրություն
stopList
stopList=false — անջատում է արգելափակման ցանկի ստուգումը․ հաղորդագրությունը կուղարկվի նաև ցանկում եղած համարին։
otp
otp=true — հաղորդագրությունը նշում է որպես OTP (մեկանգամյա գաղտնաբառ / հաստատման կոդ)։ OTP հաղորդագրությունները մշակվում են ամենաբարձր առաջնահերթությամբ։ ⚠️ Պետք է կիրառվի միայն նույնականացման կոդերի համար։
sendTime
SMS-ի պլանավորված առաքման ժամանակը։ Ձևաչափը՝ Y-m-d H:i (օրինակ՝ 2026-02-01 23:30). Նշված ժամանակը պետք է լինի ապագայում։ Չնշվելու դեպքում ուղարկվում է անմիջապես։
callbackUrl
Այս SMS հարցման անհատական callback URL-ը։ Գործում է միայն API հավելվածում ընդհանուր լռելյայն callback URL սահմանված լինելու դեպքում։
Նշումներ
OTP հաղորդագրությունները միայն նույնականացման համար են՝ մուտք, հաստատում, գաղտնաբառի վերականգնում։
Հետևյալի սխալ կիրառումը՝ otp պարամետրի, կարող է բերել առաքման կամ հաշվի սահմանափակումների։
Պատասխանի կարգավիճակ
statusID
Նկարագրություն
0
SMS-ն ուղարկված է
10
brandID-ն չի գտնվել
20
Համարները չեն գտնվել
30
Հաղորդագրության տեքստը դատարկ է
40
SMS մնացորդը բավարար չէ
50
Վավեր համարներ չեն գտնվել
60
sendTime ձևաչափը սխալ է։ Օգտագործեք Y-m-d H:i
90
JSON սխալ
99
Ընդհանուր սխալ
⚠️ GET մեթոդի սահմանափակումներ
API-ն խիստ սահմանափակում չի կիրառում ստացող համարների քանակի վրա։
Փաստացի սահմանափակումները պայմանավորված են URL-ի և HTTP վերնագրերի չափի սահմաններով (Cloudflare, պրոքսիներ, զննարկիչներ)։
Գործնական սահմաններ
✅ Մեկ հարցման մոտ 1500 համարն աշխատում է հուսալի։
⚠️ Մոտ 2000-ից ավելի համարները կարող են առաջացնել Header overflow սխալներ։
Այս սխալներն առաջանում են մինչև հարցումը API-ին հասնելը ՝ HTTP / պրոքսի մակարդակում։
Խորհուրդ
Օգտագործեք GET միայն փոքր և միջին հարցումների համար։
Մեծ ցանկերի համար միշտ օգտագործեք POST.
URL պարամետրեր 5
keyqueryYOUR_API_KEY
brandIDquery1
numbersquery9955XXXXXXXX,9955XXXXXXXX
textquerymessage
stopListqueryfalse
Կոդի օրինակներ
cURL · PHP · JavaScript
cURL
curl --request GET \
--url 'https://api.ubill.dev/v1/sms/send?key=YOUR_API_KEY&brandID=1&numbers=9955XXXXXXXX,9955XXXXXXXX&text=message&stopList=false'
Բջջային համարների զանգված։ Պետք է լինեն միջազգային ձևաչափով առանց 00 կամ + ։ Օրինակ՝ ["9955XXXXXXXX","9955XXXXXXXX"]
text
SMS բովանդակությունը։ Աջակցվում են Unicode-ի բոլոր նիշերը։
Ընտրովի պարամետրեր (JSON մարմին)
Պարամետր
Նկարագրություն
stopList
false — անջատում է արգելափակման ցանկի ստուգումը․ հաղորդագրությունը կուղարկվի նաև ցանկում եղած համարին։
otp
true — հաղորդագրությունը նշում է որպես OTP (մեկանգամյա գաղտնաբառ / հաստատման կոդ)։ OTP հաղորդագրությունները մշակվում են ամենաբարձր առաջնահերթությամբ։ ⚠️ Պետք է կիրառվի միայն նույնականացման կոդերի համար։
sendTime
SMS-ի պլանավորված առաքման ժամանակ։ Ձևաչափը՝ Y-m-d H:i (օրինակ՝ "2026-02-01 23:30" )։ Պետք է լինի ապագայում։ Չնշվելու դեպքում ուղարկվում է անմիջապես։
callbackUrl
Այս SMS հարցման անհատական callback URL-ը։ Գործում է միայն API հավելվածում ընդհանուր լռելյայն callback URL սահմանված լինելու դեպքում։
Նշումներ
OTP հաղորդագրությունները միայն նույնականացման համար են՝ մուտք, հաստատում, գաղտնաբառի վերականգնում։
Հետևյալի սխալ կիրառումը՝ otp պարամետրի, կարող է բերել առաքման կամ հաշվի սահմանափակումների։
Պատասխանի կարգավիճակ
statusID
Նկարագրություն
0
SMS-ն ուղարկված է
10
brandID-ն չի գտնվել
20
Համարները չեն գտնվել
30
Հաղորդագրության տեքստը դատարկ է
40
SMS մնացորդը բավարար չէ
50
Վավեր համարներ չեն գտնվել
60
sendTime ձևաչափը սխալ է։ Օգտագործեք Y-m-d H:i
90
JSON սխալ
99
Ընդհանուր սխալ
⚠️ Սահմաններ և նշումներ
Հարցման մարմնի առավելագույն չափ՝ 100 MB → Ավելի մեծ հարցումները մերժվում են։
Cloudflare պրոքսիի սպասման սահման՝ 100 վայրկյան → Ավելի երկար հարցումները վերադարձնում են 524 Timeout։
Մեծ SMS խմբաքանակների հարցումները բաժանեք՝ սպասման և հիշողության խնդիրներից խուսափելու համար։
Օգտագործեք stopList ՝ արգելափակված համարներին չուղարկելու համար։
Փորձարկման գործնական դիտարկում՝
Մեր փորձարկումներում SMS-ները հաջողությամբ ուղարկվել են մինչև 500 000 համարի՝ մեկ հարցմամբ ։ Ավելի մեծ քանակը կարող է առաջացնել հիշողության, սպասման կամ հարցման չափի խնդիրներ։ Փաստացի սահմանները կախված են տեքստի երկարությունից, կոդավորումից և սերվերի բեռնվածությունից։
Խորհուրդ՝
Անվտանգ և հուսալի աշխատանքի համար խորհուրդ է տրվում սահմանափակվել մոտ 100 000 համարով յուրաքանչյուր խմբաքանակում .
Հարցման վերնագրեր 2
Բանալի
Արժեք
Աղբյուր
key
YOUR_API_KEY
Նույնականացում
Content-Type
application/json
Վերնագիր
Հարցման մարմին JSON
Հարցման մարմին
{
"brandID": 1,
"numbers": [
9955XXXXXXXX,
9955XXXXXXXX
],
"text": "Message",
"stopList": false, // Enable/disable checking numbers in the stop list
"sendTime": "2026-02-01 23:01" // sendTime (optional)
}
Բջջային համարների զանգված։ Պետք է լինեն միջազգային ձևաչափով առանց 00 կամ + ։ Օրինակ՝ ["9955XXXXXXXX","9955XXXXXXXX"]
text
SMS բովանդակությունը։ Աջակցվում են Unicode-ի բոլոր նիշերը։
Ընտրովի պարամետրեր (JSON մարմին)
Պարամետր
Նկարագրություն
stopList
false — անջատում է արգելափակման ցանկի ստուգումը․ հաղորդագրությունը կուղարկվի նաև ցանկում եղած համարին։
otp
true — հաղորդագրությունը նշում է որպես OTP (մեկանգամյա գաղտնաբառ / հաստատման կոդ)։ OTP հաղորդագրությունները մշակվում են ամենաբարձր առաջնահերթությամբ։ ⚠️ Պետք է կիրառվի միայն նույնականացման կոդերի համար։
sendTime
SMS-ի պլանավորված առաքման ժամանակ։ Ձևաչափը՝ Y-m-d H:i (օրինակ՝ "2026-02-01 23:30" )։ Պետք է լինի ապագայում։ Չնշվելու դեպքում ուղարկվում է անմիջապես։
callbackUrl
Այս SMS հարցման անհատական callback URL-ը։ Գործում է միայն API հավելվածում ընդհանուր լռելյայն callback URL սահմանված լինելու դեպքում։
Նշումներ
OTP հաղորդագրությունները միայն նույնականացման համար են՝ մուտք, հաստատում, գաղտնաբառի վերականգնում։
Հետևյալի սխալ կիրառումը՝ otp պարամետրի, կարող է բերել առաքման կամ հաշվի սահմանափակումների։
Պատասխանի կարգավիճակ
statusID
Նկարագրություն
0
SMS-ն ուղարկված է
10
brandID-ն չի գտնվել
20
Համարները չեն գտնվել
30
Հաղորդագրության տեքստը դատարկ է
40
SMS մնացորդը բավարար չէ
50
Վավեր համարներ չեն գտնվել
60
sendTime ձևաչափը սխալ է։ Օգտագործեք Y-m-d H:i
90
JSON սխալ
99
Ընդհանուր սխալ
⚠️ Սահմաններ և նշումներ
Հարցման մարմնի առավելագույն չափ՝ 100 MB → Ավելի մեծ հարցումները մերժվում են։
Cloudflare պրոքսիի սպասման սահման՝ 100 վայրկյան → Ավելի երկար հարցումները վերադարձնում են 524 Timeout։
Մեծ SMS խմբաքանակների հարցումները բաժանեք՝ սպասման և հիշողության խնդիրներից խուսափելու համար։
Օգտագործեք stopList ՝ արգելափակված համարներին չուղարկելու համար։
Փորձարկման գործնական դիտարկում՝
SMS՝ մեկ ստացողին
Հարցման առավելագույն համարների քանակ
1
400,000
2
200,000
3
150,000
4
120,000
5
100,000
6
50,000
Փաստացի սահմանները կախված են տեքստի երկարությունից, կոդավորումից և սերվերի բեռնվածությունից։
Խորհուրդ՝
Հուսալի աշխատանքի համար պահպանեք վերևի համարների սահմանը՝ ըստ միավորված SMS-ների քանակի։
API հավելվածի կարգավորումներում կա մեկ ընդհանուր HTTPS հետադարձ կանչի URL ։ Առաքման հաշվետվությունները, SMS բրենդի ակտիվացման ծանուցումներն ու ապագա API իրադարձություններն ուղարկվում են նույն հասցեին՝ GET հարցմամբ .
Օգտագործեք event պարամետրը՝ ծանուցման տեսակը որոշելու համար։ Հաջող մշակումից հետո վերադարձեք ցանկացած 2xx HTTP կարգավիճակ։
Ընդհանուր պարամետրեր
Պարամետր
Նկարագրություն
key
API հավելվածի կարգավորումների callback ստուգման բանալի
Ստեղծում է նոր հաճախորդ՝ հեռախոսահամարների հետ։ Հաճախորդի համարը ( id պատասխանում, cID ներքին համակարգում) ստեղծվում է ավտոմատ և եզակի է ընկերության ներսում։
Պահանջվող թույլտվություն՝ customers.create ։ Հարցման մարմինը պետք է լինի JSON, իսկ Content-Type: application/json վերնագիրը պարտադիր է։
Հարցման մարմին
Դաշտ
Տեսակ
Պարտադիր
Նկարագրություն
typeID
ամբողջ թիվ
այո
Հաճախորդի իրավական տեսակը պետք է լինի uBill-ի տեսակների ցանկում ( 1 = ֆիզիկական անձ)։
name
տող, առավելագույնը 50
ոչ
Հաճախորդի անունը։
personalNo
տող, առավելագույնը 11
ոչ
Անձնական համար կամ ընկերության կոդ՝ միայն տառեր և թվեր։
email
տող
ոչ
Ուղարկելիս պետք է լինի վավեր էլփոստի հասցե։
birthDate
տող
ոչ
Ամսաթիվ՝ YYYY-MM-DD ձևաչափով։
lang
տող
ոչ
Հետևյալներից մեկը՝ ka, en, ru ։ Լռելյայն՝ ընկերության հաճախորդի լեզվի կարգավորումը։
address
տող, առավելագույնը 50
ոչ
Հաճախորդի հասցեն։
column1, column2
տող, առավելագույնը 50
ոչ
Ազատ լրացուցիչ դաշտեր։
numbers
զանգված
այո
Հաճախորդի հեռախոսահամարները․ առնվազն մեկը պարտադիր է։
numbers[] օբյեկտ
Դաշտ
Տեսակ
Նկարագրություն
number
տող
Տեղական համար՝ առանց երկրի կոդի, 6–15 թվանշան։
mobile
տող
Լրիվ միջազգային համար։ Այս բանալին օգտագործելիս երկրի կոդը հեռացվում է համարի սկզբից։
countryCode
տող
Երկրի կոդը, լռելյայն՝ +995.
isPrimary
0 կամ 1
Նշում է հիմնական համարը։ Եթե նշված չէ, ցանկի առաջին համարն է դառնում հիմնական։
smsEnabled
0 կամ 1
Համարը SMS ծանուցումներ ստանո՞ւմ է, լռելյայն՝ 1.
note
տող, առավելագույնը 100
Համարի ազատ նշում։
Մեկ համար կարելի է ուղարկել նաև կարճ ձևով՝ {"mobile": "9955XXXXXXXX", "countryCode": "+995"} հետևյալի փոխարեն՝ numbers զանգվածի։ Կրկնվողները հեռացվում են առանց ծանուցման, իսկ նույն ընկերության այլ հաճախորդի համարը մերժվում է։
Պատասխաններ
HTTP
statusID
Նկարագրություն
201
0
Հաճախորդը ստեղծված է, data պարունակում է նոր հաճախորդին։
400
400
Ստուգումը ձախողվել է, errors օբյեկտը նշում է բոլոր անվավեր դաշտերը։
{
"statusID": 400,
"message": "Validation failed",
"data": null,
"errors": {
"typeID": "typeID does not exist",
"birthDate": "birthDate must be a valid date in YYYY-MM-DD format",
"email": "Email is invalid",
"numbers": "Phone number is invalid"
}
}
Համարն արդեն օգտագործվում է 400
Պատասխան · JSON
{
"statusID": 400,
"message": "Validation failed",
"data": null,
"errors": {
"numbers": "+9955XXXXXXXX is already assigned to another customer"
}
}
Բիլինգ API / Հաճախորդներ / Ստանալ հաճախորդին
Ստանալ հաճախորդին
API բանալի · Վերնագիր
GEThttps://api.ubill.dev/v1/customers/100001
Այս վերջնակետը Postman հավաքածուում առանձին նկարագրություն չունի։
Գոյություն ունեցող հաճախորդի համար ստեղծում է նոր հաշիվ (ծառայություն)։ Հաշվի համարը ( id պատասխանում) գեներացվում է ընկերության cID կարգավորումներից՝ ինչպես uBill վեբ միջերեսում։
Պահանջվող թույլտվություն՝ accounts.create ։ Հարցման մարմինը պետք է լինի JSON, իսկ Content-Type: application/json վերնագիրը պարտադիր է։
Հարցման մարմին
Դաշտ
Տեսակ
Պարտադիր
Նկարագրություն
customerID
ամբողջ թիվ
այո
Հաշվի տիրոջ՝ հաճախորդի համարը, նույն id արժեքը, որը վերադարձնում են հաճախորդի վերջնակետերը։
name
տող, առավելագույնը 50
ոչ
Հաշվի անունը։
birthDate
տող
ոչ
Ամսաթիվ՝ YYYY-MM-DD ձևաչափով։
areaID
ամբողջ թիվ
ոչ
uBill շրջանների ցանկի բնակավայրի նույնացուցիչը։
address
տող, առավելագույնը 50
ոչ
Ծառայության հասցեն։
geoLocation
տող, առավելագույնը 100
ոչ
Կոորդինատները՝ 41.732438,44.7688134 ձևաչափով։
column1, column2
տող, առավելագույնը 50
ոչ
Ազատ լրացուցիչ դաշտեր։
tariffID
ամբողջ թիվ
ոչ
Ընկերության սակագնի համարը։
groupID
ամբողջ թիվ
ոչ
Ընկերության խմբի կամ մասնաճյուղի համարը։
tagsID
ամբողջ թվերի զանգված
ոչ
Հաշվին կցված ընկերության պիտակների համարները։
numbers
զանգված
ոչ
Հաշվի հեռախոսները նկարագրվում են հաճախորդի նույն ձևով։ Ի տարբերություն հաճախորդի՝ հաշիվը կարելի է ստեղծել առանց համարի։
Մոդուլից կախված դաշտեր
Այս դաշտերը կարդացվում են միայն համապատասխան մոդուլի ակտիվացման դեպքում։
Դաշտ
Մոդուլ
Պարտադիր
Նկարագրություն
mac
Ցանց
այո
Սարքի MAC հասցեն՝ եզակի ընկերության ներսում։
onuMac
Ցանց
ոչ
ONU MAC հասցեն՝ եզակի ընկերության ներսում։
ipRangeID
Ցանց
այո
NAS IP միջակայքի համարը։ Առաջին ազատ հասցեն ավտոմատ տրվում է հաշվին և վերադարձվում որպես ip.
stbMac
IPTV
ոչ
STB MAC հասցեն՝ եզակի ընկերության ներսում։
gpsProviderID
GPS track
այո
Ընկերության GPS մատակարարի համարը։
gpsTrackIdentifier
GPS track
ոչ
Սարքի նույնացուցիչը՝ եզակի ընկերության ներսում։
SMS ծանուցում
Եթե ընկերության կարգավորումներում միացված է հաշվի ավելացման SMS-ը, այն ուղարկվում է նոր հաշվի բոլոր SMS ակտիվ համարներին՝ գանձվելով ընկերության մնացորդից։ Անբավարար մնացորդի դեպքում հաշիվը միևնույն է ստեղծվում է, իսկ պատասխանում կա լրացուցիչ warning դաշտ։
Պատասխաններ
HTTP
statusID
Նկարագրություն
201
0
Հաշիվը ստեղծված է, data պարունակում է նոր հաշիվը։
400
400
Ստուգումը ձախողվել է, errors օբյեկտը նշում է սխալ դաշտերը։ Կրկնվող MAC-ներն ու հեռախոսները հաղորդվում են նույն կերպ։
{
"statusID": 0,
"message": "Account created",
"data": {
"id": 100002,
"customerID": 100001,
"name": "მეორე ბინა",
"mobile": "9955XXXXXXXX",
"numbers": [
{
"mobile": "9955XXXXXXXX",
"countryCode": "+995",
"number": "5XXXXXXXX",
"isPrimary": 1,
"smsEnabled": 1,
"note": null
}
],
"personalNo": "XXXXXXXXXXX",
"birthDate": null,
"areaID": null,
"area": "არ არის მითითებული",
"address": "",
"geoLocation": null,
"column1": "",
"column2": "",
"groupID": null,
"tagsID": [],
"tariffID": null,
"balance": "0.00",
"statusID": 1,
"createdAt": "2026-08-26 13:20:11"
},
"warning": "account was created, but the notification sms was not sent - not enough messages on the balance"
}
Ստուգումը ձախողվել է 400
Պատասխան · JSON
{
"statusID": 400,
"message": "Validation failed",
"data": null,
"errors": {
"customerID": "Customer not found",
"geoLocation": "geoLocation must look like 41.732438,44.7688134",
"tariffID": "tariffID does not exist",
"mac": "mac is required",
"ipRangeID": "ipRangeID is required"
}
}
MAC-ն արդեն օգտագործվում է 400
Պատասխան · JSON
{
"statusID": 400,
"message": "Account creation failed",
"data": null,
"errors": {
"account": [
"ეს MAC მისამართი უკვე მითითებულია სხვა ანგარიშზე"
]
}
}
Բիլինգ API / Հաշիվներ / Ստանալ հաշիվը
Ստանալ հաշիվը
API բանալի · Վերնագիր
GEThttps://api.ubill.dev/v1/accounts/100001
Այս վերջնակետը Postman հավաքածուում առանձին նկարագրություն չունի։