portal.mnDEVELOPER DOCS
API v1Portal.mn
ХАРИЛЦАГЧИЙН ГАРЫН АВЛАГА

POS & Kiosk
Gateway

Portal.mn тасалбарын системийг өөрийн киоск болон мобайл аппликейшнд холбох API заавар.

API баримт бичигШинэчилсэн: 2025Монгол хэлээр

Өөртөө үйлчлэх тасалбар

Харилцагчийн киоск дээр Portal.mn тасалбарыг борлуулна.

Нэгдсэн API

Эвент, тасалбар, invoice болон төлбөрийн урсгалыг холбох.

01 — АЮУЛГҮЙ БАЙДАЛ

Баталгаажуулалт

Portal.mn баг харилцагчид clientName, secretKey болон checksum үүсгэх нууц SPKEY олгоно. Эдгээр утгыг нууцлан хадгалж, client талын эх код эсвэл олон нийтэд ил API-д бүү байршуул.

Хүсэлт бүрд p-client-checksum болон p-client-service header-ийг илгээнэ. Checksum нь clientName, secretKey, expiresAt утгыг AES-256-CBC ашиглан шифрлэнэ.

Хугацааны хязгаар

expiresAt нь epoch миллисекундээрх тоон утга байна. Одоогийн цаг дээр яг 2 минут нэмнэ. Хугацаа хэтэрсэн checksum эсвэл буруу төрөлтэй утгыг сервер 400 алдаагаар татгалзана.

ТүлхүүрSHA-256(SPKEY)
ШифрлэлAES-256-CBC
IVСанамсаргүй 16 байт
Буцаах форматIV hex : ciphertext hex
Node.js · TypeScript
import * as crypto from 'crypto'

export function encrypt(clientName, secretKey, SPKEY) {
  const key = crypto.createHash('sha256').update(SPKEY).digest()
  const iv = crypto.randomBytes(16)
  const cipher = crypto.createCipheriv('aes-256-cbc', key, iv)
  const payload = JSON.stringify({
    clientName,
    secretKey,
    expiresAt: Date.now() + 2 * 60 * 1000,
  })
  let encrypted = cipher.update(payload, 'utf8', 'hex')
  encrypted += cipher.final('hex')
  return iv.toString('hex') + ':' + encrypted
}
Java
long expiresAt = System.currentTimeMillis() + 2 * 60 * 1000;
String json = String.format(
  "{\"clientName\":\"%s\",\"secretKey\":\"%s\",\"expiresAt\":%d}",
  clientName, secretKey, expiresAt
);
Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
cipher.init(Cipher.ENCRYPT_MODE, key, new IvParameterSpec(ivBytes));
byte[] encrypted = cipher.doFinal(json.getBytes(StandardCharsets.UTF_8));
return bytesToHex(ivBytes) + ":" + bytesToHex(encrypted);
02 — API ЛАВЛАХ

Үйлчилгээний төрлүүд

p-client-service header-д хүсэлтийн зорилгыг заасан кодыг илгээнэ.

03 — ОРЧИН

Серверийн хаягууд

Хөгжүүлэлт, туршилтаа Stage орчинд хийж, production-д гарахдаа үндсэн серверийн хаягийг ашиглана.

PRODUCTION

Үндсэн сервер

https://client-ap.portal.mn/v1
STAGE

Туршилтын сервер

https://st-client.portal.mn/v1
04 — ЭВЕНТҮҮД

Эвентүүд авах

GET/pos-kiosk/list

Зарах боломжтой эвентүүд

Query: eventId (заавал биш), limit (1–20), page (заавал). limit нь 20-оос их байж болохгүй.

GET/pos-kiosk/detail/{eventId}

Эвентийн дэлгэрэнгүй

Эвентийн тасалбарын template, суудлын тохиргоо зэрэг мэдээллийг буцаана.

i
Checkout v2 эвентийн эрх

v2 эвент харах, detail авах болон invoice үүсгэхэд Portal.mn-ээс “Kiosk v2” эрх нээлгэсэн байх шаардлагатай. Talon-оор зарагддаг эвент киоск борлуулалтад дэмжигдэхгүй. v2 эвентийн буцаалт боломжгүй.

05 — SEAT PICKER

Суудал сонголт

Суудлын зураглал, боломжит суудлын бодит цагийн төлөвийг Portal.mn-ийн Seat Picker WebView харуулна. Апп дотроо суудлын зураглалыг дахин зурах шаардлагагүй.

PRODUCTIONhttps://portal.mn/seat-picker/{eventId}
STAGINGhttps://stage.portal.mn/seat-picker/{eventId}

WebView тохиргоо

  • JavaScript идэвхтэй байх (JavaScriptMode.unrestricted).
  • Зураг томруулах боломжийг идэвхжүүлэх.
  • Дэвсгэр өнгө: #1E1E1E.
  • Ачаалалт 100% болмогц удирдлага, худалдан авах товчийг харуулна.

URL-аас сонголтыг унших

Хэрэглэгч суудлаа сонгох бүрд WebView-ийн URL seats query параметрээр шинэчлэгдэнэ. URL өөрчлөлтийг сонсож утгыг таслалаар салган авна; параметр хоосон бол сонголт хийгдээгүй гэж үзнэ.

URL contract
https://portal.mn/seat-picker/{eventId}?seats=SF2-R1-s9,SF2-R1-s10\n\n// -> ['SF2-R1-s9', 'SF2-R1-s10']
УгтварУтгаЖишээ
FДавхар (Floor)F2 → 2-р давхар
VVIP хэсэгV1 → VIP 1
T / tШирээ (Table)T4 → 4-р ширээ
GХаалга (Gate)G1 → 1-р хаалга
ZБүс (Zone)Z2 → 2-р бүс
SСектор (Sector)SF2 → F2 сектор
RЭгнээ (Row)R1 → 1-р эгнээ
sСуудал (Seat)s9 → 9-р суудал
i
Template-тэй холбох

Сонгосон суудлын код аль template-ийн seatIds-д байгааг олж, ижил templateId-ийн суудлуудыг нэгтгэн invoice хүсэлтэд илгээнэ. seatIds тодорхойгүй бол хоосон seatIds-тэй isSeat: true template ашиглана.

06 — ЗАХИАЛГА

Төлбөр ба invoice

POST/pos-kiosk/invoice

Тасалбар түгжих, invoice үүсгэх

Body: eventId болон templates[] — templateId дээр seats[] (суудалтай) эсвэл тоо ширхэг (суудалгүй) дамжуулна.

Request body · JSON
{
  "eventId": "65b1234567890abcdef12345",
  "templates": [
    { "templateId": "65b1234567890abcdef12346", "seats": ["SF2-R1-s9", "SF2-R1-s10"] },
    { "templateId": "65b1234567890abcdef12347", "seats": 2 }
  ]
}
1
Invoice үүсгэх

v1: 10 минутын дотор хүчинтэй. v2: хамгийн ихдээ 15 минут.

2
Төлбөрийн үр дүнг боловсруулах

Амжилттай бол /to-success/{invoiceId}-г заавал дуудна.

3
Төлбөр амжилтгүй эсвэл цуцлагдсан

/discard/{invoiceId}-г дуудан тасалбарын түгжээг суллана.

4
Тасалбар, QR авах

/check-invoice/{invoiceId} хүсэлт төлөгдсөн invoice-ийн QR-уудыг буцаана.

to-success хүсэлтийг орхиж болохгүй

Төлбөр амжилттай болсон ч баталгаажуулалт хийхгүй бол invoice хугацаа дуусахад автоматаар цуцлагдаж, тасалбар түгжээнээс гарна.

07 — ТАСАЛБАР & MERCH

Жагсаалт ба дэлгэрэнгүй

GET/pos-kiosk/tickets

Тасалбарын жагсаалт

page · limit · eventId?

GET/pos-kiosk/ticket/{id}

Тасалбарын дэлгэрэнгүй

id — тасалбарын ID

GET/pos-kiosk/merches

Merch жагсаалт

page · limit · eventId?

GET/pos-kiosk/merches/{id}

Merch дэлгэрэнгүй

id — merch-ийн ID

Тасалбар болон merch жагсаалтад page, limit, eventId query параметр ашиглана. eventId өгөхгүй бол бүх борлуулалтын жагсаалт буцна.

08 — БАРИМТ & БУЦААЛТ

И-баримт ба буцаалт

POST/pos-kiosk/ebarimt/{invoiceId}

И-баримт авах

v2 invoice төлөгдсөн байх ёстой. Receipt-ийн төрлийг хүсэлтэд дамжуулахгүй; Portal.mn-ийн event тохиргоогоор шийдэгдэнэ.

201Баримт бэлэн. Хариуны receipt өгөгдлөөр хэвлэнэ.
202Хүлээгдэж байна. 1–2 секундийн дараа дахин дууд; давхар receipt үүсэхгүй.
400 / 404400: гаргах боломжгүй. 404: invoice олдсонгүй эсвэл өөр client-ийнх.
!
HTTP timeout-ыг 30 секундээс багагүй тохируулна уу

И-баримтын нэг хүсэлт ойролцоогоор 24 секунд хүртэл хүлээж болно. Receipt алдаа давтагдвал Portal.mn-ийн багт хандана уу.

POST/pos-kiosk/refund/{invoiceId}

Тасалбар буцаах

Зөвхөн v1 event-д дэмжигдэнэ. v2 invoice буцаахад 400 refundNotAvailable алдаа гарна.