You need to enable JavaScript to use this application.
POST احراز هویت

Video Authentication API

این API ویدیو احراز هویت کاربر را دریافت کرده و با استفاده از شناسه KYC و کد gesture صحت هویت کاربر را تأیید می‌کند. این سرویس بخش سوم از فرآیند احراز هویت ویدیویی است و نیاز به kyc_id و کد gesture دارد که از دو سرویس قبلی دریافت می‌شوند.

POST /api/services/video-authentication/
نیاز به احراز هویت Token 30 requests/minute

مستندات

Overview

Overview

The Video Authentication API is the final step in the video authentication workflow. It receives a KYC ID and an authentication video where the user displays the gesture code with their right hand fingers next to their face. The API verifies the user's identity based on the video content and previously generated gesture.

Workflow

Complete Video Authentication Workflow

  1. Step 1: Call selfie_national_code_birthday_match service with selfie image, national code, and birth date. Extract kyc_id from the response.
  2. Step 2: Call get_random_gesture service with the kyc_id from step 1. Extract gesture (3-digit code) from the response.
  3. Step 3: User records a video showing the gesture code with their right hand fingers next to their face. Maximum video size is 30MB.
  4. Step 4: Call video_authentication service with the kyc_id from step 1 and the recorded video. Receive the final authentication result in verified and similarity fields.

Important: The same kyc_id must be used in steps 2 and 4. The gesture code received in step 2 must be clearly displayed in the video recorded for step 3.

Authentication

Authentication

Provide token authentication headers in every request:

Authorization: Token YOUR_AUTH_TOKEN
X-Unique-Code: YOUR_UNIQUE_CODE

Request Format

Request Format

Send a POST request with multipart/form-data body containing kyc_id and authentication_video:

curl -X POST /api/services/video-authentication/ \
  -H "Authorization: Token ..." \
  -H "X-Unique-Code: ..." \
  -F "kyc_id=78d399c8-ed0d-44d5-92e9-999de5a45b50" \
  -F "authentication_video=@auth_video.mp4;type=video/mp4"

Response Format

Response Format

در پاسخ موفق، کلید response_data حاوی نتیجه احراز هویت است. فیلد verified نشان می‌دهد احراز هویت موفق بوده است یا خیر و similarity میزان شباهت را به صورت عددی بین 0 و 1 نشان می‌دهد. همچنین شناسه رهگیری در ref_id و زمان عملیات در operation_time بازگردانده می‌شود.

Best Practices

Best Practices

  • از ویدیوهایی با کیفیت بالا، نور مناسب و پس‌زمینه ساده استفاده کنید.
  • اطمینان حاصل کنید که چهره کاربر و انگشتان دست راست او در کنار صورت به‌خوبی دیده می‌شوند.
  • کد gesture باید به‌طور کامل و واضح در ویدیو نمایش داده شود.
  • از همان kyc_id برای سرویس‌های get_random_gesture و video_authentication استفاده کنید.
  • request_ref، ref_id و operation_time را برای مقاصد ممیزی و پیگیری ذخیره کنید.

پارامترهای درخواست

پارامتر نوع اجباری توضیحات مثال
kyc_id String اجباری شناسه احراز هویت (KYC ID) که از سرویس تطبیق سلفی با کد ملی و تاریخ تولد دریافت شده است.
اعتبارسنجی: باید یک UUID معتبر باشد که از خروجی سرویس selfie_national_code_birthday_match دریافت شده باشد.
78d399c8-ed0d-44d5-92e9-999de5a45b50
authentication_video File اجباری ویدیو احراز هویت (حداکثر حجم ۳۰ مگابایت، فرمت‌های مجاز: MP4، AVI، ...). در این ویدیو کاربر باید کد gesture را با انگشتان دست راست در کنار صورت نمایش دهد.
اعتبارسنجی: حداکثر حجم ۳۰ مگابایت. ویدیو باید واضح باشد، چهره و دست راست کاربر به‌خوبی دیده شود و کد gesture به‌درستی نمایش داده شود.
auth_video.mp4

مثال‌های کد

Python Example

Example using Python requests library showing the complete workflow.

import requests

# Step 1: Call selfie_national_code_birthday_match to get kyc_id
url1 = "https://inquiry.sepal.ir/api/services/selfie-national-code-birthday-match/"
headers = {
    "Authorization": "Token YOUR_AUTH_TOKEN",
    "X-Unique-Code": "YOUR_UNIQUE_CODE",
}
files = {
    "selfie_image": ("selfie.jpg", open("selfie.jpg", "rb"), "image/jpeg"),
}
data = {
    "national_code": "4640229534",
    "birth_date": "13790514",
}
response1 = requests.post(url1, headers=headers, files=files, data=data)
kyc_id = response1.json()["response_data"]["kyc_id"]

# Step 2: Call get_random_gesture with kyc_id
url2 = "https://inquiry.sepal.ir/api/services/get-random-gesture/"
payload2 = {"kyc_id": kyc_id}
response2 = requests.post(url2, headers=headers, json=payload2)
gesture = response2.json()["response_data"]["gesture"]
print(f"Gesture code: {gesture}")  # e.g., "123"

# Step 3: Record video where user shows the gesture code with right hand fingers next to the face
# Assume the recorded video file is saved as auth_video.mp4

# Step 4: Call video_authentication with kyc_id and authentication_video
url3 = "https://inquiry.sepal.ir/api/services/video-authentication/"
files3 = {
    "authentication_video": ("auth_video.mp4", open("auth_video.mp4", "rb"), "video/mp4"),
}
data3 = {
    "kyc_id": kyc_id,
}
response3 = requests.post(url3, headers=headers, files=files3, data=data3)
print(response3.json())
C# Example

Example using C# HttpClient showing the complete workflow.

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.IO;
using System.Text;
using System.Text.Json;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Token", "YOUR_AUTH_TOKEN");
        client.DefaultRequestHeaders.Add("X-Unique-Code", "YOUR_UNIQUE_CODE");

        // Step 1: Get kyc_id
        using var form1 = new MultipartFormDataContent();
        using var fileStream1 = File.OpenRead("selfie.jpg");
        var fileContent1 = new StreamContent(fileStream1);
        fileContent1.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg");
        form1.Add(fileContent1, "selfie_image", "selfie.jpg");
        form1.Add(new StringContent("4640229534"), "national_code");
        form1.Add(new StringContent("13790514"), "birth_date");

        var response1 = await client.PostAsync("https://inquiry.sepal.ir/api/services/selfie-national-code-birthday-match/", form1);
        var result1 = await response1.Content.ReadAsStringAsync();
        var json1 = JsonDocument.Parse(result1);
        var kycId = json1.RootElement.GetProperty("response_data").GetProperty("kyc_id").GetString();

        // Step 2: Get gesture
        var payload2 = new { kyc_id = kycId };
        var json2 = JsonSerializer.Serialize(payload2);
        var content2 = new StringContent(json2, Encoding.UTF8, "application/json");
        var response2 = await client.PostAsync("https://inquiry.sepal.ir/api/services/get-random-gesture/", content2);
        var result2 = await response2.Content.ReadAsStringAsync();
        Console.WriteLine(result2);

        // Step 3: Record auth_video.mp4 (outside of this code)

        // Step 4: Video authentication
        using var form3 = new MultipartFormDataContent();
        using var fileStream3 = File.OpenRead("auth_video.mp4");
        var fileContent3 = new StreamContent(fileStream3);
        fileContent3.Headers.ContentType = new MediaTypeHeaderValue("video/mp4");
        form3.Add(fileContent3, "authentication_video", "auth_video.mp4");
        form3.Add(new StringContent(kycId), "kyc_id");

        var response3 = await client.PostAsync("https://inquiry.sepal.ir/api/services/video-authentication/", form3);
        var result3 = await response3.Content.ReadAsStringAsync();
        Console.WriteLine(result3);
    }
}
PHP Example

Example using PHP cURL showing the complete workflow.

<?php

$headers = [
    "Authorization: Token YOUR_AUTH_TOKEN",
    "X-Unique-Code: YOUR_UNIQUE_CODE"
];

// Step 1: Get kyc_id
$url1 = "https://inquiry.sepal.ir/api/services/selfie-national-code-birthday-match/";
$postFields1 = [
    "selfie_image" => new CURLFile("selfie.jpg", "image/jpeg", "selfie.jpg"),
    "national_code" => "4640229534",
    "birth_date" => "13790514"
];

$ch1 = curl_init($url1);
curl_setopt($ch1, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch1, CURLOPT_POST, true);
curl_setopt($ch1, CURLOPT_POSTFIELDS, $postFields1);
curl_setopt($ch1, CURLOPT_HTTPHEADER, $headers);
$response1 = curl_exec($ch1);
curl_close($ch1);

$result1 = json_decode($response1, true);
$kycId = $result1["response_data"]["kyc_id"];

// Step 2: Get gesture
$url2 = "https://inquiry.sepal.ir/api/services/get-random-gesture/";
$payload2 = json_encode(["kyc_id" => $kycId]);

$ch2 = curl_init($url2);
curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch2, CURLOPT_POST, true);
curl_setopt($ch2, CURLOPT_POSTFIELDS, $payload2);
curl_setopt($ch2, CURLOPT_HTTPHEADER, array_merge($headers, ["Content-Type: application/json"]));
$response2 = curl_exec($ch2);
curl_close($ch2);

// Step 3: Record auth_video.mp4 manually

// Step 4: Video authentication
$url3 = "https://inquiry.sepal.ir/api/services/video-authentication/";
$postFields3 = [
    "kyc_id" => $kycId,
    "authentication_video" => new CURLFile("auth_video.mp4", "video/mp4", "auth_video.mp4")
];

$ch3 = curl_init($url3);
curl_setopt($ch3, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch3, CURLOPT_POST, true);
curl_setopt($ch3, CURLOPT_POSTFIELDS, $postFields3);
curl_setopt($ch3, CURLOPT_HTTPHEADER, $headers);
$response3 = curl_exec($ch3);
curl_close($ch3);

echo $response3;
?>
cURL Example

Command-line cURL example showing the complete workflow.

# Step 1: Get kyc_id
curl -X POST "https://inquiry.sepal.ir/api/services/selfie-national-code-birthday-match/" \
  -H "Authorization: Token YOUR_AUTH_TOKEN" \
  -H "X-Unique-Code: YOUR_UNIQUE_CODE" \
  -F "national_code=4640229534" \
  -F "birth_date=13790514" \
  -F "selfie_image=@selfie.jpg;type=image/jpeg"

# Extract kyc_id from response, then:

# Step 2: Get gesture
curl -X POST "https://inquiry.sepal.ir/api/services/get-random-gesture/" \
  -H "Authorization: Token YOUR_AUTH_TOKEN" \
  -H "X-Unique-Code: YOUR_UNIQUE_CODE" \
  -H "Content-Type: application/json" \
  -d '{"kyc_id": "YOUR_KYC_ID"}'

# Step 3: Record video manually (auth_video.mp4)

# Step 4: Video authentication
curl -X POST "https://inquiry.sepal.ir/api/services/video-authentication/" \
  -H "Authorization: Token YOUR_AUTH_TOKEN" \
  -H "X-Unique-Code: YOUR_UNIQUE_CODE" \
  -F "kyc_id=YOUR_KYC_ID" \
  -F "authentication_video=@auth_video.mp4;type=video/mp4"

فرمت پاسخ

200
پاسخ موفق

پاسخ موفق شامل نتیجه احراز هویت ویدیویی (فیلد verified) و میزان شباهت (similarity).

ساختار پاسخ:
{
  "amount": "integer",
  "success": "boolean",
  "request_ref": "string",
  "error_message": "null",
  "response_data": {
    "ref_id": "string",
    "verified": "boolean",
    "similarity": "float",
    "operation_time": "integer"
  },
  "response_time_ms": "integer"
}
مثال پاسخ:
{
  "amount": 30000,
  "success": true,
  "request_ref": "XIHAUOLARKN7M0KLZKJTRNTNIPXUL7YZ",
  "error_message": null,
  "response_data": {
    "ref_id": "test-ref-id-123",
    "verified": true,
    "similarity": 0.95,
    "operation_time": 1763287828519
  },
  "response_time_ms": 2500
}
400
خطا

پارامترهای ورودی نامعتبر هستند یا kyc_id / ویدیو ارسال نشده است.

ساختار پاسخ:
{
  "error": {
    "code": "string",
    "details": "object",
    "message": "string"
  },
  "success": "boolean"
}
مثال پاسخ:
{
  "error": {
    "code": "INVALID_PARAMETERS",
    "details": {
      "kyc_id": [
        "This field is required."
      ]
    },
    "message": "پارامترهای ورودی نامعتبر است."
  },
  "success": false
}
422
خطا

ویدیو توسط سپال‌یار قابل پردازش نیست (کیفیت پایین، ناقص یا نامعتبر).

ساختار پاسخ:
{
  "error": {
    "code": "string",
    "details": "object",
    "message": "string"
  },
  "success": "boolean"
}
مثال پاسخ:
{
  "error": {
    "errors": [
      {
        "code": "5001",
        "message": "ویدیو نامعتبر است."
      }
    ],
    "ref_id": "7713c9e3-0b54-4a72-8a01-17fb37ee0ede",
    "operation_time": 1762691215312
  },
  "success": false
}