API заавар

Node.js SDK

Node.js дээр WeSend API-г албан ёсны @wesend/node багцаар дуудна.

SDK нь энэ API-ийн хаяг бүрийг төрөлтэй (typed) функц болгон өгнө. Нэмэлт хамааралгүй, TypeScript болон JavaScript-д ажиллах бөгөөд амжилтгүй хүсэлтийг мессеж давхар илгээхгүйгээр дахин оролдоно.

npm install @wesend/node

Node.js 20 буюу түүнээс шинэ хувилбар шаардана. ESM (import) болон CommonJS (require) хоёуланд нь ажиллана.

Эхлэх

API түлхүүрээ WESEND_API_KEY орчны хувьсагчид хадгална. new WeSend() гэж түлхүүргүй дуудвал клиент түлхүүрийг тэндээс өөрөө уншина.

Node.js

import { WeSend } from "@wesend/node"

const wesend = new WeSend(process.env.WESEND_API_KEY)

const message = await wesend.sms.send({
  to: "99112233",
  text: "Tanii zahialga batalgaajlaa. #1042",
})

console.log(message.id, message.status, message.balance)

SDK-г зөвхөн серверээсээ ашигла. Браузер, гар утасны апп доторх кодонд орсон түлхүүрийг хэн ч уншиж, таны кредитээр илгээж чадна.

Функцууд

Функц бүр нэг хаягийг дуудаж, хариуг нь буцаана. Талбарын нэр хаягийн хуудсууд дээрхтэй яг адил (from_name, batch_id, created_at); зөвхөн SDK-ийн өөрийн тохиргоо camelCase (idempotencyKey, maxRetries) байна.

Функц	Хаяг
wesend.sms.send(params)	POST /v1/sms
wesend.sms.sendBulk(params)	POST /v1/sms/bulk
wesend.email.send(params)	POST /v1/email
wesend.email.sendBulk(params)	POST /v1/email/bulk
wesend.verify.create(params)	POST /v1/verify
wesend.verify.check(id, { code })	POST /v1/verify/{id}/check
wesend.verify.get(id)	GET /v1/verify/{id}
wesend.messages.get(id)	GET /v1/messages/{id}
wesend.batches.get(id)	GET /v1/batches/{id}
wesend.balance.get()	GET /v1/balance
wesend.pricing.get()	GET /v1/pricing

Хаяг бүрийн хуудсан дахь хүсэлтийн жишээнүүдийн Node.js таб SDK-ийн дуудлагыг харуулна.

Алдаа

Амжилтгүй хүсэлт WeSendError алдаа шиднэ. Түүний code-оор шалгана: кодууд нь «Алдаа» хуудсанд жагсаагдсан. message-ийг зөвхөн бүртгэлд ашиглана.

Node.js

import { WeSend, WeSendError } from "@wesend/node"

try {
  await wesend.sms.send({ to: "99112233", text: "Sain baina uu" })
} catch (error) {
  if (!(error instanceof WeSendError)) throw error

  if (error.code === "insufficient_credits") {
    console.log(`Need ${error.required} credits, have ${error.balance}`)
  } else {
    console.error(error.status, error.code, error.message)
  }
}

Талбар	Утга
code	Машинд уншигдах код: `invalid_request`, `insufficient_credits` гэх мэт.
status	HTTP статус код. Хариу огт ирээгүй бол `null`.
message	Англи хэл дээрх тайлбар.
retryAfter	Дахин оролдохоос өмнө хүлээх секунд (`Retry-After` толгойноос). Байхгүй бол `null`.
balance, required	`insufficient_credits` алдаанд: байгаа болон шаардлагатай кредит.
attempts_remaining	`invalid_code` алдаанд: үлдсэн оролдлогын тоо.
invalid	Багц илгээлтийн `invalid_request` алдаанд: буруу хүлээн авагчид (50 хүртэл).
id	`provider_failed` алдаанд: амжилтгүй мессежийн дугаар.

verify.check нь код зөв бол амжилттай буцна. Буруу код invalid_code алдаа шидэх бөгөөд үлдсэн оролдлого attempts_remaining-д байна.
Гурван код API-аас биш, SDK-аас өөрөөс нь гарна: timeout ба connection_error (хариу ирээгүй тул status нь null), мөн unexpected_response (хариу WeSend API-аас ирээгүй).

Давталт ба давхар илгээхээс сэргийлэх

Мессеж давхар илгээгдэх эрсдэлгүй үед SDK амжилтгүй хүсэлтийг өөрөө дахин оролдоно: дээд тал нь 2 удаа.

Алдаа	SDK юу хийдэг вэ
`429 rate_limited`	`Retry-After` секунд хүлээгээд дахин илгээнэ. 10 секундээс урт хүлээлт бол алдааг шиднэ.
Сүлжээний тасалдал, хугацаа хэтрэх, `5xx`	Унших хүсэлт болон илгээх дөрвөн функцэд дахин илгээнэ.
`502 provider_failed`	Дахин илгээнэ: оператор мессежийг хүлээн аваагүй, кредит буцсан.
Бусад `4xx`	Шууд шиднэ. Эхлээд хүсэлтээ засна.

Илгээх дөрвөн функц (sms.send, sms.sendBulk, email.send, email.sendBulk) үргэлж Idempotency-Key-тэй явна: SDK дуудлага бүрд түлхүүр үүсгэдэг тул түүний давталт хэзээ ч давхар илгээхгүй. Таны код өөрөө хоёр удаа ажиллах үед ч (жишээ нь дарааллын ажил дахин ажиллах) хамгаалагдахын тулд өөрийн түлхүүрээ дамжуулна.

Node.js

await wesend.sms.send(
  { to: "99112233", text: "Tanii zahialga batalgaajlaa. #1042" },
  { idempotencyKey: "order-1042-confirmation" },
)

Өөрийн түлхүүртэй үед 502 provider_failed-ийг дахин оролдохгүй: тэр түлхүүрээр давтвал мөн адил алдаа буцна. Шинэ түлхүүрээр дахин илгээнэ.
verify.create, verify.check нь Idempotency-Key авдаггүй тул сүлжээний тасалдал, 5xx-ийн дараа дахин оролдохгүй.

Тохиргоо

Node.js

const wesend = new WeSend(process.env.WESEND_API_KEY, {
  timeout: 30_000,
  maxRetries: 2,
})

Тохиргоо	Анхдагч	Тайлбар
timeout	30000	Нэг оролдлогын дээд хугацаа, миллисекундээр.
maxRetries	2	Амжилтгүй хүсэлтийг хэдэн удаа дахин оролдох. `0` бол давталтгүй.
baseUrl	https://api.wesend.mn/v1	Хүсэлт илгээх хаяг.
fetch	глобал `fetch`	Глобал `fetch`-ийн оронд ашиглах функц.