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

Get Random Gesture API

این API کد gesture تصادفی (سه رقمی) را برای احراز هویت ویدیویی دریافت می‌کند. این سرویس بخش دوم از فرآیند احراز هویت ویدیویی است و نیاز به kyc_id دارد که از سرویس تطبیق سلفی با کد ملی و تاریخ تولد دریافت می‌شود. در صورت موفقیت، کد gesture برگردانده شده و کاربر باید این کد را با انگشتان دست راست در کنار صورت در ویدیو نمایش دهد.

POST /api/services/get-random-gesture/
نیاز به احراز هویت Token 30 requests/minute

مستندات

Overview

Overview

The Get Random Gesture API is the second step in the video authentication workflow. It receives a KYC ID from the selfie national code birthday match service and returns a random 3-digit gesture code that the user must display in a video using their right hand fingers next to their face.

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.

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

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 JSON body containing kyc_id:

curl -X POST /api/services/get-random-gesture/ \
  -H "Authorization: Token ..." \
  -H "X-Unique-Code: ..." \
  -H "Content-Type: application/json" \
  -d '{"kyc_id": "78d399c8-ed0d-44d5-92e9-999de5a45b50"}'

Response Format

Response Format

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

Best Practices

Best Practices

  • Always call selfie_national_code_birthday_match first to get a valid kyc_id.
  • Store the kyc_id and gesture for the complete authentication flow.
  • Ensure the gesture code is clearly visible in the video with good lighting.
  • The same kyc_id must be used for both get_random_gesture and video_authentication.
  • Store request_ref, ref_id and operation_time for auditing.

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

پارامتر نوع اجباری توضیحات مثال
kyc_id String اجباری شناسه احراز هویت (KYC ID) که از سرویس تطبیق سلفی با کد ملی و تاریخ تولد دریافت شده است.
اعتبارسنجی: باید یک UUID معتبر باشد که از خروجی سرویس selfie_national_code_birthday_match دریافت شده باشد.
78d399c8-ed0d-44d5-92e9-999de5a45b50

مثال‌های کد

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/"
payload = {
    "kyc_id": kyc_id
}
response2 = requests.post(url2, headers=headers, json=payload)
gesture = response2.json()["response_data"]["gesture"]
print(f"Gesture code: {gesture}")  # e.g., "123"
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 from selfie_national_code_birthday_match
        using var form1 = new MultipartFormDataContent();
        using var fileStream = File.OpenRead("selfie.jpg");
        var fileContent = new StreamContent(fileStream);
        fileContent.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg");
        form1.Add(fileContent, "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 with kyc_id
        var payload = new { kyc_id = kycId };
        var json2 = JsonSerializer.Serialize(payload);
        var content = new StringContent(json2, Encoding.UTF8, "application/json");
        var response2 = await client.PostAsync("https://inquiry.sepal.ir/api/services/get-random-gesture/", content);
        var result2 = await response2.Content.ReadAsStringAsync();
        Console.WriteLine(result2);
    }
}
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 from selfie_national_code_birthday_match
$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 with kyc_id
$url2 = "https://inquiry.sepal.ir/api/services/get-random-gesture/";
$postFields2 = 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, $postFields2);
curl_setopt($ch2, CURLOPT_HTTPHEADER, array_merge($headers, ["Content-Type: application/json"]));
$response2 = curl_exec($ch2);
curl_close($ch2);

echo $response2;
?>
cURL Example

Command-line cURL example showing the complete workflow.

# Step 1: Get kyc_id from selfie_national_code_birthday_match
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 with kyc_id
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"}'

فرمت پاسخ

200
پاسخ موفق

پاسخ موفق شامل کد gesture سه رقمی که کاربر باید در ویدیو نمایش دهد.

ساختار پاسخ:
{
  "amount": "integer",
  "success": "boolean",
  "request_ref": "string",
  "error_message": "null",
  "response_data": {
    "ref_id": "string",
    "gesture": "string",
    "operation_time": "integer"
  },
  "response_time_ms": "integer"
}
مثال پاسخ:
{
  "amount": 10000,
  "success": true,
  "request_ref": "XIHAUOLARKN7M0KLZKJTRNTNIPXUL7YZ",
  "error_message": null,
  "response_data": {
    "ref_id": "test-ref-id-123",
    "gesture": "123",
    "operation_time": 1763287828519
  },
  "response_time_ms": 150
}
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
}
404
خطا

kyc_id نامعتبر است یا منقضی شده است.

ساختار پاسخ:
{
  "error": {
    "code": "string",
    "details": "object",
    "message": "string"
  },
  "success": "boolean"
}
مثال پاسخ:
{
  "error": {
    "code": "4001",
    "message": "KYC ID نامعتبر است."
  },
  "success": false
}