Izmantojot HTTP API versiju 0.15
Šī versija ir aizstāta ar jaunāku - API 0.16 versiju. API 0.15 būs pieejama, atbalstīta un pilnībā funkcionāla, un arī turpmāk tā saņems kļūdu labojumus, taču tajā netiks ieviesta jauna funkcionalitāte.
Informācija, kas nepieciešama jūsu konta un API piekļuves aktivizēšanai, ir:
jūsu servera IP adrese (ir iespējamas vairākas adreses, aizstājējzīmes (wildcard substitution) un apakštīkli (subnets).
HTTP adrese priekš "webhook", uz kuru pārsūtīt īsziņu piegādes pārskatus. Ja piegādes atskaites nav nepieciešamas, šo adresi var izlaist.
Pēc šīs informācijas saņemšanas mēs iedosim Jums API atslēgu, ko var izmantot SMS padošanai.
Piezīme - ja Jums ir vairākas vides, no kurām vēlaties sūtīt SMS, piemēram, izstrādes/testa vide un produkcijas vide, katrai no tām būs nepieciešams atsevišķs API konts un atsevišķa API atslēga.
Standarta SMS garums ir 160 GSM alfabēta simboli (aprakstīts šeit - SMS saturs un garums). Garākas SMS ir iespējamas, sūtot tās atsevišķās daļās, kas saņēmēja galā tiek apvienotas vienā SMS, taču katra no šīm daļām tiks uzrādīta rēķinā kā atsevišķa SMS. Tomēr sūtot vairākdaļu SMS, katra atsevišķā daļa ir nedaudz īsāka nekā viena SMS - viena daļa var būt līdz 153 simbolus gara, piemēram, 160 simbolu SMS var tikt nosūtīta kā viendaļīga SMS, taču 170 simbolu SMS tiks nosūtīta divās daļās - pirmā 153 simbolus gara, otrā - 17.
Tā kā GSM alfabēts satur tikai nelielu daļu no visiem iespējamajiem simboliem, ir iespējams sūtīt arī Unicode SMS, kurās iespējami visi simboli, kas pieejami UCS-2 kodējumā, taču šajā gadījumā SMS garums samazināsies. Unicode SMS var būt līdz 70 SMS garumā, vai arī, sūtot vairākdaļu SMS, katra SMS daļa var būt līdz 67 simboliem (katrs simbols aizņem 2 baitus).
Piezīme - GSM alfabētā ir vairāki simboli, kuri var aizņemt divu simbolu vietas, piemēram, eiro simbols €, kvadrātiekavas [], u.c.
Teorētiski ir iespējams sūtīt vairākdaļu SMS, kas sastāv pat no 255 daļām, taču dažādu operatoru, SMS kanālu un telefona aparātu savietojamības dēļ maksimālais pieļautais vairākdaļu SMS garums ir 7 SMS daļas.
Sūtot ziņojumu, izmantojot Traffic, kā sūtītāja identifikatoru varat norādīt jebkuru numuru vai tekstu (t.i., to, kas parādīsies saņēmēja tālrunī kā ziņojuma sūtītājs). Tas var būt jūsu tālruņa numurs, jūsu zīmola nosaukums vai jebkurš cits teksts, taču ir daži ierobežojumi:
Jums sūtītāja identifikators/-i mums iepriekš jāpieprasa. Pēc pieprasījuma tie tiks pievienoti jūsu kontam un tikai pēc tam varēsiet tos izmantot.
Sūtītāja identifikatora garums:
3 līdz 11 burtciparu rakstzīmes (vārdiskā numura gadījumā)
vai
3 līdz 14 ciparu tālruņu numuri (jābūt vai jāatbilst reāla tālruņa numura formātam)
GSM standartā burtu un ciparu sūtītāja identifikatorā atļauts izmantot tikai 0–9, a – z, A – Z rakstzīmes un apakšsvītra (_). Tehniski ir iespējams izmantot arī citas rakstzīmes, taču tas var izraisīt dažādas kļūdas, piemēram, problēmas ar ziņu parādīšanos, tiek uzrādīts cits sūtītāja vārds, ziņas tiek piegādātas atkārtoti, sūtītāja ID tiek parādīts nepareizi utt.
Esiet uzmanīgi un neizvēlieties sūtītāja identifikatoru, kas var tikt pārveidots kā tālruņa numurs, kad sūtītāja ID tiek transportēts saņēmējiem (piemēram, 2 = ABC, 3 = DEF utt.). Daudzi tālruņi automātiski pārveidos šos identifikatorus tālruņa numuros, ja saņēmējs mēģinās atbildēt vai piezvanīt uz šādu sūtītāja identifikatoru.
Atkarībā no noslēgtās vienošanās starp Jums un SIA "Sales.lv", Jūsu kontam var būt vai nu mēneša kvota SMS sūtīšanai (pēcapmaksas līgumiem) vai arī SMS apjoma limits (priekšapmaksas līgumiem) atkarībā no apmaksātā apjoma. Mēneša kvotas apmērs tiek uzstādīts abpusēji vienojoties un ir paredzēts galvenokārt drošības labad, lai nejaušu (vai arī tīšu) darbību rezultātā netiktu nosūtīts pārlieku liels SMS daudzums.
Apjoma limits priekšapmaksas kontam ir atkarīgs no apmaksātās summas.
#Piegādes atskaišu saņemšana
Pēc īsziņu izsūtīšanas, ir iespēja saņemt piegādes atskaites izmantojot "webhook".
API adrese https://traffic.sales.lv/API:0.15/
Visi dati jāpadod HTTP POST pieprasījumos ar application/x-www-form-urlencoded satura tipu (Content-Type).
Katram pieprasījumam ir obligāti parametri (to nosaukumos obligāti jāievēro lielie burti):
APIKey: piešķirtā API atslēga.
Command: komandas nosaukums.
Pārējie parametri atkarīgi no konkrētās komandas.
No komandām atgrieztie dati tiek serializēti ar JSON.
Ja saņemtais pieprasījums ir kļūdains, atbildē tiks atgriezts parametrs Error ar kļūdas kodu.
Vispārīgie kļūdu kodi, kas attiecināmi uz visām komandām:
InvalidAPIVersion: adresē norādīta kļūdaina API versija (šai versijai jābūt 0.15)
NoAPIKey: nav norādīta API atslēga
InvalidAPIKey: kļūdaina vai neeksistējoša API atslēga
UnauthorizedIP: klienta IP adrese nav autorizēta
CommandNotSpecified: nav norādīta izpildāmā komanda (Command parametrs tukšs)
CommandNotImplemented: norādītā komanda neeksistē vai nav pieejama
SystemError: sistēmas kļūda
Šajā API versijā ir iespējamas šīs komandas:
SendOne: nosūta vienu SMS ar norādītajiem parametriem.
SendMultiple: nosūta vairākas SMS ar katram saņēmējam individuāli norādītu saturu (var tikt izmantots arī vienas SMS izsūtīšanai).
SendBatch: izveido vienu jaunu SMS izsūtīšanu ar norādītajiem parametriem. Numurus pēc tam jāpievieno ar AddBatchRecipients.
AddBatchRecipients: pievieno klāt numurus ar SendBatch izveidotai izsūtīšanai. Var tikt padota vairākkārt.
GetSenders: atgriež sarakstu ar visiem pieejamajiem sūtītāju vārdiem (vārdiskajiem numuriem).
GetDelivery: atgriež piegādes statusu vienai vai vairākām īsziņām pēc to identifikatoriem.
GetReport: atgriež visus datus par vienu vai vairākām īsziņām pēc to identifikatoriem.
Vairāku SMS vienlaicīgai sūtīšanai vēlams izmantot SendBatch/AddBatchRecipients, ja vien nav nepieciešams nosūtīt individuālas īsziņas katram saņēmējam.
Nosūta vienu īsziņu ar norādītajiem parametriem.
Ievades parametri:
Number: saņēmēja telefona numurs. Pirms numura varat ievietot valsts kodu, taču bez 00 vai + (tāpat arī starptautiskajiem numuriem).
Sender: sūtītāja adreses teksts (vārdiskais numurs), piem. zīmola nosaukums.
Content: SMS saturs UTF-8 kodējumā (gan parastajām, gan Unicode SMS).
(neobligāts) SendTime: izsūtīšanas laiks (kad sākt izsūtīšanu), Unix timestamp formātā. Nav obligāts, ja tas nav norādīts, izsūtīšana sāksies uzreiz.
(neobligāts) CC: noklusētais valsts kods, kas jāizmanto numuriem, kuriem tas nav norādīts. Nav obligāts. Noklusējums būs attiecīgi tas, kas uzstādīts jūsu kontam. Ja saņēmēja numurs saturēs valsts kodu, šis netiks izmantots.
(neobligāts) Concatenated: 0/1 - ja būs 0, bet saturs būs par garu, lai SMS tiktu nosūtīta vienā daļā, tiks atgriezta kļūda. Ja būs 1, vajadzības gadījumā īsziņa tiks nosūtīta kā saliktā SMS. Ja šis parametrs tiek izlaists, tas tiks noteikts automātiski. Ņemiet vērā, ka saliktās SMS gadījumā, katra daļa rēķinā tiek aprēķināta kā atsevišķa SMS, piem. 3 daļu saliktā SMS, tiks aprēķināta kā 3 atsevišķas īsziņas.
(neobligāts) Unicode: 0/1 - ja būs 0, bet saturēs ne-GSM alfabēta simbolus, tiks atgriezta kļūda. Ja būs 1, SMS nepieciešamības gadījumā tiks nosūtīta kā Unicode īsziņa. Ja parametrs izlaists, tas tiks noteikts automātiski.
(neobligāts) Validity: SMS derīguma termiņš (minūtēs), t.i., laiks, pēc kura mobilais operators pārtrauc atkārtotu piegādi, ja tālruņa numurs ir derīgs, bet nav uzreiz sasniedzams. Pēc noklusējuma ir 1440 (24 stundas.)
Atbildē tiek atgriezti parametri:
MSSID: SMS ID, kuru jāizmanto piegādes atskaišu (delivery reports) saņemšanai.
Length: SMS garums (daļu skaits).
Unicode: Unicode kodējuma indikators (0 = sūtīšanā tiek izmantots GSM alfabēts, 1 = SMS tiek sūtīta UCS-2 kodējumā).
LongSMS: saliktās SMS indikators (0 = vienadaļīga SMS, 1 = SMS sastāv no vairākām daļām.)
Invalid: iemesls, kāpēc ziņojums var būt nederīgs. Sk. zemāk sadaļā "Nederīgie numuri". Ja numurs ir derīgs, šis lauks atbildē būs tukšs.
Network: mobilais operators, kuram pieder numurs. Vairāk par to šī dokumenta beigās
vai
Error: kļūdas kods, ja ir problēma ar komandas izsaukumu kopumā. Ja kļūdu nav, šis parametrs tiks izlaists.
Iespējamās kļūdas:
InvalidNumber: kļūdains saņēmēja numurs.
InvalidSender: šāda sūtītāja adrese neeksistē, nav pieejama vai ir kļūdaina.
NoContent: nav norādīts saturs
InvalidCC: kļūdains vai neatbalstīts valsts kods (ja kods ir norādīts).
ContentTooLong: saturs ir pārāk garš - vai nu saturs ir pārāk garš vispār, vai arī, ievades parametrs Concatenated = 0, saturs ir garāks kā viena SMS daļa.
ContentContainsInvalidCharacters: ja Unicode = 0 un saturā ir ne-GMS alfabēta simboli, tiks atgriezta šī kļūda.
MonthlyQuotaExtereded: pārsniegts jūsu konta mēneša limits.
Nosūta vairākas SMS ar katram saņēmējam individuāli norādītu saturu (var tikt izmantots arī vienas SMS izsūtīšanai).
Ievades parametri:
Sender: sūtītāja adreses teksts (vārdiskais numurs), piem. zīmola nosaukums.
Content: JSON masīvs, kur katrs elements satur saņēmēja numuru un SMS tekstu. SMS teksts jānorāda UTF-8 (gan parstajām, gan Unicode SMS). Piemērs:
(neobligāts) SendTime: izsūtīšanas laiks (kad sākt izsūtīšanu), Unix timestamp formātā. Nav obligāts, ja tas nav norādīts, izsūtīšana sāksies uzreiz.
(neobligāts) CC: noklusētais valsts kods, kas jāizmanto numuriem, kuriem tas nav norādīts. Nav obligāts. Noklusējums būs attiecīgi tas, kas uzstādīts jūsu kontam. Ja saņēmēja numurs saturēs valsts kodu, šis netiks izmantots.
(neobligāts) Concatenated: 0/1 - ja būs 0, bet saturs būs par garu, lai SMS tiktu nosūtīta vienā daļā, tiks atgriezta kļūda. Ja būs 1, vajadzības gadījumā īsziņa tiks nosūtīta kā saliktā SMS. Ja šis parametrs tiek izlaists, tas tiks noteikts automātiski. Ņemiet vērā, ka saliktās SMS gadījumā, katra daļa rēķinā tiek aprēķināta kā atsevišķa SMS, piem. 3 daļu saliktā SMS, tiks aprēķināta kā 3 atsevišķas īsziņas.
(neobligāts) Unicode: 0/1 - ja būs 0, bet saturēs ne-GSM alfabēta simbolus, tiks atgriezta kļūda. Ja būs 1, SMS nepieciešamības gadījumā tiks nosūtīta kā Unicode īsziņa. Ja parametrs izlaists, tas tiks noteikts automātiski.
Atbildē tiek atgriezts asociatīvs masīvs, kur lauka nosaukums ir SMS identifikatora numurs, bet vērtība ir:
MSSID: SMS identifikators, kuru jāizmanto piegādes atskaišu (delivery reports) saņemšanai.
CC: numura valsts kods;
Phone: tālruņa numurs;
Content: ziņojuma saturs;
Unicode: Unicode kodējuma indikators (0 = sūtīšanā tiek izmantots GSM alfabēts, 1 = SMS tiek sūtīta UCS-2 kodējumā).
LongSMS: saliktās SMS indikators (0 = vienadaļīga SMS, 1 = SMS sastāv no vairākām daļām.)
Invalid: iemesls, kāpēc ziņojums var būt nederīgs. Sk. zemāk sadaļā "Nederīgie numuri". Ja numurs ir derīgs, šis lauks atbildē būs tukšs.
Length: SMS garums (daļu skaits).
Network: mobilais operators, kuram pieder numurs. Vairāk par to šī dokumenta beigās
vai
Error: kļūdas kods, ja ir problēma ar komandas izsaukumu kopumā. Ja kļūdu nav, šis parametrs tiks izlaists.
Iespējamās kļūdas:
InvalidSender: šāda sūtītāja adrese neeksistē, nav pieejama vai ir kļūdaina.
InvalidContent: nav norādīts saturs vai arī saturs nav norādīts pareizi.
InvalidCC: kļūdains vai neatbalstīts valsts kods (ja kods ir norādīts).
QuotaExtereded: pārsniegts mēneša vai apjoma limits.
izveido vienu jaunu SMS izsūtīšanu ar norādītajiem parametriem. Numurus pēc tam jāpievieno ar AddBatchRecipients.
Ievades parametri:
Sender: sūtītāja adreses teksts (vārdiskais numurs), piem. zīmola nosaukums.
Content: SMS saturs UTF-8 kodējumā (gan parastajām, gan Unicode SMS).
(neobligāts) SendTime: izsūtīšanas laiks (kad sākt izsūtīšanu), Unix timestamp formātā. Nav obligāts, ja tas nav norādīts, izsūtīšana sāksies uzreiz.
(neobligāts) CC: noklusētais valsts kods, kas jāizmanto numuriem, kuriem tas nav norādīts. Nav obligāts. Noklusējums būs attiecīgi tas, kas uzstādīts jūsu kontam. Ja saņēmēja numurs saturēs valsts kodu, šis netiks izmantots.
(neobligāts) Concatenated: 0/1 - ja būs 0, bet saturs būs par garu, lai SMS tiktu nosūtīta vienā daļā, tiks atgriezta kļūda. Ja būs 1, vajadzības gadījumā īsziņa tiks nosūtīta kā saliktā SMS. Ja šis parametrs tiek izlaists, tas tiks noteikts automātiski. Ņemiet vērā, ka saliktās SMS gadījumā, katra daļa rēķinā tiek aprēķināta kā atsevišķa SMS, piem. 3 daļu saliktā SMS, tiks aprēķināta kā 3 atsevišķas īsziņas.
(neobligāts) Unicode: 0/1 - ja būs 0, bet saturēs ne-GSM alfabēta simbolus, tiks atgriezta kļūda. Ja būs 1, SMS nepieciešamības gadījumā tiks nosūtīta kā Unicode īsziņa. Ja parametrs izlaists, tas tiks noteikts automātiski.
Atbildē tiek atgriezti parametri:
BatchID: izsūtīšanas ID, ko jāizmanto padodot saņēmēju numurus ar AddBatchRecipients.
Error: kļūdas kods, ja ir problēma ar komandas izsaukumu kopumā. Ja kļūdu nav, šis parametrs tiks izlaists.
Iespējamās kļūdas:
InvalidSender: šāda sūtītāja adrese neeksistē, nav pieejama vai ir kļūdaina.
NoContent: nav norādīts saturs.
InvalidCC: kļūdains vai neatbalstīts valsts kods (ja kods ir norādīts).
ContentTooLong: saturs ir pārāk garš - vai nu saturs ir pārāk garš vispār, vai arī, ievades parametrs Concatenated = 0, saturs ir garāks kā viena SMS daļa.
ContentContainsInvalidCharacters: ja Unicode = 0 un saturā ir ne-GMS alfabēta simboli, tiks atgriezta šī kļūda.
QuotaExtereded: pārsniegts limits.
Pievieno saņēmēju numurus jau ar SendBatch izveidotai izsūtīšanai. Var tikt izsaukta vairākas reizes.
Ievades parametri:
BatchID: no SendBatch atgriezts izsūtīšanas ID.
Recipients: JSON masīvs ar saņēmēju numuriem, piem. "[3712987654321, 37129999999, ...]"
Atbilde saturēs šādus parametrus:
MSSID: asociatīvs masīvs, kur atslēga būs tālruņa numurs un vērtība būs SMS ID. Ja ar konkrēto saņēmēju būs radusies problēma, vērtība būs kļūdas kods.
Error: kļūdas kods, ja ir problēma ar komandas izsaukumu kopumā. Ja kļūdu nav, šis parametrs tiks izlaists.
Ja starp saņēmējiem kāds numurs atkārtojas vairākas reizes, atgriežamajos datos tas parādīsies tikai vienu reizi ar vienu SMS ID, un nosūtīta tam tiks tikai viena SMS.
Iespējamās kļūdas:
Kā MSSID vērtības:
-1: jebkura cita kļūda.
-2: nepareizs numurs - neatbilst konkrētās valsts numura formātam.
-3: nepareizs numurs - numurs tehniski ir pareizs, bet nav reģistrēts mobilajā tīklā vai ir reģistrēts tīklā, kurā nav iespējama īsziņu sūtīšana. Pašlaik tas darbojas ierobežotā skaitā valstu. Šo kļūdu var atgriezt arī tad, ja numurs ir reģistrēts, bet tas nav mobilā tālruņa numurs;
-4: limits ir pārsniegts.
Error parametrā:
InvalidBatchID: šāds sūtījuma ID neeksistē vai arī nav pieejams konkrētajam API kontam.
InvalidRecipients: saņēmēju sarakstu nav iespējams nolasīt.
QuotaExceeded: limits pārsniegts. Kļūda tiek atgriezta tikai tad, ja limits ir pārsniegts jau pirms šīs komandas. Ja limits tiek pārsniegta, pēc SMS nosūtīšanas daļai saņēmēju, katram saņēmēja numuram, kas pārsniedz limitu, būs kļūda -4.
Atgriež sarakstu ar visiem pieejamajiem sūtītāju vārdiem (vārdiskajiem numuriem), kuri piešķirti jūsu kontam.
Ievades parametri: nav
Atbildes parametri:
Senders: masīvs ar visiem piešķirtajiem sūtītāja identifikatoriem vai tukšs masīvs, ja sūtītāja ID nav piešķirts/-i.
Atgriež viena vai vairāku ziņojumu piegādes atskaiti pēc to identifikatoru numuriem.
Ievades parametri:
MSSID: vienas īsziņas identifikators vai arī JSON masīvs ar vairākiem SMS identifikatoriem.
Atbilde satur:
asociatīvu masīvu, kur atslēga ir dotais SMS identifikators un vērtība ir īsziņas piegādes statuss
vai
Error: kļūdas kods, ja ir problēma ar komandas izsaukumu kopumā.
Iespējamās kļūdas:
InvalidMSSID: kļūdaini norādīts vai arī nav norādīts SMS identifikators (vai to masīvs).
Atgriež visus datus par vienu vai vairākām īsziņām pēc to identifikatoriem.
Ievades parametri:
MSSID: Vienas īsziņas identifikators vai arī JSON masīvs ar vairākiem SMS identifikatoriem.
Atbilde satur asociatīvu masīvu, kur atslēga ir dotais SMS identifikators un vērtības, kas satur:
ID: SMS identifikators.
CC: numura valsts kods.
Phone: tālruņa numurs.
Content: SMS saturs.
Unicode: Unicode kodējuma indikators (0 = sūtīšanā tiek izmantots GSM alfabēts, 1 = SMS tiek sūtīta UCS-2 kodējumā).
LongSMS: saliktās SMS indikators (0 = vienadaļīga SMS, 1 = SMS sastāv no vairākām daļām.).
Length: SMS garums (daļu skaits).
Status: SMS piegādes statuss, viens no dokumentācijas beigās aprakstītajiem statusiem.
SendTime: nosūtīšanas laiks.
DLRTime: piegādes atskaites saņemšanas laiks. (Šis ir laiks, kad piegādes atskaite tika saņemta, nevis īsziņas piegādāšanas vai atteikšanas laiks).
Validity: SMS derīguma termiņš (minūtēs), t.i., laiks, pēc kura mobilais operators pārtrauc atkārtotu piegādi, ja tālruņa numurs ir derīgs, bet nav uzreiz sasniedzams. Pēc noklusējuma ir 1440 (24 stundas)
vai
Error: kļūdas kods, ja ir problēma ar komandas izsaukumu kopumā.
Iespējamās kļūdas:
InvalidMSSID: kļūdaini norādīts vai arī nav norādīts SMS identifikators.
Komandas SendOne, SendMultiple un AddBatchRecipients var atgriezt parametru Invalid, kas norāda iemeslu, kāpēc numurs ir nederīgs. Šādi iemesli var būt:
Number: kļūdains numura formāts (piemēram, Latvijas numurs nesatur 8 ciparus).
CC: numurs satur neatļautu valsts kodu, piemēram, ja kontam ir atļauta sūtīšana uz Latvijas numuriem, numuri ar Lietuvas valsts kodu būs šādi.
MNP: numurs nav piešķirts nevienam zināmajam mobilajam operatoram.
ContentLength: īsziņām, kur saturs tiek individuāli norādīts katram saņēmējam, piemēram, sūtot ar SendMultiple, norādītais satura teksts tieši šim numuram ir pārāk garš.
Network: īsziņu sūtīšana uz tīklu, kam pieder numurs, nav iespējama. Piemēram, ja operators netiek atbalstīts vai operators nav spējīgs saņemt SMS.
Šīs īsziņas netiek ieskaitītas konta kopsummā un neietekmē konta atlikumu.
Lai norādītu numura piederību mobilo sakaru operatoram, atbildēs uz padotajām īsziņām var tikt norādīts papildus parametrs Network, kas saturēs vienu no šiem kodiem:
Latvijā:
LMT: LMT
TELE2LV: Tele2 Latvija
BITELV: Bite Latvia
Igaunijā:
TELE2EE: Tele2 Eesti
EMT: Telia Eesti, agrāk EMT
ELISA: Elisa Eesti
Lietuvā:
TELE2LT: Tele2 Lietuva
OMNITEL: Telia Lietuva, agrāk Omnitel
BITELT: Bite Lietuva
Var rasties papildu tīkla kodi, un tie nākotnē var mainīties atkarībā no tīkla operatoriem. Tomēr šajās valstīs šie ir galvenie operatori, un tie nemainīsies.
API izsaukumu piemēri, dažādās valodās un izmantojot dažādas tehnoloģijas ir norādīti atsevišķā rakstā:
API pieprasījumi izmantojot cURL
Iesākumam
Informācija, kas nepieciešama jūsu konta un API piekļuves aktivizēšanai, ir:
jūsu servera IP adrese (ir iespējamas vairākas adreses, aizstājējzīmes (wildcard substitution) un apakštīkli (subnets).
HTTP adrese priekš "webhook", uz kuru pārsūtīt īsziņu piegādes pārskatus. Ja piegādes atskaites nav nepieciešamas, šo adresi var izlaist.
Pēc šīs informācijas saņemšanas mēs iedosim Jums API atslēgu, ko var izmantot SMS padošanai.
Piezīme - ja Jums ir vairākas vides, no kurām vēlaties sūtīt SMS, piemēram, izstrādes/testa vide un produkcijas vide, katrai no tām būs nepieciešams atsevišķs API konts un atsevišķa API atslēga.
Vispārīga SMS informācija
Standarta SMS garums ir 160 GSM alfabēta simboli (aprakstīts šeit - SMS saturs un garums). Garākas SMS ir iespējamas, sūtot tās atsevišķās daļās, kas saņēmēja galā tiek apvienotas vienā SMS, taču katra no šīm daļām tiks uzrādīta rēķinā kā atsevišķa SMS. Tomēr sūtot vairākdaļu SMS, katra atsevišķā daļa ir nedaudz īsāka nekā viena SMS - viena daļa var būt līdz 153 simbolus gara, piemēram, 160 simbolu SMS var tikt nosūtīta kā viendaļīga SMS, taču 170 simbolu SMS tiks nosūtīta divās daļās - pirmā 153 simbolus gara, otrā - 17.
Tā kā GSM alfabēts satur tikai nelielu daļu no visiem iespējamajiem simboliem, ir iespējams sūtīt arī Unicode SMS, kurās iespējami visi simboli, kas pieejami UCS-2 kodējumā, taču šajā gadījumā SMS garums samazināsies. Unicode SMS var būt līdz 70 SMS garumā, vai arī, sūtot vairākdaļu SMS, katra SMS daļa var būt līdz 67 simboliem (katrs simbols aizņem 2 baitus).
Piezīme - GSM alfabētā ir vairāki simboli, kuri var aizņemt divu simbolu vietas, piemēram, eiro simbols €, kvadrātiekavas [], u.c.
Teorētiski ir iespējams sūtīt vairākdaļu SMS, kas sastāv pat no 255 daļām, taču dažādu operatoru, SMS kanālu un telefona aparātu savietojamības dēļ maksimālais pieļautais vairākdaļu SMS garums ir 7 SMS daļas.
Sūtītātja identifikators
Sūtot ziņojumu, izmantojot Traffic, kā sūtītāja identifikatoru varat norādīt jebkuru numuru vai tekstu (t.i., to, kas parādīsies saņēmēja tālrunī kā ziņojuma sūtītājs). Tas var būt jūsu tālruņa numurs, jūsu zīmola nosaukums vai jebkurš cits teksts, taču ir daži ierobežojumi:
Jums sūtītāja identifikators/-i mums iepriekš jāpieprasa. Pēc pieprasījuma tie tiks pievienoti jūsu kontam un tikai pēc tam varēsiet tos izmantot.
Sūtītāja identifikatora garums:
3 līdz 11 burtciparu rakstzīmes (vārdiskā numura gadījumā)
vai
3 līdz 14 ciparu tālruņu numuri (jābūt vai jāatbilst reāla tālruņa numura formātam)
GSM standartā burtu un ciparu sūtītāja identifikatorā atļauts izmantot tikai 0–9, a – z, A – Z rakstzīmes un apakšsvītra (_). Tehniski ir iespējams izmantot arī citas rakstzīmes, taču tas var izraisīt dažādas kļūdas, piemēram, problēmas ar ziņu parādīšanos, tiek uzrādīts cits sūtītāja vārds, ziņas tiek piegādātas atkārtoti, sūtītāja ID tiek parādīts nepareizi utt.
Esiet uzmanīgi un neizvēlieties sūtītāja identifikatoru, kas var tikt pārveidots kā tālruņa numurs, kad sūtītāja ID tiek transportēts saņēmējiem (piemēram, 2 = ABC, 3 = DEF utt.). Daudzi tālruņi automātiski pārveidos šos identifikatorus tālruņa numuros, ja saņēmējs mēģinās atbildēt vai piezvanīt uz šādu sūtītāja identifikatoru.
Vispārīga sistēmas informācija
Atkarībā no noslēgtās vienošanās starp Jums un SIA "Sales.lv", Jūsu kontam var būt vai nu mēneša kvota SMS sūtīšanai (pēcapmaksas līgumiem) vai arī SMS apjoma limits (priekšapmaksas līgumiem) atkarībā no apmaksātā apjoma. Mēneša kvotas apmērs tiek uzstādīts abpusēji vienojoties un ir paredzēts galvenokārt drošības labad, lai nejaušu (vai arī tīšu) darbību rezultātā netiktu nosūtīts pārlieku liels SMS daudzums.
Apjoma limits priekšapmaksas kontam ir atkarīgs no apmaksātās summas.
#Piegādes atskaišu saņemšana
Pēc īsziņu izsūtīšanas, ir iespēja saņemt piegādes atskaites izmantojot "webhook".
API informācija
API adrese https://traffic.sales.lv/API:0.15/
Visi dati jāpadod HTTP POST pieprasījumos ar application/x-www-form-urlencoded satura tipu (Content-Type).
Katram pieprasījumam ir obligāti parametri (to nosaukumos obligāti jāievēro lielie burti):
APIKey: piešķirtā API atslēga.
Command: komandas nosaukums.
Pārējie parametri atkarīgi no konkrētās komandas.
No komandām atgrieztie dati tiek serializēti ar JSON.
Ja saņemtais pieprasījums ir kļūdains, atbildē tiks atgriezts parametrs Error ar kļūdas kodu.
Vispārīgie kļūdu kodi, kas attiecināmi uz visām komandām:
InvalidAPIVersion: adresē norādīta kļūdaina API versija (šai versijai jābūt 0.15)
NoAPIKey: nav norādīta API atslēga
InvalidAPIKey: kļūdaina vai neeksistējoša API atslēga
UnauthorizedIP: klienta IP adrese nav autorizēta
CommandNotSpecified: nav norādīta izpildāmā komanda (Command parametrs tukšs)
CommandNotImplemented: norādītā komanda neeksistē vai nav pieejama
SystemError: sistēmas kļūda
Šajā API versijā ir iespējamas šīs komandas:
SendOne: nosūta vienu SMS ar norādītajiem parametriem.
SendMultiple: nosūta vairākas SMS ar katram saņēmējam individuāli norādītu saturu (var tikt izmantots arī vienas SMS izsūtīšanai).
SendBatch: izveido vienu jaunu SMS izsūtīšanu ar norādītajiem parametriem. Numurus pēc tam jāpievieno ar AddBatchRecipients.
AddBatchRecipients: pievieno klāt numurus ar SendBatch izveidotai izsūtīšanai. Var tikt padota vairākkārt.
GetSenders: atgriež sarakstu ar visiem pieejamajiem sūtītāju vārdiem (vārdiskajiem numuriem).
GetDelivery: atgriež piegādes statusu vienai vai vairākām īsziņām pēc to identifikatoriem.
GetReport: atgriež visus datus par vienu vai vairākām īsziņām pēc to identifikatoriem.
Vairāku SMS vienlaicīgai sūtīšanai vēlams izmantot SendBatch/AddBatchRecipients, ja vien nav nepieciešams nosūtīt individuālas īsziņas katram saņēmējam.
Komandu apraksts
SendOne
Nosūta vienu īsziņu ar norādītajiem parametriem.
Ievades parametri:
Number: saņēmēja telefona numurs. Pirms numura varat ievietot valsts kodu, taču bez 00 vai + (tāpat arī starptautiskajiem numuriem).
Sender: sūtītāja adreses teksts (vārdiskais numurs), piem. zīmola nosaukums.
Content: SMS saturs UTF-8 kodējumā (gan parastajām, gan Unicode SMS).
(neobligāts) SendTime: izsūtīšanas laiks (kad sākt izsūtīšanu), Unix timestamp formātā. Nav obligāts, ja tas nav norādīts, izsūtīšana sāksies uzreiz.
(neobligāts) CC: noklusētais valsts kods, kas jāizmanto numuriem, kuriem tas nav norādīts. Nav obligāts. Noklusējums būs attiecīgi tas, kas uzstādīts jūsu kontam. Ja saņēmēja numurs saturēs valsts kodu, šis netiks izmantots.
(neobligāts) Concatenated: 0/1 - ja būs 0, bet saturs būs par garu, lai SMS tiktu nosūtīta vienā daļā, tiks atgriezta kļūda. Ja būs 1, vajadzības gadījumā īsziņa tiks nosūtīta kā saliktā SMS. Ja šis parametrs tiek izlaists, tas tiks noteikts automātiski. Ņemiet vērā, ka saliktās SMS gadījumā, katra daļa rēķinā tiek aprēķināta kā atsevišķa SMS, piem. 3 daļu saliktā SMS, tiks aprēķināta kā 3 atsevišķas īsziņas.
(neobligāts) Unicode: 0/1 - ja būs 0, bet saturēs ne-GSM alfabēta simbolus, tiks atgriezta kļūda. Ja būs 1, SMS nepieciešamības gadījumā tiks nosūtīta kā Unicode īsziņa. Ja parametrs izlaists, tas tiks noteikts automātiski.
(neobligāts) Validity: SMS derīguma termiņš (minūtēs), t.i., laiks, pēc kura mobilais operators pārtrauc atkārtotu piegādi, ja tālruņa numurs ir derīgs, bet nav uzreiz sasniedzams. Pēc noklusējuma ir 1440 (24 stundas.)
Atbildē tiek atgriezti parametri:
MSSID: SMS ID, kuru jāizmanto piegādes atskaišu (delivery reports) saņemšanai.
Length: SMS garums (daļu skaits).
Unicode: Unicode kodējuma indikators (0 = sūtīšanā tiek izmantots GSM alfabēts, 1 = SMS tiek sūtīta UCS-2 kodējumā).
LongSMS: saliktās SMS indikators (0 = vienadaļīga SMS, 1 = SMS sastāv no vairākām daļām.)
Invalid: iemesls, kāpēc ziņojums var būt nederīgs. Sk. zemāk sadaļā "Nederīgie numuri". Ja numurs ir derīgs, šis lauks atbildē būs tukšs.
Network: mobilais operators, kuram pieder numurs. Vairāk par to šī dokumenta beigās
vai
Error: kļūdas kods, ja ir problēma ar komandas izsaukumu kopumā. Ja kļūdu nav, šis parametrs tiks izlaists.
Iespējamās kļūdas:
InvalidNumber: kļūdains saņēmēja numurs.
InvalidSender: šāda sūtītāja adrese neeksistē, nav pieejama vai ir kļūdaina.
NoContent: nav norādīts saturs
InvalidCC: kļūdains vai neatbalstīts valsts kods (ja kods ir norādīts).
ContentTooLong: saturs ir pārāk garš - vai nu saturs ir pārāk garš vispār, vai arī, ievades parametrs Concatenated = 0, saturs ir garāks kā viena SMS daļa.
ContentContainsInvalidCharacters: ja Unicode = 0 un saturā ir ne-GMS alfabēta simboli, tiks atgriezta šī kļūda.
MonthlyQuotaExtereded: pārsniegts jūsu konta mēneša limits.
SendMultiple
Nosūta vairākas SMS ar katram saņēmējam individuāli norādītu saturu (var tikt izmantots arī vienas SMS izsūtīšanai).
Ievades parametri:
Sender: sūtītāja adreses teksts (vārdiskais numurs), piem. zīmola nosaukums.
Content: JSON masīvs, kur katrs elements satur saņēmēja numuru un SMS tekstu. SMS teksts jānorāda UTF-8 (gan parstajām, gan Unicode SMS). Piemērs:
[
[26480847, “Hello”],
[21234567, “Hello”],
[29876543, “Hello, world!”]
](neobligāts) SendTime: izsūtīšanas laiks (kad sākt izsūtīšanu), Unix timestamp formātā. Nav obligāts, ja tas nav norādīts, izsūtīšana sāksies uzreiz.
(neobligāts) CC: noklusētais valsts kods, kas jāizmanto numuriem, kuriem tas nav norādīts. Nav obligāts. Noklusējums būs attiecīgi tas, kas uzstādīts jūsu kontam. Ja saņēmēja numurs saturēs valsts kodu, šis netiks izmantots.
(neobligāts) Concatenated: 0/1 - ja būs 0, bet saturs būs par garu, lai SMS tiktu nosūtīta vienā daļā, tiks atgriezta kļūda. Ja būs 1, vajadzības gadījumā īsziņa tiks nosūtīta kā saliktā SMS. Ja šis parametrs tiek izlaists, tas tiks noteikts automātiski. Ņemiet vērā, ka saliktās SMS gadījumā, katra daļa rēķinā tiek aprēķināta kā atsevišķa SMS, piem. 3 daļu saliktā SMS, tiks aprēķināta kā 3 atsevišķas īsziņas.
(neobligāts) Unicode: 0/1 - ja būs 0, bet saturēs ne-GSM alfabēta simbolus, tiks atgriezta kļūda. Ja būs 1, SMS nepieciešamības gadījumā tiks nosūtīta kā Unicode īsziņa. Ja parametrs izlaists, tas tiks noteikts automātiski.
Atbildē tiek atgriezts asociatīvs masīvs, kur lauka nosaukums ir SMS identifikatora numurs, bet vērtība ir:
MSSID: SMS identifikators, kuru jāizmanto piegādes atskaišu (delivery reports) saņemšanai.
CC: numura valsts kods;
Phone: tālruņa numurs;
Content: ziņojuma saturs;
Unicode: Unicode kodējuma indikators (0 = sūtīšanā tiek izmantots GSM alfabēts, 1 = SMS tiek sūtīta UCS-2 kodējumā).
LongSMS: saliktās SMS indikators (0 = vienadaļīga SMS, 1 = SMS sastāv no vairākām daļām.)
Invalid: iemesls, kāpēc ziņojums var būt nederīgs. Sk. zemāk sadaļā "Nederīgie numuri". Ja numurs ir derīgs, šis lauks atbildē būs tukšs.
Length: SMS garums (daļu skaits).
Network: mobilais operators, kuram pieder numurs. Vairāk par to šī dokumenta beigās
vai
Error: kļūdas kods, ja ir problēma ar komandas izsaukumu kopumā. Ja kļūdu nav, šis parametrs tiks izlaists.
Iespējamās kļūdas:
InvalidSender: šāda sūtītāja adrese neeksistē, nav pieejama vai ir kļūdaina.
InvalidContent: nav norādīts saturs vai arī saturs nav norādīts pareizi.
InvalidCC: kļūdains vai neatbalstīts valsts kods (ja kods ir norādīts).
QuotaExtereded: pārsniegts mēneša vai apjoma limits.
SendBatch
izveido vienu jaunu SMS izsūtīšanu ar norādītajiem parametriem. Numurus pēc tam jāpievieno ar AddBatchRecipients.
Ievades parametri:
Sender: sūtītāja adreses teksts (vārdiskais numurs), piem. zīmola nosaukums.
Content: SMS saturs UTF-8 kodējumā (gan parastajām, gan Unicode SMS).
(neobligāts) SendTime: izsūtīšanas laiks (kad sākt izsūtīšanu), Unix timestamp formātā. Nav obligāts, ja tas nav norādīts, izsūtīšana sāksies uzreiz.
(neobligāts) CC: noklusētais valsts kods, kas jāizmanto numuriem, kuriem tas nav norādīts. Nav obligāts. Noklusējums būs attiecīgi tas, kas uzstādīts jūsu kontam. Ja saņēmēja numurs saturēs valsts kodu, šis netiks izmantots.
(neobligāts) Concatenated: 0/1 - ja būs 0, bet saturs būs par garu, lai SMS tiktu nosūtīta vienā daļā, tiks atgriezta kļūda. Ja būs 1, vajadzības gadījumā īsziņa tiks nosūtīta kā saliktā SMS. Ja šis parametrs tiek izlaists, tas tiks noteikts automātiski. Ņemiet vērā, ka saliktās SMS gadījumā, katra daļa rēķinā tiek aprēķināta kā atsevišķa SMS, piem. 3 daļu saliktā SMS, tiks aprēķināta kā 3 atsevišķas īsziņas.
(neobligāts) Unicode: 0/1 - ja būs 0, bet saturēs ne-GSM alfabēta simbolus, tiks atgriezta kļūda. Ja būs 1, SMS nepieciešamības gadījumā tiks nosūtīta kā Unicode īsziņa. Ja parametrs izlaists, tas tiks noteikts automātiski.
Atbildē tiek atgriezti parametri:
BatchID: izsūtīšanas ID, ko jāizmanto padodot saņēmēju numurus ar AddBatchRecipients.
Error: kļūdas kods, ja ir problēma ar komandas izsaukumu kopumā. Ja kļūdu nav, šis parametrs tiks izlaists.
Iespējamās kļūdas:
InvalidSender: šāda sūtītāja adrese neeksistē, nav pieejama vai ir kļūdaina.
NoContent: nav norādīts saturs.
InvalidCC: kļūdains vai neatbalstīts valsts kods (ja kods ir norādīts).
ContentTooLong: saturs ir pārāk garš - vai nu saturs ir pārāk garš vispār, vai arī, ievades parametrs Concatenated = 0, saturs ir garāks kā viena SMS daļa.
ContentContainsInvalidCharacters: ja Unicode = 0 un saturā ir ne-GMS alfabēta simboli, tiks atgriezta šī kļūda.
QuotaExtereded: pārsniegts limits.
AddBatchRecipients
Pievieno saņēmēju numurus jau ar SendBatch izveidotai izsūtīšanai. Var tikt izsaukta vairākas reizes.
Ievades parametri:
BatchID: no SendBatch atgriezts izsūtīšanas ID.
Recipients: JSON masīvs ar saņēmēju numuriem, piem. "[3712987654321, 37129999999, ...]"
Atbilde saturēs šādus parametrus:
MSSID: asociatīvs masīvs, kur atslēga būs tālruņa numurs un vērtība būs SMS ID. Ja ar konkrēto saņēmēju būs radusies problēma, vērtība būs kļūdas kods.
Error: kļūdas kods, ja ir problēma ar komandas izsaukumu kopumā. Ja kļūdu nav, šis parametrs tiks izlaists.
Ja starp saņēmējiem kāds numurs atkārtojas vairākas reizes, atgriežamajos datos tas parādīsies tikai vienu reizi ar vienu SMS ID, un nosūtīta tam tiks tikai viena SMS.
Iespējamās kļūdas:
Kā MSSID vērtības:
-1: jebkura cita kļūda.
-2: nepareizs numurs - neatbilst konkrētās valsts numura formātam.
-3: nepareizs numurs - numurs tehniski ir pareizs, bet nav reģistrēts mobilajā tīklā vai ir reģistrēts tīklā, kurā nav iespējama īsziņu sūtīšana. Pašlaik tas darbojas ierobežotā skaitā valstu. Šo kļūdu var atgriezt arī tad, ja numurs ir reģistrēts, bet tas nav mobilā tālruņa numurs;
-4: limits ir pārsniegts.
Error parametrā:
InvalidBatchID: šāds sūtījuma ID neeksistē vai arī nav pieejams konkrētajam API kontam.
InvalidRecipients: saņēmēju sarakstu nav iespējams nolasīt.
QuotaExceeded: limits pārsniegts. Kļūda tiek atgriezta tikai tad, ja limits ir pārsniegts jau pirms šīs komandas. Ja limits tiek pārsniegta, pēc SMS nosūtīšanas daļai saņēmēju, katram saņēmēja numuram, kas pārsniedz limitu, būs kļūda -4.
GetSenders
Atgriež sarakstu ar visiem pieejamajiem sūtītāju vārdiem (vārdiskajiem numuriem), kuri piešķirti jūsu kontam.
Ievades parametri: nav
Atbildes parametri:
Senders: masīvs ar visiem piešķirtajiem sūtītāja identifikatoriem vai tukšs masīvs, ja sūtītāja ID nav piešķirts/-i.
GetDelivery
Atgriež viena vai vairāku ziņojumu piegādes atskaiti pēc to identifikatoru numuriem.
Ievades parametri:
MSSID: vienas īsziņas identifikators vai arī JSON masīvs ar vairākiem SMS identifikatoriem.
Atbilde satur:
asociatīvu masīvu, kur atslēga ir dotais SMS identifikators un vērtība ir īsziņas piegādes statuss
vai
Error: kļūdas kods, ja ir problēma ar komandas izsaukumu kopumā.
Iespējamās kļūdas:
InvalidMSSID: kļūdaini norādīts vai arī nav norādīts SMS identifikators (vai to masīvs).
GetReport
Atgriež visus datus par vienu vai vairākām īsziņām pēc to identifikatoriem.
Ievades parametri:
MSSID: Vienas īsziņas identifikators vai arī JSON masīvs ar vairākiem SMS identifikatoriem.
Atbilde satur asociatīvu masīvu, kur atslēga ir dotais SMS identifikators un vērtības, kas satur:
ID: SMS identifikators.
CC: numura valsts kods.
Phone: tālruņa numurs.
Content: SMS saturs.
Unicode: Unicode kodējuma indikators (0 = sūtīšanā tiek izmantots GSM alfabēts, 1 = SMS tiek sūtīta UCS-2 kodējumā).
LongSMS: saliktās SMS indikators (0 = vienadaļīga SMS, 1 = SMS sastāv no vairākām daļām.).
Length: SMS garums (daļu skaits).
Status: SMS piegādes statuss, viens no dokumentācijas beigās aprakstītajiem statusiem.
SendTime: nosūtīšanas laiks.
DLRTime: piegādes atskaites saņemšanas laiks. (Šis ir laiks, kad piegādes atskaite tika saņemta, nevis īsziņas piegādāšanas vai atteikšanas laiks).
Validity: SMS derīguma termiņš (minūtēs), t.i., laiks, pēc kura mobilais operators pārtrauc atkārtotu piegādi, ja tālruņa numurs ir derīgs, bet nav uzreiz sasniedzams. Pēc noklusējuma ir 1440 (24 stundas)
vai
Error: kļūdas kods, ja ir problēma ar komandas izsaukumu kopumā.
Iespējamās kļūdas:
InvalidMSSID: kļūdaini norādīts vai arī nav norādīts SMS identifikators.
Nederīgi numuri
Komandas SendOne, SendMultiple un AddBatchRecipients var atgriezt parametru Invalid, kas norāda iemeslu, kāpēc numurs ir nederīgs. Šādi iemesli var būt:
Number: kļūdains numura formāts (piemēram, Latvijas numurs nesatur 8 ciparus).
CC: numurs satur neatļautu valsts kodu, piemēram, ja kontam ir atļauta sūtīšana uz Latvijas numuriem, numuri ar Lietuvas valsts kodu būs šādi.
MNP: numurs nav piešķirts nevienam zināmajam mobilajam operatoram.
ContentLength: īsziņām, kur saturs tiek individuāli norādīts katram saņēmējam, piemēram, sūtot ar SendMultiple, norādītais satura teksts tieši šim numuram ir pārāk garš.
Network: īsziņu sūtīšana uz tīklu, kam pieder numurs, nav iespējama. Piemēram, ja operators netiek atbalstīts vai operators nav spējīgs saņemt SMS.
Šīs īsziņas netiek ieskaitītas konta kopsummā un neietekmē konta atlikumu.
Operatoru kodi
Lai norādītu numura piederību mobilo sakaru operatoram, atbildēs uz padotajām īsziņām var tikt norādīts papildus parametrs Network, kas saturēs vienu no šiem kodiem:
Latvijā:
LMT: LMT
TELE2LV: Tele2 Latvija
BITELV: Bite Latvia
Igaunijā:
TELE2EE: Tele2 Eesti
EMT: Telia Eesti, agrāk EMT
ELISA: Elisa Eesti
Lietuvā:
TELE2LT: Tele2 Lietuva
OMNITEL: Telia Lietuva, agrāk Omnitel
BITELT: Bite Lietuva
Var rasties papildu tīkla kodi, un tie nākotnē var mainīties atkarībā no tīkla operatoriem. Tomēr šajās valstīs šie ir galvenie operatori, un tie nemainīsies.
Lietošanas piemēri
API izsaukumu piemēri, dažādās valodās un izmantojot dažādas tehnoloģijas ir norādīti atsevišķā rakstā:
API pieprasījumi izmantojot cURL
Atjaunināts: 09/06/2021
Paldies!