IDmatic API და Web SDK

მიმოხილვა

IDmatic არის ვინაობის დისტანციური დადასტურების პლატფორმა. თქვენი სერვერი ქმნის ვინაობის დადასტურების სესიას, მომხმარებელი ტელეფონით გადაიღებს დოკუმენტს და სახის ფოტოს, ხოლო IDmatic ამოიცნობს დოკუმენტს, ამოწმებს მას და გიბრუნებთ სტრუქტურირებულ შედეგს და გადაწყვეტილებას.

• ბაზური მისამართი: https://idmatic.net (On-premise-ზე — თქვენი სერვერის მისამართი). ყველა მოთხოვნა და პასუხი — JSON, UTF-8.
• მანქანით წაკითხვადი სპეციფიკაცია: /openapi.yaml (OpenAPI 3.1) — კლიენტის ბიბლიოთეკის გენერაციისთვის.
• დროები — ISO 8601 / RFC 3339 ფორმატში, UTC-ში. ქვეყნის კოდები — ISO 3166-1 alpha-3 (მაგ. GEO).

სწრაფი დაწყება

ინტეგრაცია ხუთი ნაბიჯია. სატესტო რეჟიმში ყველაფერი უფასოა და რეალურ მომხმარებლებზე გავლენას არ ახდენს.

1. 1დარეგისტრირდით და კაბინეტში შექმენით სატესტო API გასაღები (idm_test_…) — „დეველოპერები → API გასაღებები“.
2. 2თქვენი სერვერიდან შექმენით ვინაობის დადასტურება: POST /v1/verifications.
3. 3მიღებული url გაუგზავნეთ მომხმარებელს, გადაამისამართეთ ან გახსენით Web SDK-ით.
4. 4დაარეგისტრირეთ webhook („დეველოპერები → Webhook-ები“) და შეამოწმეთ ხელმოწერა.
5. 5webhook-ის მიღების შემდეგ წამოიღეთ სრული შედეგი: GET /v1/verifications/{id}.

curl -X POST https://idmatic.net/v1/verifications \
  -H "Authorization: Bearer $IDMATIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "CUST-1042",
    "redirect_url": "https://example.ge/kyc/done",
    "metadata": { "channel": "web", "plan": "gold" }
  }'

ავთენტიფიკაცია და გარემოები

API მოთხოვნები ავტორიზდება კაბინეტში შექმნილი გასაღებით, HTTP სათაურით:

Authorization: Bearer idm_live_XXXXXXXXXXXXXXXXXXXXXXXX

• გასაღები გამოიყენეთ მხოლოდ სერვერიდან. ბრაუზერსა და მობილურ აპლიკაციაში API გასაღები არასდროს მოათავსოთ — იქ მხოლოდ ვინაობის დადასტურების url გადაეცემა.
• გასაღები შეგიძლიათ შეზღუდოთ თქვენი სერვერების IP მისამართებით; სხვა მისამართიდან მოთხოვნა დაბრუნდება 403 ip_not_allowed.
• გასაღების გაჟონვის ეჭვისას — დაუყოვნებლივ გააუქმეთ კაბინეტში და შექმენით ახალი. გასაღებების შექმნა და გაუქმება აუდიტში ფიქსირდება.

ვინაობის დადასტურების შექმნა

სხეულში უცნობი ველები არ მიიღება (400 invalid_json) — ეს იცავს შეცდომით გაგზავნილი მონაცემებისგან.

HTTP/1.1 201 Created

{
  "id": "ver_…",
  "status": "created",
  "url": "https://idmatic.net/verify#vs_…",
  "sdk_token": "vs_…",
  "expires_at": "2026-10-08T12:00:00Z"
}

სტატუსები და გადაწყვეტილება

გადაწყვეტილების ობიექტი: decision.status, decision.reasons (მიზეზების კოდები) და decision.manual — true, თუ საბოლოო გადაწყვეტილება ოპერატორმა მიიღო.

შედეგის მიღება

GET /v1/verifications/ver_…

{
  "id": "ver_…",
  "status": "approved",
  "mode": "live",
  "reference": "CUST-1042",
  "decision": { "status": "approved", "reasons": [], "manual": false },
  "document": {
    "doc_type": "…",
    "doc_name": "პირადობის მოწმობა",
    "kind": "id_card",
    "country": "GEO",
    "mrz_format": "TD1",
    "fields": [
      { "key": "surname", "label": "გვარი", "value": "…",
        "source": "mrz+viz", "confidence": 100, "review": false },
      { "key": "personal_number", "label": "პირადი ნომერი", "value": "…",
        "source": "mrz+viz", "confidence": 100, "review": false }
    ],
    "risk": "low"
  },
  "checks": [
    { "id": "mrz", "status": "passed", "message": "…" },
    { "id": "document_expiry", "status": "passed", "message": "…" },
    { "id": "data_consistency", "status": "passed", "message": "…" }
  ],
  "created_at": "2026-10-07T12:00:00Z",
  "completed_at": "2026-10-07T12:01:04Z",
  "erased": false
}

გამოსახულებები

დოკუმენტიდან ამოჭრილი პორტრეტი (photo) ან ხელმოწერა (signature). ყოველი ნახვა აუდიტში იწერება. მონაცემების წაშლის შემდეგ პასუხი — 404.

რეგისტრატურა და HL7 FHIR

რეგისტრატურის მოდულით (კლინიკა, ლაბორატორია, ოფისი) შექმნილი ვინაობის დადასტურების ველები — მხოლოდ ის ველები, რომლებიც კომპანიამ „რეგისტრატურის“ პარამეტრებში მონიშნა. /desk აბრუნებს subject-ს (key, label, value), წარმომადგენლით სცენარში — representative-ს და relation-ს; /fhir — HL7 FHIR R4 Patient რესურსს (application/fhir+json): პირადი ნომერი — identifier, ბავშვის შემთხვევაში წარმომადგენელი — contact, დოკუმენტის გარეშე რეგისტრაცია — meta.tag unverified.

სინქრონული ამოცნობა

როცა გამოსახულება უკვე თქვენს სისტემაშია (მაგ. ოფისის სკანერი), შეგიძლიათ პირდაპირ გაგზავნოთ ამოსაცნობად: {"front": "<base64>", "back": "<base64>"}. პასუხში ბრუნდება ველები, შემოწმებები, შემოთავაზებული სტატუსი და ამოჭრილი გამოსახულებები. სერვერზე არაფერი ინახება.

მონაცემების წაშლა

შლის გამოსახულებებს და პერსონალურ მონაცემებს; გადაწყვეტილება, სტატუსი და აუდიტის ჩანაწერი რჩება. გარდა ამისა, კაბინეტში მითითებული შენახვის ვადის გასვლისას წაშლა ავტომატურად ხდება.

დოკუმენტის ტიპები

აბრუნებს თქვენს ანგარიშზე აქტიურ დოკუმენტის ტიპებს. საქართველოს დოკუმენტები (პირადობის მოწმობა, პასპორტი, ბინადრობის და მართვის მოწმობა) ეფუძნება PRADO-ს რეესტრის ემისიებს.

შეცდომები და ლიმიტები

შეცდომა ყოველთვის ერთი ფორმისაა. request_id მიუთითეთ მხარდაჭერასთან მიმართვისას.

{
  "error": {
    "code": "invalid_api_key",
    "message": "…",
    "request_id": "req_…"
  }
}

• ლიმიტი: 600 მოთხოვნა წუთში თითო გასაღებზე.
• გამეორებისას გამოიყენეთ ექსპონენციალური დაყოვნება და გაითვალისწინეთ Retry-After სათაური.

მოვლენები და მიწოდება

Webhook-ი გატყობინებთ ვინაობის დადასტურების სტატუსის ცვლილებას. მიმართულება და საიდუმლო გასაღები კაბინეტში იმართება. შეტყობინება პერსონალურ მონაცემებს არ შეიცავს — მხოლოდ სტატუსს და გადაწყვეტილებას.

POST https://example.ge/idmatic/webhook
Content-Type: application/json
IDmatic-Signature: t=1791400000,v1=5f2c9a…

{
  "id": "evt_…",
  "type": "verification.completed",
  "created": "2026-10-07T12:01:05Z",
  "data": {
    "id": "ver_…",
    "status": "approved",
    "mode": "live",
    "reference": "CUST-1042",
    "completed_at": "2026-10-07T12:01:04Z",
    "decision": { "status": "approved", "reasons": [], "manual": false }
  }
}

• მიწოდება — ერთხელ მაინც: წარუმატებლობისას (არა-2xx პასუხი ან დროის ამოწურვა) შეტყობინება მეორდება 1 წუთიდან 24 საათამდე ინტერვალებით.
• დუბლიკატების ასაცილებლად შეინახეთ მოვლენის id და განმეორებით მიღებული უგულებელყავით (იდემპოტენტობა).
• უპასუხეთ სწრაფად 2xx-ით და დამუშავება გააგრძელეთ ფონურად.
• Production-ში მიმართულება უნდა იყოს https:// და საჯარო მისამართი; გადამისამართება არ მიიღება (SSRF-ისგან დაცვა).

ხელმოწერის შემოწმება

ყოველ შეტყობინებას ახლავს სათაური IDmatic-Signature: t=<unix>,v1=<hex>, სადაც v1 = HMAC-SHA256(secret, "<t>.<body>"). შეამოწმეთ ხელმოწერა დაუმუშავებელ (raw) სხეულზე და უარყავით 5 წუთზე ძველი დროის ნიშნული.

import crypto from "node:crypto";

// Express: app.post("/idmatic/webhook", express.raw({ type: "application/json" }), handler)
export function verifyIDmatic(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false; // განმეორება
  const expected = crypto.createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Web SDK: ჩაშენება

SDK აჩენს ვინაობის დადასტურების მოდულს თქვენს გვერდზე iframe-ით — დამოკიდებულებების გარეშე. ორი რეჟიმია: modal (ფანჯარა; მობილურზე სრულ ეკრანზე) და inline (ბლოკი გვერდში; სიმაღლე ავტომატურად ერგება).

<script src="https://idmatic.net/sdk.js"></script>
<button id="kyc-btn">ვინაობის დადასტურება</button>
<script>
  document.getElementById("kyc-btn").onclick = async () => {
    // 1) ვინაობის დადასტურება იქმნება თქვენს სერვერზე (API გასაღები ბრაუზერში არასდროს!)
    const { url } = await fetch("/api/kyc/start", { method: "POST" }).then((r) => r.json());
    // 2) მოდული იხსნება ფანჯარაში (მობილურზე — სრულ ეკრანზე)
    const v = IDmatic.open({
      url,
      onComplete: (r) => console.log("status:", r.status), // ინფორმაციისთვის — არა გადაწყვეტილებისთვის
      onClose: () => console.log("closed"),
      onEvent: (e) => console.log(e.type, e.step),
    });
    // v.close() — პროგრამულად დახურვა
  };
</script>

მობილურ აპლიკაციებში (iOS, Android) ვინაობის დადასტურების url გახსენით აპლიკაციის ბრაუზერში (SFSafariViewController, Custom Tabs) — კამერაზე წვდომა და უსაფრთხოება ბრაუზერის სტანდარტით მუშაობს.

მოვლენები და პარამეტრები

iframe-დან თქვენს გვერდზე გადმოდის მხოლოდ ნაბიჯი და სტატუსი — პერსონალური მონაცემები არა. მეთოდი close() მოდულს პროგრამულად ხურავს.

ვიჯეტი კოდის გარეშე

ვიჯეტი ვინაობის დადასტურებას ბრაუზერიდან ქმნის — სერვერის კოდის გარეშე. ვიჯეტის კოდი კაბინეტშია („ვიჯეტი და ბრენდი“); შედეგი მოდის webhook-ით.

<script src="https://idmatic.net/sdk.js"></script>

<div data-idmatic-widget="eXXXXXXXXXXXX"
     data-reference="CUST-1042"
     data-mode="modal"
     data-text="ვინაობის დადასტურება"></div>

<script>
  document.querySelector("[data-idmatic-widget]")
    .addEventListener("idmatic:complete", (e) => console.log(e.detail.status));
</script>

უსაფრთხოება და მონაცემები

On-premise განთავსება

IDmatic შეიძლება სრულად განთავსდეს თქვენს ინფრასტრუქტურაში. API, Web SDK, კაბინეტი და ამოცნობის ძრავა იგივეა, რაც ღრუბელში — იცვლება მხოლოდ ბაზური მისამართი.

გაშვების ჩამონათვალი

• API გასაღები ინახება მხოლოდ სერვერზე (საიდუმლოების საცავში), IP შეზღუდვით.
• Webhook-ის ხელმოწერა მოწმდება raw სხეულზე, დროის ნიშნულით, მუდმივი დროის შედარებით.
• მოვლენის id ინახება — დუბლიკატები უგულებელყოფილია.
• საბოლოო სტატუსი იკითხება სერვერიდან, არა ბრაუზერიდან.
• ჩასმის დომენები მითითებულია; ტესტირება გავლილია idm_test_ გასაღებით.
• შენახვის ვადა დაყენებულია თქვენი პოლიტიკის შესაბამისად.
• live გასაღებზე გადასვლა — ტესტების წარმატებით დასრულების შემდეგ.