API лавлах
Session, Rule, webhook болон тест горимын бүх хүсэлт, хариуны жишээ нэг дор.
Ерөнхий
| Үндсэн хаяг | https://api.2fa.mn |
| Нэвтрэлт | Authorization: Bearer sk_test_... эсвэл Bearer sk_live_... |
| Формат | JSON хүсэлт, JSON хариу (Content-Type: application/json) |
| Цаг | RFC 3339, UTC (2026-12-01T10:00:00Z) |
| Утасны дугаар | 8 оронтой (99112233). Оролтод +976, 976 угтварыг хүлээн авна, хариуд үргэлж 8 оронтой буцна. |
API түлхүүрийн угтвар горимыг тодорхойлно: sk_test_ нь тест, sk_live_ нь бодит горим. Тест API түлхүүр оператор руу хандахгүй, орлого болохгүй. Нууц API түлхүүрийг зөвхөн сервер талд хадгална.
Нэг удаагийн код (Session)
Код үүсгэх
POST/v1/sessions
Шинэ session үүсгэнэ.
| Талбар | Төрөл | Заавал | Тайлбар |
|---|---|---|---|
phone | string | Үгүй | Заасан бол зөвхөн энэ дугаараас ирсэн SMS баталгаажуулна |
metadata | object | Үгүй | Дурын JSON, webhook-д буцаж ирнэ |
{
"phone": "99112233",
"metadata": { "user_id": "u_42" }
}{
"id": "ses_8f3k2m",
"mode": "test",
"code": "482913",
"short_code": "150073",
"sms_uri": "sms:150073?body=482913",
"qr_svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 33 33\" shape-rendering=\"crispEdges\">…</svg>",
"status": "pending",
"phone": "99112233",
"metadata": { "user_id": "u_42" },
"expires_at": "2026-12-01T10:05:00Z",
"created_at": "2026-12-01T10:00:00Z"
}phone заагаагүй бол хариуд "phone": null байна. Session нэг удаа ашиглагдаж, 5 минутын дараа хугацаа нь дуусна.
Кодын төлөв авах
GET/v1/sessions/{id}
Session-ийг буцаана. status нь pending, verified, expired-ийн нэг байна. Баталгаажсан үед verified_phone, verified_at, operator нэмэгдэнэ.
{
"id": "ses_8f3k2m",
"mode": "test",
"code": "482913",
"short_code": "150073",
"sms_uri": "sms:150073?body=482913",
"status": "verified",
"phone": "99112233",
"metadata": { "user_id": "u_42" },
"expires_at": "2026-12-01T10:05:00Z",
"created_at": "2026-12-01T10:00:00Z",
"verified_phone": "99112233",
"verified_at": "2026-12-01T10:00:41Z",
"operator": "unitel"
}Тогтмол текст (Rule)
Тогтмол текст бүртгэх
POST/v1/rules
{ "prefix": "HIHI", "name": "Үйлчилгээ идэвхжүүлэх" }| Талбар | Төрөл | Заавал | Тайлбар |
|---|---|---|---|
prefix | string | Тийм | 2-20 тэмдэгт, латин үсгээр эхэлнэ, үсэг ба цифр, том жижиг үсэг ялгахгүй. Бодит горимд дор хаяж 4 тэмдэгт. 2FA, LOGIN, STOP, HELP, TEST, INFO нөөцөлсөн |
name | string | Үгүй | Хянах самбарт харагдах нэр |
150073 дугаарын угтварыг бүх харилцагч хуваалцдаг тул бодит горимын угтвар өөр харилцагчийн угтварын эхлэл (эсвэл эсрэгээрээ) байж болохгүй. Давхцвал 409 prefix_taken буцаана. Нэг харилцагч бодит горимд 5 хүртэл rule бүртгэх бөгөөд хэтэрвэл 409 rule_limit буцна. Мессеж угтварын эхний үгтэй таарна: HIHI нь HIHI 123-д тохирно, HIHI123-д тохирохгүй.
{
"id": "rul_4n8q1z",
"mode": "test",
"prefix": "HIHI",
"name": "Үйлчилгээ идэвхжүүлэх",
"created_at": "2026-12-01T10:00:00Z"
}Жагсаалт авах
GET/v1/rules
{
"data": [
{
"id": "rul_4n8q1z",
"mode": "test",
"prefix": "HIHI",
"name": "Үйлчилгээ идэвхжүүлэх",
"created_at": "2026-12-01T10:00:00Z"
}
]
}Устгах
DELETE/v1/rules/{id}
Амжилттай бол 204 No Content.
Webhook
Горим бүрд нэг webhook хаяг байна.
Хаяг тохируулах
PUT/v1/webhook
{ "url": "https://example.mn/webhooks/2fa" }{ "url": "https://example.mn/webhooks/2fa", "secret": "whsec_..." }Хаягийг харах
GET/v1/webhook
Одоогийн тохиргоог буцаана.
{ "url": "https://example.mn/webhooks/2fa", "secret": "whsec_..." }Webhook-ийн secret солих
POST/v1/webhook/rotate-secret
Шинэ secret үүсгэнэ. Хуучин secret-ээр signature зурахаа болино.
{ "url": "https://example.mn/webhooks/2fa", "secret": "whsec_..." }Хүргэлтийн түүх
GET/v1/webhook/deliveries
Сүүлийн хүргэлтүүдийг буцаана.
{
"data": [
{
"event_id": "evt_2k9d7x",
"type": "verification.succeeded",
"status": "delivered",
"attempts": 1,
"last_status_code": 200,
"created_at": "2026-12-01T10:00:41Z",
"delivered_at": "2026-12-01T10:00:41Z"
}
]
}status: pending, delivered, failed.
Виджетийн token
Token баталгаажуулах
POST/v1/verifications
Виджетээс ирсэн token-ийг сервер дээрээ нэг удаа ашиглана. Нууц API түлхүүр шаардана. Token-ийг хүсэлтийн биед дамжуулдаг тул URL болон лог руу орохгүй.
{ "token": "eyJhbGciOiJFUzI1NiIs..." }{ "session_id": "ses_8f3k2m", "phone": "99112233", "verified_at": "2026-12-01T10:02:14Z", "mode": "test", "state": "q9Xh2LwP0aT7bV4e" }GET /v1/verifications/{token} хуучин ажиллагаатай хэвээр байна, гэхдээ POST-г ашиглана уу. Алдаа: 400 invalid_token, 404 not_found, 409 token_used, 410 token_expired.
Тест
SMS дуурайх
POST/v1/test/mo
Зөвхөн тест API түлхүүрээр ажиллана. Хэрэглэгчийн 150073 руу илгээсэн SMS-ийг дуурайна. Нэг харилцагч минутад 30 хүртэл дуудна, хэтэрвэл 429 rate_limited. Тест webhook нэг л удаа илгээгдэнэ.
{ "from": "99112233", "text": "482913" }{ "id": "mo_5h2j8w" }Webhook үйл явдлууд
Таны webhook хаяг руу POST хүсэлтээр, X-2FA-Signature: t=<unix секунд>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")> толгойтой ирнэ. Дэлгэрэнгүйг Webhook ба signature хэсгээс үзнэ үү.
{
"id": "evt_2k9d7x",
"type": "verification.succeeded",
"mode": "live",
"created_at": "2026-12-01T10:00:41Z",
"data": {
"session_id": "ses_8f3k2m",
"phone": "99112233",
"operator": "unitel",
"verified_at": "2026-12-01T10:00:41Z",
"metadata": { "user_id": "u_42" }
}
}{
"id": "evt_7c1m3p",
"type": "rule.matched",
"mode": "live",
"created_at": "2026-12-01T10:02:10Z",
"data": {
"rule_id": "rul_4n8q1z",
"prefix": "HIHI",
"phone": "99112233",
"text": "HIHI 5521",
"operator": "unitel",
"received_at": "2026-12-01T10:02:10Z"
}
}{
"id": "evt_9a4b6c",
"type": "session.expired",
"mode": "live",
"created_at": "2026-12-01T10:05:00Z",
"data": { "session_id": "ses_8f3k2m" }
}Алдаа
{ "error": { "code": "not_found", "message": "session not found" } }| HTTP | code |
|---|---|
| 400 | invalid_request, invalid_phone |
| 401 | unauthorized |
| 403 | client_suspended, test_only |
| 404 | not_found |
| 409 | prefix_taken, rule_limit |
| 429 | rate_limited |
Дэлгэрэнгүйг Алдааны кодууд хэсгээс үзнэ үү.
Дараагийн алхам
Энэ хуудас тус болсон уу?