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
14 վերջնակետ
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.
OTP recipient limits and partial batches
In automatic protection mode, OTP cooldown and per-number limits reject only the affected recipient rows. Other recipients continue; the application is not paused by these two rules. Overall volume and unique OTP recipient limits remain application-wide. The owner can disable additional OTP protection per application.
A mixed batch returns statusID=0, a valid smsID, message=SMS partially sent, acceptedCount, rejectedCount և rejectedNumbers. Each rejection contains the original zero-based request index, normalized number, statusID=47, reason (otpCooldown կամ otpNumberLimit) and retryAfter seconds. If both rules apply, the later-release reason is returned. Only accepted rows are queued, charged and counted against limits. Retry only rejected indexes; resending the full batch can duplicate accepted SMS.
If all recipients are rejected, statusID=47, smsID=null և acceptedCount=0. The HTTP Retry-After header gives the earliest recipient retry time. Rejected retries do not extend it. A separate whole-request failure queues nothing. XML uses <rejectedNumbers><recipient>...</recipient></rejectedNumbers> with the same fields. Responses without filtering keep their existing shape.
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 համարով յուրաքանչյուր խմբաքանակում .
OTP recipient limits and partial batches
In automatic protection mode, OTP cooldown and per-number limits reject only the affected recipient rows. Other recipients continue; the application is not paused by these two rules. Overall volume and unique OTP recipient limits remain application-wide. The owner can disable additional OTP protection per application.
A mixed batch returns statusID=0, a valid smsID, message=SMS partially sent, acceptedCount, rejectedCount և rejectedNumbers. Each rejection contains the original zero-based request index, normalized number, statusID=47, reason (otpCooldown կամ otpNumberLimit) and retryAfter seconds. If both rules apply, the later-release reason is returned. Only accepted rows are queued, charged and counted against limits. Retry only rejected indexes; resending the full batch can duplicate accepted SMS.
If all recipients are rejected, statusID=47, smsID=null և acceptedCount=0. The HTTP Retry-After header gives the earliest recipient retry time. Rejected retries do not extend it. A separate whole-request failure queues nothing. XML uses <rejectedNumbers><recipient>...</recipient></rejectedNumbers> with the same fields. Responses without filtering keep their existing shape.
Հարցման վերնագրեր 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-ների քանակի։
OTP recipient limits and partial batches
In automatic protection mode, OTP cooldown and per-number limits reject only the affected recipient rows. Other recipients continue; the application is not paused by these two rules. Overall volume and unique OTP recipient limits remain application-wide. The owner can disable additional OTP protection per application.
A mixed batch returns statusID=0, a valid smsID, message=SMS partially sent, acceptedCount, rejectedCount և rejectedNumbers. Each rejection contains the original zero-based request index, normalized number, statusID=47, reason (otpCooldown կամ otpNumberLimit) and retryAfter seconds. If both rules apply, the later-release reason is returned. Only accepted rows are queued, charged and counted against limits. Retry only rejected indexes; resending the full batch can duplicate accepted SMS.
If all recipients are rejected, statusID=47, smsID=null և acceptedCount=0. The HTTP Retry-After header gives the earliest recipient retry time. Rejected retries do not extend it. A separate whole-request failure queues nothing. XML uses <rejectedNumbers><recipient>...</recipient></rejectedNumbers> with the same fields. Responses without filtering keep their existing shape.
Հարցման մարմնի առավելագույն չափ՝ 100 MB → Ավելի մեծ հարցումները մերժվում են։
Cloudflare պրոքսիի սպասման սահման՝ 100 վայրկյան → Ավելի երկար հարցումները վերադարձնում են 524 Timeout.
Մեծ SMS հարցումները բաժանեք փոքր մասերի՝ սպասման և հիշողության խնդիրներից խուսափելու համար։
Օգտագործեք stopList ՝ արգելափակված համարներին չուղարկելու համար։
OTP recipient limits and partial batches
In automatic protection mode, OTP cooldown and per-number limits reject only the affected recipient rows. Other recipients continue; the application is not paused by these two rules. Overall volume and unique OTP recipient limits remain application-wide. The owner can disable additional OTP protection per application.
A mixed batch returns statusID=0, a valid smsID, message=SMS partially sent, acceptedCount, rejectedCount և rejectedNumbers. Each rejection contains the original zero-based request index, normalized number, statusID=47, reason (otpCooldown կամ otpNumberLimit) and retryAfter seconds. If both rules apply, the later-release reason is returned. Only accepted rows are queued, charged and counted against limits. Retry only rejected indexes; resending the full batch can duplicate accepted SMS.
If all recipients are rejected, statusID=47, smsID=null և acceptedCount=0. The HTTP Retry-After header gives the earliest recipient retry time. Rejected retries do not extend it. A separate whole-request failure queues nothing. XML uses <rejectedNumbers><recipient>...</recipient></rejectedNumbers> with the same fields. Responses without filtering keep their existing shape.
URL պարամետրեր 1
keyqueryYOUR_API_KEY
Հարցման մարմին XML
Հարցման մարմին
<?xml version="1.0" encoding="UTF-8"?>
<request>
<brandID>1</brandID>
<numbers>9955XXXXXXXX</numbers>
<text>test</text>
<stopList>false</stopList> <!-- Enable/disable checking numbers in the stop list -->
</request>
Կոդի օրինակներ
cURL · PHP · JavaScript
cURL
curl --request POST \
--url 'https://api.ubill.dev/v1/sms/sendXml?key=YOUR_API_KEY' \
--data '<?xml version="1.0" encoding="UTF-8"?>
<request>
<brandID>1</brandID>
<numbers>9955XXXXXXXX</numbers>
<text>test</text>
<stopList>false</stopList> <!-- Enable/disable checking numbers in the stop list -->
</request>'
Required application permission: sms.inbound. Enable Incoming SMS access in the company's API application settings and pass that application's API key in the key header. Only messages assigned to the key's company are returned. A client-supplied company ID cannot change this scope. IP restrictions and API rate limits still apply.
Without date parameters, returns the last 24 hours by provider send time. Results are in receipt order, oldest first, rather than sorted by UUID or sender timestamp. Dates in sendAt and response metadata are UTC; date-only filters use the Asia/Tbilisi calendar.
Query parameters
Պարամետր
Տեսակ
Պարտադիր
Նկարագրություն
date
String
Ոչ
One whole Tbilisi calendar day, for example 2026-11-02. Cannot be combined with from կամ to.
from
String
Ոչ
Inclusive start. Accepts YYYY-MM-DD or an RFC 3339 timestamp with timezone and up to 6 fractional digits. Defaults to 24 hours before the end.
to
String
Ոչ
Defaults to now. A date includes its entire Tbilisi calendar day; a timestamp is an exclusive end.
limit
Integer
Ոչ
Batch size: 1–100; default 50.
cursor
String (UUIDv4)
Ոչ
Use the previous response's meta.nextCursor to retrieve later records. Unknown or other-company cursors return HTTP 404.
Date examples
GET /v1/sms/inbound
GET /v1/sms/inbound?date=2026-11-02
GET /v1/sms/inbound?from=2026-11-01&to=2026-11-02
GET /v1/sms/inbound?from=2026-11-02T00%3A00%3A00%2B04%3A00&to=2026-11-03T00%3A00%3A00%2B04%3A00
URL-encode timezone offsets, especially + as %2B. Invalid, conflicting or reversed date filters return HTTP 400.
Message fields
Դաշտ
Տեսակ
Նկարագրություն
eventID
String (UUIDv4)
Stable UBill-generated public message ID. It is independent of the SMS provider's message ID and is also used in callbacks. Use it to deduplicate messages.
from
String
Subscriber number in local nine-digit format, for example 5XXXXXXXX.
to
String
Receiving short number.
text
String
Incoming message text. Unicode and line breaks are preserved.
noSms
Boolean
Effective NO SMS policy configured for the short number by the administrator; not the provider's flag.
sendAt
String / null
Provider send time in UTC, with microsecond precision. May be null for older imported messages.
Provider IDs and internal numeric row IDs are not exposed. Other applications of the same company with sms.inbound access see the same public message ID.
Pagination and polling
meta.count is the number of messages in this batch; meta.hasMore indicates another batch. For the next page, reuse meta.from, meta.to և meta.nextCursor so the date window remains fixed. On an empty batch, nextCursor retains the supplied cursor, or is null if no cursor was supplied.
For polling, omit dates and send the last cursor to fetch newer records within the latest 24-hour window. Persist public eventID values to handle duplicates. Use explicit dates when retrieving older history.
Errors
HTTP 400: invalid dates, limit or cursor format. HTTP 401: invalid API key or missing sms.inbound permission. HTTP 403: IP not allowed. HTTP 404: unknown or other-company cursor. HTTP 429: rate limit exceeded.
{
"statusID": 401,
"message": "Invalid API key or permission denied",
"result": []
}
Cursor not found404
Պատասխան · JSON
{
"statusID": 404,
"message": "Cursor not found",
"result": []
}
SMS API / Incoming SMS / Get Incoming SMS by eventID
Get Incoming SMS by eventID
API բանալի · Վերնագիր
GEThttps://api.ubill.dev/v1/sms/inbound/{eventID}
Get one incoming SMS
Requires the application's sms.inbound permission and key header. Replace {eventID} with the public UUID returned by the incoming-message list or callback.
The lookup is restricted to the API key's company and has no date restriction. An invalid UUID returns HTTP 400; an unknown, provider-owned or other-company UUID returns HTTP 404. The response contains statusID and a result array with one message object.
{
"statusID": 404,
"message": "Message not found",
"result": []
}
SMS API / Incoming SMS / Incoming SMS Callback
Incoming SMS Callback
API event callback
POSThttps://example.com/callback
Incoming SMS callback
Set an HTTPS հետադարձ կանչի URL for your API application and enable sms.inbound. When an incoming SMS is assigned to that company, uBill queues one delivery for each active, permitted application with a configured callback URL.
This event uses POST with a JSON body to the same callback URL used by delivery-status notifications. The event type is sms.inbound.received. Delivery-status and brand-activation events continue to use GET; a shared receiver should route by HTTP method and event type.
Authentication and fields
The application's callback key is sent both in the X-Webhook-Token header and the JSON key field. Validate it against your configured callback key. For legacy applications without a callback key, the existing API-key fallback is used.
Դաշտ
Տեսակ
Նկարագրություն
event
String
sms.inbound.received
key
String
Callback authentication key.
eventID
String (UUIDv4)
The same stable public message ID returned by the Incoming SMS API. It is not the provider's message ID.
from
String
Subscriber's local nine-digit number.
to
String
Receiving short number.
text
String
Incoming message, including Unicode and line breaks.
noSms
Boolean
Administrator-configured short-number NO SMS policy.
sendAt
String
Provider send time in UTC with microsecond precision.
Acknowledgement and retries
After safely accepting the message, return any 2xx HTTP response. Delivery is at least once: store eventID with a unique constraint and return success for a message already accepted. A timed-out request may already have reached your server.
Network failures and non-2xx responses are retried, up to 5 HTTP attempts. Retry delays are 1 minute, 5 minutes, 30 minutes, then 2 hours; actual timing depends on worker scheduling. The message ID stays unchanged. The request timeout is 10 seconds. Redirects are not followed with the token or SMS content.
Before sending, uBill rechecks application activity, permission, company and callback URL. Removing access or disabling the app cancels pending delivery. Old messages are not automatically pushed when callbacks are first enabled; use the Incoming SMS API to retrieve history.
API հավելվածի կարգավորումներում կա մեկ ընդհանուր HTTPS հետադարձ կանչի URL . The event type determines the HTTP method and payload format; not every callback is a GET request.
Օգտագործեք event to route notifications. Return any 2xx HTTP status after safely accepting an event.
Աջակցվող իրադարձություններ
Իրադարձություն
Մեթոդ
Fields
sms.delivery.updated
GET query
key, event, smsID, number, statusID, date
sms.brand.activated
GET query
key, event, brandID, brandName, authorized=1, date
sms.inbound.received
POST JSON
key, event, eventID, from, to, text, noSms, sendAt
GET callbacks authenticate with the application's callback key query parameter. Incoming SMS callbacks send that key in JSON and the X-Webhook-Token header and require sms.inbound access. GET date fields use Y-m-d H:i:s; incoming SMS sendAt uses UTC RFC 3339.
Ստեղծում է նոր հաճախորդ՝ հեռախոսահամարների հետ։ Հաճախորդի համարը ( id in the response) is generated automatically and is unique inside the company.
Պահանջվող թույլտվություն՝ 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"
}
}
Updates an existing customer in the company associated with your API key. Use the customer id returned by the create, search or get endpoints in the URL.
Պահանջվող թույլտվություն՝ customers.edit. Enable this permission in the API application settings. A Business package is required. Send key: YOUR_API_KEY և Content-Type: application/json headers.
Partial update
Send a non-empty JSON object containing only fields to change. Omitted fields keep their current values. The customer ID, balance and status cannot be changed with this endpoint. Unknown fields and fields of disabled modules are rejected.
Հարցման մարմին
Դաշտ
Տեսակ
Նկարագրություն
name
string/null, max 50
Name; null or empty string clears it.
birthDate
string/null
YYYY-MM-DD date; null or empty string clears it.
address
string/null, max 50
Address; null or empty string clears it.
column1, column2
string/null, max 50
Additional fields; null or empty string clears them.
numbers
զանգված
Replacement phone number list; omission preserves existing numbers.
typeID
ամբողջ թիվ
Existing legal type ID. Cannot be null.
personalNo
string/null, max 11
Alphanumeric personal or company code. Null or empty string clears it.
email
string/null, max 254
Valid email address. Null or empty string clears it.
lang
տող
ka, en or ru. Cannot be cleared.
Phone numbers
Omit numbers և mobile to keep existing numbers. Sending either replaces the entire phone number list; include every number you want to keep. Customers require at least one number; an empty list is rejected. Sending numbers: null is invalid. Numbers already assigned to another customer in the same company are rejected; keeping a number already on this customer is allowed.
Use the same numbers[] objects as for creation: number (local digits) or mobile (full international number), countryCode (default +995), isPrimary, smsEnabled (default true), and note (maximum 100 characters). Boolean flags accept JSON booleans or 0/1. One primary number is selected; without an explicit primary flag the first number is primary. Duplicate numbers in the submitted list are collapsed. A number must have 6 to 15 digits, and country code plus number must not exceed 15 digits.
For a single number use {"mobile":"9955XXXXXXXX","countryCode":"+995","smsEnabled":true,"numberNote":"Main"}. Send either numbers կամ mobile, never both. The top-level countryCode, smsEnabled, and numberNote shortcuts require mobile.
Update behavior
If the update fails, the previous data remains unchanged.
Պատասխաններ
HTTP
statusID
Նկարագրություն
200
0
Updated successfully. data contains the updated record and current phone numbers; all related IDs in the response are public IDs.
400
400
Invalid request or invalid field values. errors identifies the affected fields; data is null.
401
401
Invalid API key or missing edit permission.
403
403
The caller IP address is not allowed.
404
404
The record is missing, deleted, or belongs to another company.
415
415
The request Content-Type is not application/json.
429
429
API rate limit exceeded.
500
99
The update could not be saved. The previous data remains unchanged.
Գոյություն ունեցող հաճախորդի համար ստեղծում է նոր հաշիվ (ծառայություն)։ Հաշվի համարը ( id in the response) is generated automatically according to the account numbering settings, just like an account created from the uBill web interface.
Պահանջվող թույլտվություն՝ 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 მისამართი უკვე მითითებულია სხვა ანგარიშზე"
]
}
}
Billing API / Accounts / Edit Account
Edit Account
API բանալի · Վերնագիր
POSThttps://api.ubill.dev/v1/accounts/edit/100001
Updates an existing account in the company associated with your API key. Use the account id returned by the create, search or get endpoints in the URL.
Պահանջվող թույլտվություն՝ accounts.edit. Enable this permission in the API application settings. A Business package is required. Send key: YOUR_API_KEY և Content-Type: application/json headers.
Partial update
Send a non-empty JSON object containing only fields to change. Omitted fields keep their current values. The account ID and balance cannot be changed with this endpoint. Unknown fields and fields of disabled modules are rejected.
Հարցման մարմին
Դաշտ
Տեսակ
Նկարագրություն
name
string/null, max 50
Name; null or empty string clears it.
birthDate
string/null
YYYY-MM-DD date; null or empty string clears it.
address
string/null, max 50
Address; null or empty string clears it.
column1, column2
string/null, max 50
Additional fields; null or empty string clears them.
numbers
զանգված
Replacement phone number list; omission preserves existing numbers.
customerID
ամբողջ թիվ
Customer id returned by the customer endpoints for your company. Cannot be null.
areaID
integer/null
Settlement ID; null removes the settlement.
geoLocation
string/null
Latitude,longitude with latitude between -90 and 90 and longitude between -180 and 180; null or empty string clears it.
tariffID, groupID
integer/null
Public tariff/group IDs in the same company. Null removes the link.
tagsID
ամբողջ թվերի զանգված
Full replacement list of public tag IDs. [] removes all tags; omission preserves them.
mac, onuMac
string/null, max 45
Available only with the Network module. Values must be unique within the company; null or empty string clears them.
ipRangeID
integer/null
Network module only. Public NAS range ID. A changed range assigns the first free IP; if exhausted, the request fails. Null removes both the range and IP. An unchanged range preserves the IP.
stbMac
string/null, max 45
IPTV module only. Must be unique within the company.
gpsProviderID
integer/null
GPS module only. Public GPS provider ID; null clears it.
gpsTrackIdentifier
string/null, max 255
GPS module only. Unique device identifier; null or empty string clears it.
statusID
ամբողջ թիվ
Account status: 1 = Active (აქტიური), 2 = Passive (პასიური), 3 = Suspended (შეჩერებული), 4 = Cancelled (გაუქმებული). Omission keeps the current status; null, strings and unknown IDs are rejected.
Account statuses / ანგარიშის სტატუსები
statusID
Meaning
ქართული მნიშვნელობა
1
Active
აქტიური
2
Passive
პასიური
3
Suspended
შეჩერებული
4
Cancelled
გაუქმებული
Ուղարկել {"statusID":2} to make an account passive. The updated account status is returned in data.statusID, with its catalog label in data.statusName. The top-level statusID: 0 describes API success, not the account status.
Status 4 clears the assigned IP. The account, its ID and phone numbers are preserved. Balance, credit, tariff and billing dates remain unchanged by a status change.
Phone numbers
Omit numbers և mobile to keep existing numbers. Sending either replaces the entire phone number list; include every number you want to keep. Accounts may have no numbers; send numbers: [] to clear the list. Sending numbers: null is invalid. Numbers already assigned to another account in the same company are rejected; keeping a number already on this account is allowed.
Use the same numbers[] objects as for creation: number (local digits) or mobile (full international number), countryCode (default +995), isPrimary, smsEnabled (default true), and note (maximum 100 characters). Boolean flags accept JSON booleans or 0/1. One primary number is selected; without an explicit primary flag the first number is primary. Duplicate numbers in the submitted list are collapsed. A number must have 6 to 15 digits, and country code plus number must not exceed 15 digits.
For a single number use {"mobile":"9955XXXXXXXX","countryCode":"+995","smsEnabled":true,"numberNote":"Main"}. Send either numbers կամ mobile, never both. The top-level countryCode, smsEnabled, and numberNote shortcuts require mobile.
Update behavior
If the update fails, the previous data remains unchanged. Editing an account does not send the account creation SMS notification.
Պատասխաններ
HTTP
statusID
Նկարագրություն
200
0
Updated successfully. data contains the updated record and current phone numbers; all related IDs in the response are public IDs.
400
400
Invalid request or invalid field values. errors identifies the affected fields; data is null.
401
401
Invalid API key or missing edit permission.
403
403
The caller IP address is not allowed.
404
404
The record is missing, deleted, or belongs to another company.
415
415
The request Content-Type is not application/json.
429
429
API rate limit exceeded.
500
99
The update could not be saved. The previous data remains unchanged.