SMS API – HTTPS integráció és példák

Milyen folyamatokhoz használható?

Rendelési állapotváltozásokhoz, időpont-emlékeztetőkhöz vagy szolgáltatási értesítésekhez a saját alkalmazása kezdeményezheti az API-hívást. Az esemény felismerését, az időzítést és a címzett kiválasztását az Ön rendszere kezeli; a BitSMS az üzenet továbbítását és a státusz lekérdezését biztosítja. Az alábbi útmutató nem feltételez kész webáruházmodult vagy beépített időzítőt.

1. Hozzáférés és IP-engedélyezés

Az integráció előtt adja meg a küldő szerver nyilvános IP-címét vagy IP-címeit a BitSMS ügyfélszolgálatának. Az elérést ezekre a címekre engedélyezzük. A felhasználónevet és jelszót szintén az ügyfélszolgálattól kapja meg.

Nem engedélyezett IP-cím vagy hibás belépési adatok esetén az API NO ACCESS választ ad. Ilyenkor a kimenő IP-címet és a hozzáférési adatokat ellenőrizze; a kérés változatlan ismétlése nem oldja meg az engedélyezési hibát.

A hozzáférési adatokat kizárólag a saját szerverén tárolja. Ne tegye őket böngészőben futó JavaScriptbe, nyilvános forráskódba vagy naplóba. Az alábbi példák helyőrzőket tartalmaznak, nem működő hozzáféréseket.

2. SMS küldése POST-kéréssel

A küldési végpont pontos HTTPS-címét az ügyfélszolgálat adja meg a hozzáférés beállításakor. A példákban az API_HOST, a KULDESI_VEGPONT és a STATUSZ_VEGPONT helyőrzők szerepelnek, nem tényleges címek. A példa HTTPS POST-kérést és application/x-www-form-urlencoded törzset használ. A json=1 paraméter a válasz JSON-formátumát kéri; nem azt jelenti, hogy a kérés törzsét JSON-ként kell elküldeni.

Paraméter	Tartalom
`username`	Az ügyfélszolgálattól kapott felhasználónév. Kötelező.
`password`	A hozzáféréshez tartozó jelszó. Kötelező.
`receiver`	Nemzetközi telefonszám, kizárólag számjegyekkel, „+” jel és szóköz nélkül. Szövegként kezelje. Kötelező.
`text`	Az SMS szövege. Kötelező.
`charset`	`7bit` vagy `unicode`. A példában kifejezetten megadjuk a kívánt kódolást.

Példa kérés

Az alábbi minta nem fut le ezen az oldalon. A helyőrzőket a saját, biztonságosan kezelt adataival és engedélyezett tesztcímzettel helyettesítse.

POST KULDESI_VEGPONT?json=1 HTTP/1.1
Host: API_HOST
Content-Type: application/x-www-form-urlencoded

username=USERNAME&password=PASSWORD&receiver=RECEIVER_NUMBER&text=Teszt%20uzenet&charset=7bit

A paraméterértékeket URL-kódolni kell. A rendszer GET-kérést is támogat, de a POST-minta elkerüli, hogy a jelszó az URL lekérdezési részébe kerüljön.

Példa JSON-válasz

{"messages":["4fd88ad0-b945-11e5-9078-00163e536649"]}

Mentse el a visszakapott üzenetazonosítókat. Az azonosító önmagában nem bizonyítja a kézbesítést; ehhez külön státuszlekérdezés szükséges. A válasz feldolgozásakor ellenőrizze, hogy érvényes JSON-t és a várt messages mezőt kapta-e.

3. Kézbesítési státusz lekérdezése

A státusz legkorábban az SMS küldése után 10 másodperccel kérdezhető le az ügyfélszolgálattól kapott státuszvégponton. A dokumentált egyedi lekérdezéshez a username, password és id mezők szükségesek. GET és URL-kódolt POST használható.

POST STATUSZ_VEGPONT HTTP/1.1
Host: API_HOST
Content-Type: application/x-www-form-urlencoded

username=USERNAME&password=PASSWORD&id=4fd88ad0-b945-11e5-9078-00163e536649

Az alábbi rövidített válasz a státusz és az üzenetazonosító kapcsolatát szemlélteti:

{"messages":[{"status":"delivered","message_id":"4fd88ad0-b945-11e5-9078-00163e536649"}]}

Státusz	Jelentés
`started`	Az üzenet átadása a mobilszolgáltatónak elkezdődött.
`sent`	A mobilszolgáltató átvette az üzenetet. Ez még nem kézbesítési igazolás.
`buffered`	Az első kézbesítés nem sikerült; a hálózat újra próbálkozik, például kikapcsolt telefon esetén.
`delivered`	Az üzenet kézbesült. Ez nem olvasási visszaigazolás.
`undeliverable`, `rejected`	Az üzenet nem kézbesíthető, például hibás vagy nem létező telefonszám miatt.
`expired`, `deleted`	A szolgáltatói várakozási idő alatt nem sikerült kézbesíteni az üzenetet, a hálózat eldobta azt.

4. Karakterkészlet, hosszú SMS és számlázás

Kódolás	Egy SMS	Összefűzött üzenet egy része
7bit	Legfeljebb 160 karakter	Legfeljebb 153 karakter
Unicode	Legfeljebb 70 karakter	Legfeljebb 67 karakter

A hosszú szöveget a rendszer automatikusan SMS-részekre bontja; ezeket a fogadó készülék összefűzheti. Ahány SMS-rész keletkezik, annyi darabot számlázunk. Például egy 161 egyszerű, 7 bites karakterből álló szöveg két SMS-rész, egy 71 szokásos magyar Unicode-betűből álló szöveg szintén két SMS-rész lehet. A karakterek kódolása befolyásolja a rendelkezésre álló helyet.

A 7bit beállításnál a magyar ékezetes karaktereket a szolgáltatás átalakítja, a nem támogatott karaktereket eltávolíthatja. Ha fontos az ékezetek megtartása, használjon Unicode-kódolást. A pontos szöveget próbálja ki tesztküldéssel; különösen emoji vagy speciális karakter esetén ne pusztán a látható betűk számából becsülje a díjat.

A fogadó készülék is korlátozhatja az összefűzést: a műszaki leírás szerint három SMS-rész felett egyes készülékek eldobhatják az üzenetet. Üzleti értesítésnél ezért érdemes rövid, egyértelmű szöveget használni.

5. Hibakezelés az integrációban

Állítson be kapcsolódási és válaszidő-korlátot a saját HTTP-kliensében.
A hálózati hibát, a NO ACCESS választ és az érvénytelen JSON-t kezelje külön.
Ha a küldési kérés után megszakad a kapcsolat, a válasz hiánya nem bizonyítja, hogy nem indult el a küldés. A vak újrapróbálkozás duplikált SMS-t okozhat.
A kapott azonosítót kapcsolja össze a saját üzleti eseményével, és státuszlekérdezéssel kövesse az eredményt.
A naplókból hagyja ki a jelszót, és csak a szükséges címzett- és üzenetadatokat őrizze meg.

Az útmutató az egyedi üzenetazonosítós lekérdezést mutatja be. Tömeges státuszlekérdezés, más kérésformátum vagy további integrációs igény esetén egyeztessen az ügyfélszolgálattal.

Feladószám és kipróbálás

Az üzenet feladója dedikált vagy osztott telefonszám lehet. A dedikált csomag havi nettó 24 990 Ft, amely a One, Yettel és Telekom hálózatában egy-egy számot tartalmaz. Az SMS-díjakat és a teljes egészében leforgalmazható havi nettó 18 000 Ft szolgáltatási díjat az áraknál találja.

Az ingyenes próba 10 SMS-t és 1 hét hozzáférést tartalmaz. A próba végén a hozzáférés megszűnik, automatikus fizetős folytatás nincs. Az API-próbához az IP-engedélyezést és a hozzáférést előre egyeztetjük.

Ingyenes próbát kérek