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

Bank Card OCR API

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

POST /api/services/bank-card-ocr/
نیاز به احراز هویت Token 30 requests/minute

مستندات

Overview

Overview

The Bank Card OCR API accepts an image of an Iranian bank card and returns extracted textual data (such as full card number) using Sepal Yar's OCR service.

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 the bank card image:

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

Response Format

Response Format

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

Error Handling

Error Handling

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

Best Practices

Best Practices

  • Ensure the card image is high resolution, without glare, and the full card is visible.
  • Store request references for troubleshooting and audit.
  • Validate the extracted card number on your side before using it in sensitive flows.

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

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

مثال‌های کد

Python Example

Example using Python requests library.

import requests

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

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

Example using C# HttpClient with multipart/form-data.

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

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");

        using var form = new MultipartFormDataContent();
        using var fileStream = File.OpenRead("card.jpg");
        var fileContent = new StreamContent(fileStream);
        fileContent.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg");
        form.Add(fileContent, "bank_card_image", "card.jpg");

        var response = await client.PostAsync("https://inquiry.sepal.ir/api/services/bank-card-ocr/", form);
        var result = await response.Content.ReadAsStringAsync();
        Console.WriteLine(result);
    }
}
PHP Example

Example using PHP cURL file upload.

<?php

$url = "https://inquiry.sepal.ir/api/services/bank-card-ocr/";

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

$postFields = [
    "bank_card_image" => new CURLFile("card.jpg", "image/jpeg", "card.jpg")
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postFields);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>
cURL Example

Command-line cURL example.

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

فرمت پاسخ

200
پاسخ موفق

پاسخ موفق شامل شماره کارت بانکی و اطلاعات متادیتای سپال‌یار (operation_time و ref_id) در کلید response_data.

ساختار پاسخ:
{
  "amount": "integer",
  "success": "boolean",
  "request_ref": "string",
  "error_message": "null",
  "response_data": {
    "ref_id": "string",
    "card_number": "string",
    "operation_time": "integer"
  },
  "response_time_ms": "integer"
}
مثال پاسخ:
{
  "amount": 15000,
  "success": true,
  "request_ref": "c45cca4f5e614ec785ad514fcee31422",
  "error_message": null,
  "response_data": {
    "ref_id": "fae9e82c-0db1-403a-84e8-514972a78c55",
    "card_number": "5892101543218776",
    "operation_time": 1763284900697
  },
  "response_time_ms": 420
}
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
}
400
خطا

خطای دسترسی یا خطای کسب‌و‌کاری از سمت سپال‌یار (برگشت داده شده به همان شکل).

ساختار پاسخ:
{
  "error": {
    "errors": "list",
    "ref_id": "string",
    "operation_time": "integer"
  },
  "success": "boolean"
}
مثال پاسخ:
{
  "error": {
    "errors": [
      {
        "code": "1027",
        "message": "دسترسی این برنامه برای بانک درخواست شده برقرار نمی باشد"
      }
    ],
    "ref_id": "4cad244b-8073-45b5-908d-80b29722f181",
    "operation_time": 1763284888408
  },
  "success": false
}