FAQ

Vsak zahtevek mora vsebovati API ključ v HTTP glavi:

apikey: YOUR_API_KEY

API ključ obravnavajte kot geslo. Ne vključujte ga v javno dostopno izvorno kodo, aplikacije na strani odjemalca ali javne repozitorije.

Zahtevek mora vsebovati najmanj naslednji glavi:

Content-Type: application/json

apikey: YOUR_API_KEY

SMS sporočila pošljete z zahtevkom:

POST https://api.lertify.app/v1/sms/messages

Telo zahtevka mora biti poslano v podatkovnem formatu JSON.

Obvezna so naslednja polja:

• sender – naziv ali telefonska številka pošiljatelja,
• destinations – seznam telefonskih številk prejemnikov,
• message.content – vsebina SMS sporočila.

Polja message.isUnicode, deliveryReportUrl in scheduledTime niso obvezna.

Telefonske številke morajo biti zapisane v mednarodnem formatu s predpono +.

Primer:

+38640123456

Ne uporabljajte lokalnega zapisa, začetne ničle, presledkov ali drugih ločil.

Da. V polju destinations lahko pošljete seznam več telefonskih številk:

{

“destinations”: [

“+38640123456”,

“+38640987654”

]

}

 

Za vsakega prejemnika se ustvari ločeno sporočilo z lastnim identifikatorjem in statusom dostave.

Polje sender vsebuje naziv ali telefonsko številko pošiljatelja, ki bo prikazana prejemniku.

Uporabite lahko samo pošiljatelja, ki je omogočen oziroma dodeljen vašemu računu. Razpoložljivost alfanumeričnih nazivov in telefonskih številk je odvisna od ciljne države ter pravil mobilnih operaterjev.

Če sporočilo vsebuje Unicode znake, nastavite:

{

“message”: {

“content”: “Vaše sporočilo vsebuje šumnike.”,

“isUnicode”: true

}

}

 

Unicode je potreben za šumnike, nekatere posebne znake, nelatinične pisave in določene simbole. Uporaba Unicode zmanjša število znakov, ki jih lahko vsebuje posamezen SMS-del.

V zahtevek dodajte polje scheduledTime, ki vsebuje Unix timestamp v sekundah:

{

“scheduledTime”: 1789297200

}

 

Če je navedeni čas v preteklosti, se sporočilo pošlje takoj.

Polje scheduledTime je Unix timestamp in zato predstavlja absolutni časovni trenutek.

V odgovoru je lahko čas načrtovanega pošiljanja prikazan tudi v obliki UTC, na primer:

2026-09-13T09:00:00Z

Pred pretvorbo lokalnega časa v Unix timestamp vedno upoštevajte časovni pas in morebitni poletni čas.

Uspešen odgovor vsebuje seznam ustvarjenih sporočil. Za posameznega prejemnika sta vrnjena najmanj:

• messageId – enolični identifikator sporočila,
• destination – telefonska številka prejemnika.

Pri načrtovanem sporočilu odgovor vsebuje tudi informacije o načrtovanem času pošiljanja.

Identifikator messageId shranite, saj se uporablja za povezovanje sporočila s poznejšimi poročili o dostavi.

Ne. HTTP status 200 pomeni, da je bil zahtevek sprejet v obdelavo.

Končni rezultat dostave spremljate prek poročil o dostavi. Sporočilo je dostavljeno šele, ko prejmete status DELIVERED.

Za telefonsko oziroma virtualno številko, ki podpira prejemanje SMS sporočil, mora biti nastavljen inboundUrl.

Ob prejemu sporočila Lertify na ta naslov pošlje HTTP POST zahtevek z naslednjimi podatki:

• Sender – telefonska številka osebe, ki je poslala sporočilo,
• Recipient – številka oziroma pošiljatelj, na katerega je bilo sporočilo poslano,
• Message – vsebina prejetega sporočila,
• Time – čas prejema v formatu yyyy-MM-dd HH:mm:ss.

Primer:

{

“Sender”: “+38640123456”,

“Recipient”: “+38631234567”,

“Message”: “TEST”,

“Time”: “2026-05-15 14:32:10”

}

 

Inbound endpoint mora vrniti HTTP status 2xx. Če ga ne vrne, se uporabi enak mehanizem ponovnih poskusov kot pri poročilih o dostavi.

V zahtevek dodajte polje deliveryReportUrl:

{

“deliveryReportUrl”: “https://example.com/delivery-report”

}

 

Lertify bo na ta naslov pošiljal HTTP POST zahtevke s posodobitvami statusa sporočila.

Če deliveryReportUrl ni naveden v zahtevku, sistem uporabi URL, nastavljen pri izbranem pošiljatelju.

Če URL ni nastavljen niti v zahtevku niti pri pošiljatelju, webhook s poročilom o dostavi ne bo poslan.

URL iz posameznega API zahtevka ima tako prednost pred privzeto nastavitvijo pošiljatelja.

Webhook endpoint mora:

• sprejemati HTTP POST zahtevke,
• biti dostopen prek interneta,
• vrniti HTTP status iz skupine 2xx.

Priporočljivo je, da veljaven webhook čim prej potrdi s statusom 2xx, nadaljnjo obdelavo pa po potrebi izvede asinhrono.

Lertify ponovno poskusi poslati webhook.

Zakasnitev se izračuna po formuli:

zakasnitev = poskus² + 1 minuta

Izvede se največ 10 poskusov, interval med poskusi pa se postopoma povečuje. Zadnji poskus se izvede približno 6 ur in 35 minut po prvem neuspešnem pošiljanju.

Vaš endpoint mora biti pripravljen na možnost, da isti dogodek prejme večkrat.

Webhook lahko vsebuje naslednje statuse:

• SENT – sporočilo je bilo predano ponudniku oziroma operaterju,
• DELIVERED – sporočilo je bilo dostavljeno prejemnikovi napravi,
• FAILED – pri pošiljanju ali dostavi je prišlo do napake,
• REJECTED – sporočilo je bilo zavrnjeno pred uspešno oddajo operaterju,
• UNKNOWN – končnega statusa dostave ni bilo mogoče določiti,
• CANCELLED – sporočilo je bilo preklicano pred dostavo.

Status SENT ni končna potrditev dostave.

Da. Status sporočila se lahko skozi njegov življenjski cikel večkrat spremeni.

Primer običajnega poteka:

ACCEPTED → SENT → DELIVERED

Sistem, ki obdeluje webhooke, naj ob vsaki posodobitvi shrani najnovejši status za ustrezni messageId.

Poročilo o dostavi se pošlje za vsakega prejemnika posebej.

Če ste z enim API zahtevkom poslali sporočilo desetim prejemnikom, lahko prejmete ločene statuse za vseh deset sporočil.

Primer payload-a:

{

“messageId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,

“status”: “DELIVERED”

}