ناوبری سریع

APIهای مرتبط

Bank Card OCR API

این API تصویر کارت بانکی را دریافت کرده و شماره …

Video Authentication API

این API ویدیو احراز هویت کاربر را دریافت کرده و …

Mobile National Code Match API

This API endpoint allows you to verify if a mobile …

National Code Birthday Match API

This API verifies whether an Iranian national code matches a …

Compare Images API

این API دو تصویر چهره را دریافت می‌کند و آن‌ها …

Selfie National Code Birthday Match API

این API تصویر سلفی کاربر را به همراه کد ملی …

POST احراز هویت

National Card OCR API

این API تصویر کارت ملی را دریافت کرده و اطلاعات متنی استخراج‌شده را بازمی‌گرداند. در صورت موفقیت، هزینه سرویس از کیف پول کسر می‌شود.

POST /api/services/national-card-ocr/

نیاز به احراز هویت Token 30 requests/minute

مستندات

Overview

The National Card OCR API accepts an image of an Iranian national card and returns extracted textual data using Sepal Yar's OCR service.

Authentication

Provide token authentication headers in every request:

Authorization: Token YOUR_AUTH_TOKEN
X-Unique-Code: YOUR_UNIQUE_CODE

Request Format

Send a POST request with multipart/form-data body containing the card image:

curl -X POST /api/services/national-card-ocr/ \
  -H "Authorization: Token ..." \
  -H "X-Unique-Code: ..." \
  -F "national_card_image=@km.jpg;type=image/jpeg"

Response Format

در پاسخ موفق، کلید response_data حاوی خروجی سرویس سپال‌یار است. نمونه فیلدهای بازگشتی شامل name، last_name، father_name، national_id، birth_date و expire_date است. همچنین شناسه رهگیری سپال‌یار در ref_id و زمان عملیات در operation_time برمی‌گردد.

Error Handling

خطاهای رایج شامل نامعتبر بودن ورودی، عدم توانایی OCR در شناسایی متن و خطاهای زیرساختی سپال‌یار است (مانند کد 060 با پیام «سیستم قادر به سرویس‌دهی نیست»). برای عیب‌یابی، مقدارهای operation_time و ref_id را ذخیره کنید.

Best Practices

Ensure the image is high resolution and without glare.
Store request references for troubleshooting.
Validate the extracted data on your side before proceeding.

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

پارامتر	نوع	اجباری	توضیحات	مثال
`national_card_image`	File	اجباری	تصویر کارت ملی (فرمت‌های مجاز: JPG، PNG). اعتبارسنجی: حداکثر حجم 2 مگابایت. تصویر باید واضح باشد.	`km.jpg`

مثال‌های کد

Python Example

Example using Python requests library.

import requests

url = "https://inquiry.sepal.ir/api/services/national-card-ocr/"
headers = {
    "Authorization": "Token YOUR_AUTH_TOKEN",
    "X-Unique-Code": "YOUR_UNIQUE_CODE",
}
files = {
    "national_card_image": ("km.jpg", open("km.jpg", "rb"), "image/jpeg"),
}

response = requests.post(url, headers=headers, files=files)
print(response.json())

cURL Example

Command-line cURL example.

curl -X POST "https://inquiry.sepal.ir/api/services/national-card-ocr/" \
  -H "Authorization: Token YOUR_AUTH_TOKEN" \
  -H "X-Unique-Code: YOUR_UNIQUE_CODE" \
  -F "national_card_image=@km.jpg;type=image/jpeg"

فرمت پاسخ

200

پاسخ موفق

پاسخ موفق شامل داده‌های استخراج شده از کارت ملی (خروجی اصلی سپال‌یار در کلید response_data قرار می‌گیرد).

ساختار پاسخ:

{
  "amount": "integer",
  "success": "boolean",
  "request_ref": "string",
  "error_message": "null",
  "response_data": "object",
  "response_time_ms": "integer"
}

مثال پاسخ:

{
  "amount": 20000,
  "success": true,
  "request_ref": "c45cca4f5e614ec785ad514fcee31422",
  "error_message": null,
  "response_data": {
    "name": "رامین",
    "ref_id": "a0278953-34a4-4d76-873a-4aff873055e7",
    "last_name": "علاثی",
    "birth_date": "1379/05/14",
    "expire_date": "1401/06/13",
    "father_name": "تورج",
    "national_id": "4640229534",
    "operation_time": 1762961452558
  },
  "response_time_ms": 512
}

400

خطا

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

ساختار پاسخ:

{
  "error": {
    "errors": "list",
    "ref_id": "string",
    "operation_time": "integer"
  },
  "success": "boolean"
}

مثال پاسخ:

{
  "error": {
    "errors": [
      {
        "code": "1001",
        "message": "ارسال تصویر الزامی است."
      }
    ],
    "ref_id": "4d43a9dc-7cb1-4e61-8d10-4e2cdb2c9d23",
    "operation_time": 1762691215312
  },
  "success": false
}

422

خطا

تصویر توسط سپال‌یار قابل پردازش نیست.

ساختار پاسخ:

{
  "error": {
    "errors": "list",
    "ref_id": "string",
    "operation_time": "integer"
  },
  "success": "boolean"
}

مثال پاسخ:

{
  "error": {
    "errors": [
      {
        "code": "5001",
        "message": "تصویر کارت ملی خوانا نیست."
      }
    ],
    "ref_id": "7713c9e3-0b54-4a72-8a01-17fb37ee0ede",
    "operation_time": 1762691215312
  },
  "success": false
}