Developer Documentation

1. Ерөнхий мэдээлэл

gesign.mn нь 3-дагч тал системүүдэд дараах үйлчилгээнүүдийг үзүүлнэ:

• Partner Sign Request — хэрэглэгчээр баримтад гарын үсэг зуруулах (async, webhook)
• CSC API v2 — Cloud Signature Consortium стандартаар шууд гарын үсэг зурах (sync)
• OAuth2 Login — gesign.mn account-аар нэвтрэх
• Signature Verify — гарын үсэг баталгаажуулах (public, auth шаардахгүй)

2. Authentication

2.1 OAuth2 Client (Partner)

Partner систем бүр OAuth2 Client болж бүртгэгдэнэ. Admin хэсгээс client_id + client_secret олгоно.

Token авах — Client Credentials

POST /oauth2/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "scope": "sign webhook"
}

// Response
{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "sign webhook"
}

Scopes:

2.2 User JWT Token

CSC API болон хэрэглэгчийн endpoint-үүд JWT Bearer token шаарддаг.

Authorization: Bearer <access_token>

3. Partner Sign Request API

Хэрэглэгчээр баримтад гарын үсэг зуруулах async flow. Partner систем хүсэлт үүсгэнэ, хэрэглэгч gesign.mn-ээр зурна, webhook-ээр үр дүн ирнэ.

Partner App                    gesign.mn                    User
    |                              |                          |
    |-- POST /partner/sign-request |                          |
    |         (document_hash)      |                          |
    |<---- sign_url, request_id ---|                          |
    |                              |                          |
    |         sign_url-г хэрэглэгчид илгээнэ (email/SMS)     |
    |---------------------------------------------------------|
    |                              |                          |
    |                              |<-- Хэрэглэгч sign_url  --|
    |                              |    нээж, гарын үсэг зурна|
    |                              |                          |
    |<---- Webhook: signed --------|                          |
    |   (signature, certificate)   |                          |

POST /api/v1/partner/sign-request

Auth: Bearer <partner_token> (scope: sign)

// Request
{
  "user_email": "user@example.mn",     // эсвэл user_phone
  "user_phone": "+97699001234",         // optional
  "document_hash": "e3b0c44298fc...",   // SHA-256 hex
  "document_name": "contract.pdf",      // optional
  "document_url": "https://...",        // optional, хэрэглэгчид харуулна
  "description": "Гэрээний баримт",    // optional
  "required_loa": 2,                    // 1-3, default 2
  "callback_url": "https://partner.mn/callback",  // optional
  "external_ref": "order-12345",        // таны системийн reference
  "expires_in": 86400                   // секундээр, default 24 цаг
}

// Response 201
{
  "request_id": "uuid",
  "status": "pending",
  "sign_url": "https://gesign.mn/sign/uuid",
  "expires_at": "2026-03-31T12:00:00Z",
  "external_ref": "order-12345"
}

GET /api/v1/partner/sign-request/:id

Auth: Bearer <partner_token> (scope: sign)

// Response
{
  "request_id": "uuid",
  "status": "signed",       // pending | signed | rejected | expired
  "external_ref": "order-12345",
  "signed_at": "2026-03-30T10:30:00Z",
  "rejected_at": null,
  "expires_at": "2026-03-31T12:00:00Z",
  "created_at": "2026-03-30T10:00:00Z"
}

POST /api/v1/partner/webhooks

Auth: Bearer <partner_token> (scope: webhook)

// Request
{
  "url": "https://partner.mn/webhook/eid",
  "events": ["sign_request.signed", "sign_request.rejected", "sign_request.expired"]
}

// Response 201
{
  "webhook": { "id": "uuid", "url": "...", "events": [...], "status": "active" },
  "signing_key": "hex_secret"   // HMAC баталгаажуулалтад хэрэглэнэ
}

4. CSC API v2 — Cloud Signing

Cloud Signature Consortium стандартын дагуу хэрэглэгчийн нэрийн өмнөөс hash-д шууд гарын үсэг зурна. Real-time (sync) flow.

1. credentials/list    →  Хэрэглэгчийн сертификатууд
2. credentials/info    →  Сертификатын мэдээлэл + SAM тохиргоо
3. credentials/authorize  →  OTP + PIN шалгалт → SAD token
4. signatures/signHash    →  SAD + hash → signature

POST /csc/v2/info

Auth: шаардахгүй

// Response
{
  "specs": "2.0.0.2",
  "name": "gesign.mn",
  "region": "MN",
  "lang": "mn-MN",
  "authType": ["basic", "oauth2code"],
  "methods": [
    "auth/login", "credentials/list", "credentials/info",
    "credentials/authorize", "signatures/signHash"
  ]
}

POST /csc/v2/credentials/list

Auth: Bearer <user_jwt>

// Response
{
  "credentialIDs": [
    "ea530523-5b6b-4674-810f-23a2c6927857"
  ]
}

POST /csc/v2/credentials/info

Auth: Bearer <user_jwt>

// Request
{
  "credentialID": "ea530523-...",
  "certInfo": true,
  "authInfo": true,
  "certificates": "single"
}

// Response
{
  "key": { "status": "enabled", "algo": ["1.2.840.10045.2.1"], "len": 256, "curve": "P-256" },
  "cert": {
    "status": "valid",
    "subjectDN": "CN=..., C=MN",
    "serialNumber": "...",
    "validFrom": "20260324...",
    "validTo": "20270324...",
    "certificates": ["MIIBxTCCAWugAwIB..."]
  },
  "authMode": "explicit",
  "SCAL": "1",
  "multisign": 1,
  "OTP": { "presence": "true", "type": "online" },
  "PIN": { "presence": "true", "format": "N" }
}

POST /csc/v2/credentials/authorize

Auth: Bearer <user_jwt>

SAM (Signature Activation Module) шалгалт. OTP + PIN шаардлагатай (admin тохиргооноос хамаарна).

// Request (1-р дуудалт — OTP код илгээгдэнэ)
{
  "credentialID": "ea530523-...",
  "numSignatures": 1,
  "hash": ["base64_encoded_sha256_hash"]
}

// Response 401
{ "error": "otp_required", "error_description": "OTP код илгээгдлээ (SMS)..." }

// Request (2-р дуудалт — OTP + PIN-тэй)
{
  "credentialID": "ea530523-...",
  "numSignatures": 1,
  "hash": ["base64_encoded_sha256_hash"],
  "OTP": "123456",
  "PIN": "654321"
}

// Response 200
{
  "SAD": "p6Kw_2zgWUuChdVq...",
  "expiresIn": 300
}

POST /csc/v2/signatures/signHash

Auth: Bearer <user_jwt>

// Request
{
  "credentialID": "ea530523-...",
  "SAD": "p6Kw_2zgWUuChdVq...",
  "hash": ["base64_encoded_sha256_hash"],
  "hashAlgo": "2.16.840.1.101.3.4.2.1",
  "signAlgo": "1.2.840.10045.4.3.2"
}

// Response
{
  "signatures": ["A9SyJAhHw2TN8q5zco7f..."]
}

5. OAuth2 Login

3-дагч тал систем gesign.mn account-аар хэрэглэгчийг нэвтрүүлэх. Authorization Code + PKCE flow.

1. GET  /oauth/authorize?client_id=...&redirect_uri=...&code_challenge=...
2. Хэрэглэгч gesign.mn-д нэвтэрч consent өгнө
3. Redirect → partner callback?code=...&state=...
4. POST /api/v1/auth/token  (code + code_verifier → access_token)

GET /oauth/authorize

GET /oauth/authorize?
  client_id=your_client_id&
  redirect_uri=https://partner.mn/callback&
  response_type=code&
  scope=openid+profile+email&
  state=random_csrf_state&
  code_challenge=S256_hash&
  code_challenge_method=S256

POST /api/v1/auth/token

// Request
{
  "grant_type": "authorization_code",
  "code": "auth_code_from_callback",
  "code_verifier": "original_pkce_verifier"
}

// Response
{
  "data": {
    "access_token": "eyJhbGci...",
    "refresh_token": "...",
    "expires_in": 3600
  }
}

Discovery endpoints

6. Гарын үсэг баталгаажуулах

Эдгээр endpoint-ууд нээлттэй — authentication шаардахгүй.

// POST /api/v1/signature/verify
// Content-Type: multipart/form-data
// Fields: signature (file), document (file), signature_format (string)

// Response
{
  "is_valid": true,
  "signer_name": "Отгонбаяр БАЯРСАЙХАН",
  "signing_time": "2026-03-30T10:30:00Z",
  "signature_level": "CAdES-T",
  "is_timestamped": true,
  "certificate_info": "CN=..., C=MN"
}

7. Webhooks

Event types

Webhook payload

POST https://partner.mn/webhook/eid
Content-Type: application/json
X-Webhook-Signature: sha256=<hmac_hex>
X-Webhook-Timestamp: 1709400000

{
  "event": "sign_request.signed",
  "request_id": "uuid",
  "external_ref": "order-12345",
  "status": "signed",
  "signed_at": "2026-03-30T10:30:00Z",
  "signature": "MEYCIQD...",      // base64 CAdES signature
  "certificate": "-----BEGIN CERTIFICATE-----\n..."
}

Signature шалгалт

# Python жишээ
import hmac, hashlib

def verify_webhook(body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    payload = f"{timestamp}.".encode() + body
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Retry policy

Webhook амжилтгүй (HTTP 2xx биш) бол дараах дарааллаар дахин илгээнэ:

8. Алдааны кодууд

// Стандарт алдааны формат
{
  "error": {
    "code": "error_code",
    "message": "Тайлбар"
  }
}

9. PKI Endpoints