OTP Sanly — Node.js / TypeScript SDK

Türkmençe | Русский | English

OTP Sanly (https://otp.sanly.dev) üçin resmi SDK — Türkmenistan üçin SMS & Email OTP tassyklama hyzmaty.

Gurnamak

npm install otp-sanly

Çalt başlamak

import { OtpSanly } from 'otp-sanly'

const sanly = new OtpSanly({ apiKey: process.env.OTP_API_KEY! })

// OTP iber
const sent = await sanly.sendOtp({
  phone: '+99361234567', // SMS üçin diňe Türkmenistan belgileri. Dünýäniň islendik ýerine ibermek üçin `email` ulanyň.
  project: 'Meniň Programmam',
  lang: 'ru', // 'tm' | 'ru' | 'en' — OTP-iň haýsy dilde ugradylmalydygy
})
console.log(sent.otpId, sent.message)

// Ulanyjynyň girizen kodyny barla
const verified = await sanly.verifyOtp({
  phone: '+99361234567',
  code: '123456',
})
if (verified.success) {
  // dowam et — kod dogry
}

Sandbox (synag) rejimi

Dashboard-yňyzda (https://otp.sanly.dev/dashboard/api-keys) sandbox API açary döredip, integrasiýaňyzy mugt synap görüp bilersiňiz — hakyky SMS/email ugradylmaýar. OTP kody göni jogapda gaýtarylýar:

const sent = await sanly.sendOtp({ phone: '+99361234567' })
console.log(sent.code) // diňe sandbox açarlarda bar bolýar

Ýalňyşlyklary dolandyrmak

v2-den başlap, adaty API ýalňyşlyklary (nädogry API açar, nädogry kod, aşa köp synanyşyk) taşlanmaýar (throw edilmeýär) — muňa derek adaty { success:false, status, error } obýekti gaýdyp gelýär, status meýdançasyna görä ýalňyşlygyň görnüşini tapawutlandyryp bolýar:

const result = await sanly.sendOtp({ phone: '+99361234567' })

if (!result.success) {
  if (result.status === 401 || result.status === 403) {
    // API açaryňyz nädogry, işjeň däl ýa-da balans gutaran — konfigurasiýa meselesi
  } else if (result.status === 400) {
    // Ulanyjynyň iberen maglumaty nädogry (telefon/email formaty ýalňyş)
  } else if (result.status === 429) {
    // Aşa köp synanyşyk — birazdan gaýtadan synanyşyň
  } else {
    // Serwer tarapyndaky garaşylmadyk ýalňyşlyk (5xx)
  }
  console.error(result.status, result.error)
  return
}

OtpSanlyError diňe ulgam derejesindäki näsazlyklarda (internet ýok, DNS işlänok, jogap düýbünden JSON däl) taşlanýar — bulary try/catch bilen tutmaly:

import { OtpSanly, OtpSanlyError } from 'otp-sanly'

try {
  const result = await sanly.sendOtp({ phone: '+99361234567' })
  if (!result.success) { /* ýokardaky status barlagyny serediň */ }
} catch (err) {
  if (err instanceof OtpSanlyError) {
    console.error('Ulgam ýalňyşlygy:', err.message)
  }
}

v1-den geçýänler üçin: öňki wersiýada ähli ýalňyşlyklar (şol sanda adaty API ýalňyşlyklary hem) taşlanýardy. Indi diňe ulgam derejesindäki näsazlyklar taşlanýar — API jogaby geleninde bolsa hemişe result.success barlaň.

Doly API resminamasy

Doly API resminamasyny, webhook dokumentasiýasyny we beýleki dillerdäki mysallary şu ýerden görüň: https://otp.sanly.dev/developers

Ýalňyşlyk kodlary we gaýtadan synanyşmak

HTTP statusdan başga, käbir ýalňyşlyklar maşyn kody we gaýtadan synanyşmak maslahaty bilen gelýär:

| Status | Kod | Manysy | Näme etmeli | |---|---|---|---| | 429 | — | Örän köp sorag (rate limit) | Garaşyp gaýtadan synanyşyň | | 429 | DAILY_LIMIT_REACHED | API açaryň günlük OTP çägi doldy (dashboard-da goýulýar) | Dashboard-da çägi ýokarlandyryň ýa-da ertire garaşyň (Aşgabat wagty) | | 503 | NO_DEVICE_AVAILABLE | SMS üçin onlaýn enjam ýok. Töleg we kvota alynmaýar | Görkezilen sekuntdan gaýtadan synanyşyň ýa-da email bilen iberiň | | 403 | — | Açar işjeň däl ýa-da haýyş IP/CIDR, domen ýa-da ýurt çäklendirmesini bozýar | Dashboard-da açar sazlamalaryny barlaň |

const r = await sanly.sendOtp({ phone: '+99361234567' })
if (!r.success && r.errorCode === 'NO_DEVICE_AVAILABLE') {
  await new Promise(res => setTimeout(res, (r.retryAfter ?? 30) * 1000))
  // retry, or fall back to email
} else if (!r.success && r.errorCode === 'DAILY_LIMIT_REACHED') {
  // the key's daily limit is reached
}

Bellik: SMS ugradyp bolmasa, şol OTP üçin kvota ýa-da töleg awtomatik yzyna gaýtarylýar. Açary täzeleseňiz, köne açar ýene 24 sagat işleýär (açar syzan bolsa, derrew öçürmegi saýlaň).

Ygtyýarnama

MIT