Хөгжүүлэгчид — түншийн API

1. Эхлэх — холболтын хүсэлтээс Live хүртэл

1. Холболтын хүсэлт илгээнэ (байгууллага, хариуцсан хүний имэйл, салбар, төлбөр/И-баримт хэрэгтэй эсэх). Бид 2 ажлын өдөрт хянана.
2. Зөвшөөрөгдвөл имэйлээр урилга очно. Холбоосоор түншийн портал-ын нууц үгээ өөрөө тохируулна. Эхэндээ зөвхөн sandbox нээлттэй.
3. Порталд sandbox түлхүүр (avz_test_...) үүсгэнэ. Түлхүүр зөвхөн нэг удаа харагдах тул тэр даруй серверийнхээ нууц тохиргоонд хадгална. Холболтоо шалгана: GET https://orloo.mn/api/v1/partner/me/.
4. Webhook URL-аа бүртгэнэ (портал эсвэл POST webhooks/). Хариунд ирэх whsec_... secret-ийг хадгална.
5. Sandbox-д бүтэн урсгалаа туршина (10-р хэсэг). Порталын «Live эрх» хуудас аль туршилт хийгдсэнийг ✅-ээр харуулна.
6. «Live эрх хүсэх» товчийг дарна — заавал хийх туршилтууд бүгд ✅ болоход идэвхжинэ. Орлоогийн ажилтан туршилтын дүнг хянаад зөвшөөрөхөд Live орчин нээгдэж, имэйлээр мэдэгдэнэ.
7. Порталын «Live» орчинд avz_live_... түлхүүр, live webhook-ээ үүсгэнэ. Live эрх нээгдэхээс өмнө live түлхүүр 401 буцаана.

Түлхүүр солилцохгүй. API түлхүүр, OAuth client secret, webhook secret бүгдийг та порталд өөрөө үүсгэнэ. Бид тэдгээрийг имэйл, чат, утсаар хэзээ ч илгээхгүй, асуухгүй — бидэнд зөвхөн hash (түлхүүр) эсвэл шифрлэгдсэн хэлбэр (webhook secret) хадгалагдана.

Үндсэн хаяг: https://orloo.mn/api/v1/partner/. Бүх хүсэлт, хариу JSON, UTF-8 форматтай. Цаг ISO 8601 форматаар ирнэ: захиалгын талбарууд Улаанбаатарын цагаар (+08:00), webhook-ийн created_at UTC-ээр. Мөнгөн дүн төгрөгөөр, захиалгын талбаруудад тоон мөр ("5000.00"), payment дотор бүхэл тоо.

2. Нэвтрэлт, орчин

Authorization: Api-Key avz_test_xxxxxxxxxxxxxxxxxxxxxxxx

• Sandbox ба live бүрэн тусгаарлагдсан. avz_test_ түлхүүрээр үүссэн захиалга жинхэнэ хүргэгчид очихгүй, мөнгө хөдлөхгүй, жинхэнэ И-баримт олгогдохгүй. Webhook endpoint ч орчин бүрт тусдаа байна.
• Эрх (scope): orders:read, orders:write, webhooks:manage.
• Хязгаар: анхдагчаар түнш бүрт минутад 120 хүсэлт. Хэтэрвэл 429 буцаана, Retry-After-ийн дараа дахин оролдоно.
• IP allowlist: live түлхүүрт серверийнхээ IP-г бүртгүүлэхийг зөвлөнө.
• OAuth2 (том түншид): POST /oauth/token/ (client credentials) хүсэлтээр token аваад Authorization: Bearer <token> header-ээр дамжуулна.

3. Захиалгын урсгал

1. POST quotes/ — үнийн санал авна. available: false бол тухайн салбар одоогоор захиалга авахгүй. Захиалах товчоо хааж, unavailable_reason-ийг үйлчлүүлэгчид харуулна.
2. POST orders/ — quote_id-тайгаар захиалга илгээнэ, Idempotency-Key header-тэй.
3. Танай гэрээгээр төлбөрийг урьдчилж авдаг бол хариунд payment.status = "unpaid" болон QPay нэхэмжлэх ирнэ. Үйлчлүүлэгч QR уншуулах эсвэл банкны апп руу шилжиж төлнө (5-р хэсэг). Төлбөр төлөгдөөгүй захиалга хүргэгчид харагдахгүй.
4. payment.paid webhook ирнэ. Үйлчлүүлэгчээс И-баримтын төрлийг асууна (6-р хэсэг), мэдээ хүлээн авах эсэхийг асууна (7-р хэсэг).
5. Хүргэлтийн явц бүрт order.<status> webhook ирнэ: created → assigned → picked_up → in_transit → delivered. Бусад төгсгөлийн төлөв: failed, returned, cancelled.

Хүлээн авагчид tracking_url (хувийн мэдээлэлгүй, нийтийн хянах хуудас)-ыг илгээж болно.

4. Захиалга илгээх

POST /api/v1/partner/orders/
Authorization: Api-Key avz_test_...
Idempotency-Key: 6f9c1d2e-SHOP-1001
Content-Type: application/json

{
  "external_order_id": "SHOP-1001",
  "quote_id": "q_5MHN8F1h9UaxH2d0",
  "pickup_name": "Дэлгүүр — Төв салбар",
  "pickup_phone": "70110000",
  "pickup_address": "1-р хороо, 5-р байр",
  "dropoff_name": "Бат Дорж",
  "dropoff_phone": "99112233",
  "dropoff_address": "Баянцагаан, 5-р байр, 2-р орц, 12 тоот",
  "dropoff_lat": 49.03,
  "dropoff_lng": 104.045,
  "package_description": "Хоол: 2 порц",
  "cod_amount": "0",
  "note": "Хаалганы код 1234",
  "terms_acceptance": {
    "version": "2026-11-02",
    "accepted_at": "2026-11-04T09:00:00Z",
    "channel": "partner_web"
  }
}

• Ижил Idempotency-Key-тэй хүсэлтийг давтвал анхны хариу 200-оор ирнэ. Ижил external_order_id-тай өөр хүсэлт ирвэл 409 буцаана. Сүлжээ тасарсан үед түлхүүрээ солилгүй дахин илгээнэ.
• Утасны дугаарыг 8 оронтой болгож хадгална (+976, зай, зураасыг арилгана).
• Танай гэрээгээр журам зөвшөөрөлт заавал бол terms_acceptance шаардлагатай. Журмын текстийг GET terms/-ээс авна.

{
  "tracking_code": "ORLCG7K39SWY",
  "tracking_url": "https://orloo.mn/track/ORLCG7K39SWY/",
  "branch": "ERD",
  "external_order_id": "SHOP-1001",
  "status": "created",
  "is_test": true,
  "pickup_name": "Дэлгүүр — Төв салбар",
  "pickup_phone": "70110000",
  "pickup_address": "1-р хороо, 5-р байр",
  "pickup_lat": null,
  "pickup_lng": null,
  "dropoff_name": "Бат Дорж",
  "dropoff_phone": "99112233",
  "dropoff_address": "Баянцагаан, 5-р байр, 2-р орц, 12 тоот",
  "dropoff_lat": 49.03,
  "dropoff_lng": 104.045,
  "package_description": "Хоол: 2 порц",
  "weight_kg": "0.00",
  "cod_amount": "0.00",
  "delivery_fee": "5000.00",
  "note": "Хаалганы код 1234",
  "metadata": {},
  "extra_fee": "0.00",
  "failure_reason": "",
  "redelivery_of": null,
  "payment_status": "unpaid",
  "payment": {
    "status": "unpaid",
    "amount": 5000,
    "invoice": {
      "invoice_id": "2c0a6e3e-5f0b-4b8d-9a77-0c1f3a9d1e21",
      "qr_text": "0002010102121531279404962794049600022310027138152045734...",
      "qr_image": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51AAA...",
      "short_url": "https://s.qpay.mn/AbCdEf",
      "deeplinks": [
        {
          "name": "Khan bank",
          "description": "Хаан банк",
          "logo": "https://qpay.mn/q/logo/khanbank.png",
          "link": "khanbank://q?qPay_QRcode=0002010102121531279404962794049600022310027138152045734..."
        },
        {
          "name": "qPay wallet",
          "description": "qPay хэтэвч",
          "logo": "https://s3.qpay.mn/p/e9bbdc69-3544-4c2f-aff0-4c292bc094f6/launcher-icon-ios.jpg",
          "link": "qpaywallet://q?qPay_QRcode=0002010102121531279404962794049600022310027138152045734..."
        }
      ],
      "expires_at": "2026-11-04T10:05:00+08:00"
    },
    "ebarimt": null,
    "receipt": null
  },
  "quote_id": "q_5MHN8F1h9UaxH2d0",
  "terms_acceptance": {
    "version": "2026-11-02",
    "accepted_at": "2026-11-04T09:00:00Z",
    "channel": "partner_web"
  },
  "courier": null,
  "events": [
    {
      "status": "created",
      "note": "",
      "lat": null,
      "lng": null,
      "created_at": "2026-11-04T09:00:01+08:00"
    }
  ],
  "created_at": "2026-11-04T09:00:01+08:00",
  "updated_at": "2026-11-04T09:00:01+08:00",
  "delivered_at": null
}

5. QPay төлбөр

Төлбөрийг урьдчилж авдаг түншийн захиалгад payment объект ирнэ (бусад үед null). Захиалга үүсэхэд нэхэмжлэх автоматаар үүснэ. Хэрэв payment.invoice null бол (QPay түр холбогдоогүй) POST orders/{code}/invoice/ хүсэлтээр дахин үүсгэнэ.

payment.status: unpaid (нэхэмжлэх хүлээгдэж байна) · paid · expired (хугацаа дууссан, захиалга цуцлагдана) · refunded.

payment.invoice (зөвхөн unpaid үед):

{
  "invoice_id": "2c0a6e3e-5f0b-4b8d-9a77-0c1f3a9d1e21",
  "qr_text": "0002010102121531279404962794049600022310027138152045734...",
  "qr_image": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51AAA...",
  "short_url": "https://s.qpay.mn/AbCdEf",
  "deeplinks": [
    {
      "name": "Khan bank",
      "description": "Хаан банк",
      "logo": "https://qpay.mn/q/logo/khanbank.png",
      "link": "khanbank://q?qPay_QRcode=0002010102121531279404962794049600022310027138152045734..."
    },
    {
      "name": "qPay wallet",
      "description": "qPay хэтэвч",
      "logo": "https://s3.qpay.mn/p/e9bbdc69-3544-4c2f-aff0-4c292bc094f6/launcher-icon-ios.jpg",
      "link": "qpaywallet://q?qPay_QRcode=0002010102121531279404962794049600022310027138152045734..."
    }
  ],
  "expires_at": "2026-11-04T10:05:00+08:00"
}

Банкны холбоос (payment.invoice.deeplinks)

QPay-ийн буцаасан жагсаалтыг бид өөрчлөхгүйгээр дамжуулна. Элемент бүр яг 4 талбартай:

[
  {
    "name": "Khan bank",
    "description": "Хаан банк",
    "logo": "https://qpay.mn/q/logo/khanbank.png",
    "link": "khanbank://q?qPay_QRcode=0002010102121531279404962794049600022310027138152045734..."
  },
  {
    "name": "qPay wallet",
    "description": "qPay хэтэвч",
    "logo": "https://s3.qpay.mn/p/e9bbdc69-3544-4c2f-aff0-4c292bc094f6/launcher-icon-ios.jpg",
    "link": "qpaywallet://q?qPay_QRcode=0002010102121531279404962794049600022310027138152045734..."
  }
]

• Гар утсанд банк бүрийг logo + description-тэй товч болгож, дарахад link-ийг нээнэ. Аппаас url_launcher / Linking.openURL, вэбээс энгийн <a href> ашиглана.
• Компьютерт qr_image-ийг харуулна. Deeplink компьютер дээр ажиллахгүй.
• Жагсаалтын банкууд, тэдгээрийн дараалал QPay-ээс хамаарч өөрчлөгдөнө. Банкны нэрийг кодонд хатуу бичихгүй, ирсэн жагсаалтыг бүхэлд нь харуулна. Жагсаалт хоосон байж болно, тэр үед QR болон short_url-ийг харуулна.
• Sandbox-д QPay-ийн туршилтын орчны жишээ холбоосууд ирнэ. Тэдгээрээр жинхэнэ төлбөр хийгдэхгүй, харин simulate-payment-ээр төлөгдсөн гэж дуурайна.

Төлөгдсөнийг тогтоох: зөвхөн payment.paid webhook эсвэл GET orders/{code}/-ийн payment.status-аар шийднэ. Үйлчлүүлэгч «төлсөн» гэж дарсан төдийгөөр бүү итгэ. Webhook удааширвал POST orders/{code}/invoice/check/-аар QPay-ээс шууд шалгуулна.

6. И-баримт

1. Төлбөр төлөгдмөгц payment.receipt.status = "awaiting" болно. Баримт автоматаар олгогдохгүй, хугацаагүй хүлээнэ. payment.receipt.prefill нь тухайн утас болон танай түншийн сүүлийн баримтаас бөглөгдсөн утга. Түүгээр маягтаа бөглөж харуулна.

   {
     "status": "paid",
     "amount": 5000,
     "invoice": null,
     "ebarimt": null,
     "receipt": {
       "status": "awaiting",
       "type": "individual",
       "reg_no": "",
       "name": "",
       "prefill": {
         "type": "organization",
         "reg_no": "6543210",
         "name": "Номин Трейд ХХК"
       },
       "change_request": null
     }
   }

2. Үйлчлүүлэгч «Иргэн» эсвэл «Байгууллага»-г сонгож, байгууллага бол регистрээ оруулна. Нэрийг GET ebarimt/organizations/{reg_no}/-ээр шалгаж харуулбал алдаа гарахаас сэргийлнэ (404 — олдсонгүй, 502 — ТТГ-ын систем хариу өгсөнгүй, дахин оролдоно). Дараа нь «И-баримт авах» товч дарна:

   POST /api/v1/partner/orders/{code}/receipt/
   {"type": "individual"}
   {"type": "organization", "reg_no": "6543210"}

3. Олголт асинхрон явагдана (status = "pending"). Бэлэн болмогц payment.receipt_issued webhook ирж, payment.ebarimt бөглөгдөнө:

   {
     "status": "paid",
     "amount": 5000,
     "invoice": null,
     "ebarimt": {
       "id": "000000000000000000000000000000000",
       "lottery": "AB 12345678",
       "qr_data": "1234567890123456789012345678901234567890...",
       "date": "2026-11-04T09:12:30+08:00",
       "amount": 5000,
       "vat": 454.55
     },
     "receipt": {
       "status": "issued",
       "type": "individual",
       "reg_no": "",
       "name": "",
       "prefill": null,
       "change_request": null
     }
   }

Олгосон баримтын төрлийг API-аар солихгүй (409). Үйлчлүүлэгч orloo.mn-д нэвтэрч «Миний баримтууд» хэсгээс солих хүсэлт гаргана. Баримт аваагүй үйлчлүүлэгч мөн тэндээс дараа нь авч болно. Sandbox-д дуураймал баримт олгогдоно (qr_data нь SANDBOX--ээр эхэлнэ).

7. Мэдээ хүлээн авах зөвшөөрөл

Төлбөрийн дараа GET contact-consent/text/-ийн текстийг өөрчлөлгүйгээр харуулж, үйлчлүүлэгчийн шийдвэрийг (зөвшөөрсөн ч, татгалзсан ч) POST orders/{code}/contact-consent/-оор илгээнэ: granted, consented_at (товч дарсан цаг), текстийн checksum, email, phone, channel (partner_app | partner_web), нотолгоонд client_ip, user_agent. Зөвшөөрсөн имэйл рүү хүргэлтийн явцын мэдээлэл очно, имэйл бүр «Бүртгэлээс гарах» холбоостой.

8. Webhook

Бид таны https:// URL руу POST хүсэлт илгээнэ, Content-Type: application/json.

{
  "id": "3f1c2a9e-8b7d-4c1e-9f0a-2d6b5e4c3a21",
  "type": "payment.receipt_issued",
  "created_at": "2026-11-04T01:12:31.123456+00:00",
  "livemode": true,
  "data": {
    "tracking_code": "ORLCG7K39SWY",
    "tracking_url": "https://orloo.mn/track/ORLCG7K39SWY/",
    "branch": "ERD",
    "external_order_id": "SHOP-1001",
    "status": "created",
    "is_test": false,
    "pickup_name": "Дэлгүүр — Төв салбар",
    "pickup_phone": "70110000",
    "pickup_address": "1-р хороо, 5-р байр",
    "pickup_lat": null,
    "pickup_lng": null,
    "dropoff_name": "Бат Дорж",
    "dropoff_phone": "99112233",
    "dropoff_address": "Баянцагаан, 5-р байр, 2-р орц, 12 тоот",
    "dropoff_lat": 49.03,
    "dropoff_lng": 104.045,
    "package_description": "Хоол: 2 порц",
    "weight_kg": "0.00",
    "cod_amount": "0.00",
    "delivery_fee": "5000.00",
    "note": "Хаалганы код 1234",
    "metadata": {},
    "extra_fee": "0.00",
    "failure_reason": "",
    "redelivery_of": null,
    "payment_status": "paid",
    "payment": {
      "status": "paid",
      "amount": 5000,
      "invoice": null,
      "ebarimt": {
        "id": "000000000000000000000000000000000",
        "lottery": "AB 12345678",
        "qr_data": "1234567890123456789012345678901234567890...",
        "date": "2026-11-04T09:12:30+08:00",
        "amount": 5000,
        "vat": 454.55
      },
      "receipt": {
        "status": "issued",
        "type": "individual",
        "reg_no": "",
        "name": "",
        "prefill": null,
        "change_request": null
      }
    },
    "quote_id": "q_5MHN8F1h9UaxH2d0",
    "terms_acceptance": {
      "version": "2026-11-02",
      "accepted_at": "2026-11-04T09:00:00Z",
      "channel": "partner_web"
    },
    "courier": null,
    "events": [
      {
        "status": "created",
        "note": "",
        "lat": null,
        "lng": null,
        "created_at": "2026-11-04T09:00:01+08:00"
      }
    ],
    "created_at": "2026-11-04T09:00:01+08:00",
    "updated_at": "2026-11-04T09:00:01+08:00",
    "delivered_at": null
  }
}

Гарын үсэг шалгах

• Ирсэн түүхий байтаар шалгана. JSON-ийг задлаад дахин serialize хийвэл гарын үсэг таарахгүй.
• Түлхүүр нь whsec_... мөр бүхэлдээ (UTF-8). Base64-ээр задлахгүй.
• Timestamp 300 секундээс хуучин бол татгалзана. Шалгалт амжилтгүй бол 401 буцаана.

# Python
import hashlib, hmac, time
def verify(secret, timestamp, body: bytes, signature):
    expected = "sha256=" + hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(timestamp)) < 300 and hmac.compare_digest(expected, signature)

// Node.js (Express: app.post(path, express.raw({type: "application/json"}), ...))
const crypto = require("crypto");
function verify(secret, timestamp, rawBody, signature) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(signature || "");
  return Math.abs(Date.now() / 1000 - Number(timestamp)) < 300 && a.length === b.length && crypto.timingSafeEqual(a, b);
}

// PHP
$raw = file_get_contents("php://input");
$ts = $_SERVER["HTTP_X_AVZAGA_TIMESTAMP"];
$expected = "sha256=" . hash_hmac("sha256", $ts . "." . $raw, $secret);
$ok = abs(time() - (int)$ts) < 300 && hash_equals($expected, $_SERVER["HTTP_X_AVZAGA_SIGNATURE"] ?? "");

Хариу, дахин илгээлт

• 10 секундийн дотор 2xx буцаана. Удаан ажлыг дараалалд оруулаад шууд хариу өгнө.
• Бусад хариу (redirect, 401, 5xx, timeout) ирвэл 1 мин, 5 мин, 30 мин, 2 цаг, 6 цагийн дараа дахин илгээнэ. Портал дээр илгээлт бүрийн түүх харагдах ба гараар дахин илгээж болно.
• Event-үүдийн дараалал баталгаатай биш. data.status болон created_at-аар эсвэл GET orders/{code}/-ээр эцсийн төлөвийг тогтооно.

9. Алдааны хариу

{
  "detail": "Одоогоор хүргэлт хүлээн авах боломжгүй байна.",
  "code": "service_unavailable"
}

10. Sandbox туршилт

avz_test_ түлхүүрээр нэг захиалгын бүтэн урсгалыг туршина:

1. POST quotes/ → POST orders/. Хариунд payment.invoice.deeplinks ирнэ.
2. POST orders/{code}/simulate-payment/ — төлбөр төлөгдсөнийг дуурайна → payment.paid webhook ирнэ.
3. POST orders/{code}/receipt/ → payment.receipt_issued webhook ирнэ (дуураймал баримт).
4. POST orders/{code}/simulate/ {"status": "assigned"}, дараа нь picked_up, in_transit, delivered — төлөв бүрт order.* webhook ирнэ.
5. Портал → Webhook → «Туршилт илгээх» товчоор ping event илгээж гарын үсгийн шалгалтаа туршина.

Live эрх хүсэхэд заавал хийх туршилт: sandbox түлхүүрээр API дуудсан, захиалга үүсгэсэн, «Хүргэгдсэн» хүртэл явуулсан, webhook-ийг 2xx-ээр хүлээн авсан. Төлбөр урьдчилж авдаг бол simulate-payment, И-баримтын төрөл сонгуулдаг бол receipt/ мөн заавал. Цуцлалт туршихыг зөвлөнө.

Sandbox-д бүх салбар нээлттэй. Жинхэнэ хүний утас, нэр, регистр бүү ашигла.

11. Аюулгүй байдал (заавал мөрдөнө)

Төлбөр, И-баримт (регистр, нэр, сугалаа, QR), хүлээн авагчийн утас, хаяг нь нууц мэдээлэл.

• Зөвхөн HTTPS (TLS 1.2/1.3). TLS гэрчилгээний шалгалтыг хэзээ ч унтраахгүй (verify=False, rejectUnauthorized: false, CURLOPT_SSL_VERIFYPEER=0 хориотой).
• Түлхүүр, client secret, webhook secret зөвхөн танай серверт (орчны хувьсагч, secret manager) байна. Гар утасны апп, браузерын JavaScript, git, лог, чатад хэзээ ч оруулахгүй. Урсгал: апп → танай сервер → Орлоо.
• Түлхүүрийг зөвхөн Authorization header-ээр илгээнэ, URL-д хэзээ ч оруулахгүй.
• Webhook URL заавал https://, нийтэд хүрэх хаяг байна. http хаяг руу бид мэдэгдэл илгээхгүй. Гарын үсэг шалгаагүй webhook-ийг боловсруулахгүй.
• И-баримтын QR, сугалаа, регистр, QPay-ийн QR-ийг зөвхөн тухайн захиалгын нэвтэрсэн үйлчлүүлэгчид харуулна. Лог, алдааны мэдээнд (Sentry г.м.) бүтнээр нь бичихгүй.
• Бидний хариу Cache-Control: no-store, private толгойтой ирнэ. Өөрийн прокси, CDN-дээ ч кэшлэхгүй.
• Түлхүүр алдагдсан гэж сэжиглэвэл портал дээрээс тэр даруй хүчингүй болгож шинээр үүсгээд, бидэнд мэдэгдэнэ. Бид түлхүүрийг hash-аар, webhook secret-ийг шифрлэж хадгалдаг тул сэргээж өгөх боломжгүй. Орлоогийн ажилтан таны түлхүүр, secret-ийг хэзээ ч асуухгүй.

Аюулгүй байдлын асуудал илэрвэл support@orloo.mn хаягаар, гарчигтаа «SECURITY» гэж бичээд мэдэгдэнэ.

12. Endpoint жагсаалт

Бүгд /api/v1/partner/-ээр эхэлнэ. Талбарын дэлгэрэнгүйг Swagger-ээс үзнэ.