Нэг удаагийн код (Session)

Session нь нэг удаагийн баталгаажуулалтыг илэрхийлнэ. Таны сервер session үүсгэхэд 2fa.mn 6 оронтой код олгоно. Хэрэглэгч уг кодыг 150073 дугаарт илгээмэгц session баталгаажиж, таны серверт webhook мэдэгдэл ирнэ.

Бүртгүүлэх, нэвтрэх, гүйлгээг баталгаажуулах, үйлчилгээг идэвхжүүлэх зэрэгт ашиглана.

Код үүсгэх

curl -X POST https://api.2fa.mn/v1/sessions \
  -H "Authorization: Bearer $TWOFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "99112233", "metadata": { "user_id": "u_42" } }'

const res = await fetch('https://api.2fa.mn/v1/sessions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TWOFA_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ phone: '99112233', metadata: { user_id: 'u_42' } }),
});
const session = await res.json(); // session.sms_uri, session.code

body := strings.NewReader(`{"phone": "99112233", "metadata": {"user_id": "u_42"}}`)
req, _ := http.NewRequest("POST", "https://api.2fa.mn/v1/sessions", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("TWOFA_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

<?php
$ch = curl_init('https://api.2fa.mn/v1/sessions');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('TWOFA_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['phone' => '99112233', 'metadata' => ['user_id' => 'u_42']]),
]);
$session = json_decode(curl_exec($ch), true);

import os, requests

res = requests.post(
    "https://api.2fa.mn/v1/sessions",
    headers={"Authorization": f"Bearer {os.environ['TWOFA_KEY']}"},
    json={"phone": "99112233", "metadata": {"user_id": "u_42"}},
)
session = res.json()  # session["sms_uri"], session["code"]

Хариу 201 Created:

{
  "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"
}

qr_svg талбар

qr_svg нь sms_uri-г агуулсан QR кодын бүрэн SVG дүрслэл юм. Зөвхөн pending төлөвтэй session-д буцаж ирнэ. Баталгаажсан эсвэл хугацаа нь дууссан session-ийн хариунд энэ талбар байхгүй.

SVG-г 2fa.mn тогтмол тэмдэгтүүдээс үүсгэдэг тул HTML хуудсанд шууд (inline) оруулж болно.

phone талбарыг заах эсэх

Дугаарыг заасан үед. Хэрэглэгч дугаараа өмнө нь оруулсан бол, жишээлбэл бүртгэлийн маягтад, phone талбарыг дамжуулна. Өөр дугаараас илгээсэн SMS тухайн session-ийг баталгаажуулахгүй. Session pending хэвээр үлдэж, зөв дугаараас SMS ирэхийг хүлээнэ.

Дугаарыг заагаагүй үед. Хэрэглэгчээс дугаар урьдчилан асуулгүйгээр SMS илгээх товчийг харуулж болно. Кодыг хамгийн түрүүнд илгээсэн дугаар session-ийг баталгаажуулна. SMS илгээсэн хэрэглэгчийн дугаарыг webhook-ийн phone талбараас авна. Ингэснээр бүртгэлийн үйл явц богиносно.

Хэрэглэгчид харуулах

Хэрэглэгчид SMS-ийн үнийг урьдчилан харуулж, sms_uri-тай холбосон товч байрлуулна. Утаснаас товчийг дарахад SMS апп нээгдэж, 150073 дугаар болон код автоматаар бөглөгдөнө. Дараа нь хэрэглэгч SMS аппын илгээх товчийг дарж мессежээ илгээнэ.

<p>Нэг SMS: 150₮</p>
<a href="sms:150073?body=482913">SMS илгээх</a>

SMS товч эсвэл QR код

• Утаснаас: sms_uri-тай холбосон SMS илгээх товчийг харуулна.
• Компьютероос: qr_svg-г харуулна. Хэрэглэгч утасныхаа камераар QR кодыг уншуулахад SMS апп дугаар, кодтойгоо нээгдэнэ (утас, камерын аппаас хамаарна). SMS-ийг хэрэглэгч өөрөө илгээнэ. Код болон 150073 дугаарыг текстээр мөн харуулж, гараар илгээх боломж олгоно.

Аль ч хувилбарт SMS-ийн үнийг товч эсвэл QR кодын өмнө харуулна. Баталгаажмагц SMS илгээх товч болон QR кодыг нууна.

<p>Нэг SMS: 150₮</p>
<div class="qr">
  <!-- session.qr_svg -->
</div>
<p>Утасныхаа камераар QR кодыг уншуулна уу.</p>

SVG дүрслэлд width болон height атрибут байхгүй тул хэмжээг нь агуулж буй элементийн CSS-ээр тохируулна. Жишээ нь:

.qr svg {
  width: 200px;
  height: 200px;
}

Төлөв

Session-ийг зөвхөн нэг удаа ашиглана. Баталгаажсан эсвэл хугацаа нь дууссан session-д дахин SMS ирсэн ч төлөв өөрчлөгдөхгүй. Хэрэглэгч дахин оролдох бол шинэ session үүсгэнэ.

Төлөв шалгах

Үндсэн арга нь webhook ашиглах юм. Хөтөч дээр session-ийн төлөв харуулах шаардлагатай бол өөрийн серверээр дамжуулан GET /v1/sessions/{id} хүсэлт илгээнэ.

curl https://api.2fa.mn/v1/sessions/ses_8f3k2m \
  -H "Authorization: Bearer sk_test_..."

Баталгаажсан session-ийн хариунд 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"
}

Алдаа

Бүх алдааны кодын тайлбарыг Алдааны кодууд хэсгээс үзнэ үү.

Webhook

Session баталгаажихад verification.succeeded, хугацаа нь дуусахад session.expired үйл явдал ирнэ. session.expired-ийн data-д зөвхөн session_id байна.

{
  "id": "evt_2k9d7x",
  "type": "verification.succeeded",
  "mode": "test",
  "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" }
  }
}

Webhook-ийн гарын үсгийг (signature) хэрхэн шалгахыг Webhook ба signature хэсгээс үзнэ үү.