مستندات API استعلام

برای کسب‌وکارهایی که می‌خواهند استعلام را داخل محصول خودشان انجام دهند، نه اینکه کاربرشان را به سایت دیگری بفرستند. مثلاً تطبیق کد ملی با شمارهٔ موبایل در لحظهٔ ثبت‌نام، یا تبدیل کد پستی به نشانی در فرم سفارش.

حساب کسب‌وکار را خودتان در پنل می‌سازید، بی‌درنگ و بدون تأیید دستی، و کلید را هم خودتان می‌سازید و می‌چرخانید.

1. با شمارهٔ موبایل وارد می‌شوید و در پنل کسب‌وکار نام کسب‌وکار را ثبت می‌کنید. حساب همان لحظه ساخته می‌شود.
2. پنل را از همان صفحه شارژ می‌کنید، کمترین مبلغ ۱٬۰۰۰٬۰۰۰ تومان، و کلید می‌سازید. متن کلید فقط یک بار نشان داده می‌شود.
3. کلید را در هدر می‌گذارید و فراخوان می‌زنید.

کلید را در یکی از این دو هدر بفرستید، هر دو پذیرفته می‌شوند:

Authorization: Bearer ehr_live_…
# یا
X-API-Key: ehr_live_…

⚠️ کلید را هرگز در کد سمت مرورگر نگذارید. هر کسی که کلید را ببیند می‌تواند از موجودی شما خرج کند. اگر نشت کرد، از پنل باطلش کنید؛ ابطال بی‌درنگ اثر می‌کند.

اگر IP سرورتان ثابت است، هنگام ساخت کلید فهرست IP مجاز را پر کنید. خالی‌گذاشتنش یعنی کلید از هر جای دنیا کار می‌کند.

هر سرویس یک نشانی دارد و فقط POST می‌پذیرد. ورودی این سرویس‌ها کد ملی و شمارهٔ کارت است؛ فرستادنش در نشانی یعنی نشستنش در لاگ سرور، تاریخچهٔ مرورگر و هدر Referer، پس GET عمداً پشتیبانی نمی‌شود.

POST https://ehrazino.com/api/v1/{slug}/
Content-Type: application/json

سرویس‌هایی که تصویر یا ویدیو می‌گیرند، به‌جای JSON بدنهٔ multipart/form-data دارند؛ بخش «ارسال فایل» را ببینید.

اسلش پایانی را بگذارید. شکل بدون اسلش هم کار می‌کند، ولی شکل بالا شکل قطعی است و هیچ هدایتی نمی‌گیرد، و بعضی کتابخانه‌ها بدنهٔ POST را پس از هدایت دوباره نمی‌فرستند.

{
  "ok": true,
  "requestId": "req_1a2b3c…",
  "service": "sana-inquiry",
  "data": { … },
  "billing": { "amountRial": 51000, "balanceRial": 9949000 }
}

• data، نتیجهٔ استعلام. فیلدهای هر سرویس در صفحهٔ همان سرویس آمده‌اند. در سرویس‌های خواندن تصویر و احراز هویت، فقط فیلدهای همان جدول برمی‌گردد و تصویر چهره هرگز در پاسخ نیست.
• billing.amountRial، همان مبلغی که همین حالا کسر شد. صفر یعنی رایگان بود.
• requestId، برای پیگیری در پشتیبانی. نگهش دارید.

هر پاسخ ناموفق همین شکل را دارد و error.code ماشین‌خوان است. به کد تکیه کنید و نه به متن پیام؛ متن ممکن است بهتر شود.

{ "ok": false, "requestId": "req_…", "error": { "code": "insufficient_funds", "message": "…" } }

⚠️ not_found با HTTP ۲۰۰ برمی‌گردد و ok:false دارد. «رکوردی نیست» یک پاسخ معتبر است که ما بابتش به سرویس مرجع پول داده‌ایم، پس هزینه دارد، ولی ۴۰۴ نمی‌دهیم چون با «چنین سرویسی نداریم» قاطی می‌شود.

هر پاسخی که به مرحلهٔ تسویه رسیده باشد، چه موفق چه ناموفق، فیلد billing دارد و می‌گوید همین حالا چقدر کسر شد و موجودی‌تان چقدر مانده. نبودنِ این فیلد یعنی هیچ مبلغی جابه‌جا نشده؛ پس برای تطبیق حساب لازم نیست حدس بزنید.

curl

curl -X POST 'https://ehrazino.com/api/v1/sana-inquiry/' \
  -H 'Authorization: Bearer ehr_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"nationalCode":"0013542419","mobile":"09120000000"}'

PHP / وردپرس

$response = wp_remote_post( 'https://ehrazino.com/api/v1/sana-inquiry/', array(
    'timeout' => 30,
    'headers' => array(
        'Authorization' => 'Bearer ' . EHRAZINO_API_KEY,
        'Content-Type'  => 'application/json',
    ),
    'body' => wp_json_encode( array(
        'nationalCode' => $national_code,
        'mobile'       => $mobile,
    ) ),
) );

if ( is_wp_error( $response ) ) {
    // شبکه قطع بود، دوباره تلاش کنید.
    return;
}

$body = json_decode( wp_remote_retrieve_body( $response ), true );
if ( ! empty( $body['ok'] ) ) {
    // $body['data'] پاسخ استعلام است.
}

Node.js

const response = await fetch('https://ehrazino.com/api/v1/sana-inquiry/', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EHRAZINO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ nationalCode, mobile }),
});

const body = await response.json();
if (body.ok) {
  // body.data
}

Python

import os, requests

response = requests.post(
    "https://ehrazino.com/api/v1/sana-inquiry/",
    headers={"Authorization": f"Bearer {os.environ['EHRAZINO_API_KEY']}"},
    json={"nationalCode": national_code, "mobile": mobile},
    timeout=30,
)
body = response.json()
if body.get("ok"):
    data = body["data"]

⚠️ مهلت (timeout) را دست‌کم ۳۰ ثانیه بگذارید. برخی سرویس‌های مرجع کند پاسخ می‌دهند و مهلت کوتاه یعنی شما پاسخ را نمی‌بینید در حالی که صورتحسابش صادر شده. برای احراز هویت ویدئویی دست‌کم ۹۰ ثانیه: پردازش ویدیو تا یک دقیقه طول می‌کشد و بارگذاری خود ویدیو هم زمان می‌برد.

این سرویس‌ها تصویر یا ویدیو می‌گیرند: OCR چک صیادی، OCR کارت ملی، احراز هویت تصویری، احراز هویت ویدئویی. بدنه multipart/form-data است: هر فیلد متنی یک بخش متنی، و هر فایل یک بخش فایل با نامی که در جدول «سرویس‌ها و ورودی‌هایشان» با برچسب «فایل» آمده.

• هدر Content-Type را دستی ننویسید؛ کتابخانهٔ HTTP مرز بخش‌ها را خودش می‌سازد و هدر دستی آن را می‌شکند.
• نوع فایل از روی محتوای خودش سنجیده می‌شود و نه پسوند یا نوع اعلام‌شده. تصویر: JPEG، PNG یا WebP. ویدیو: MP4، MOV، WebM یا MKV. سقف حجم هر فایل کنار نامش آمده.
• فایل نامعتبر، بدنهٔ JSON به‌جای multipart و حجم بیش از سقف، پیش از هر تماسی رد می‌شوند و هزینه‌ای ندارند.
• فایل فقط تا پایان همان درخواست در حافظه است و هیچ‌جا ذخیره نمی‌شود. در گزارش پنل از آن فقط نوع و حجم می‌ماند.
• تصویری که پردازش شود ولی خوانا نباشد، کد unreadable می‌گیرد و چون پردازش انجام شده، هزینه دارد. متن پیام علت را می‌گوید و می‌شود همان را به کاربر نشان داد.
• در احراز تصویری و ویدئویی، سریال کارت ملی (nationalCardSerial، ده نویسهٔ پشت کارت) کنار تاریخ تولد الزامی است؛ سامانهٔ مرجع بی آن تصویر ثبت احوال را نمی‌دهد. بی سریال، درخواست همین‌جا و رایگان رد می‌شود.
• در احراز هویت، «تطبیق ندارد» خودش یک نتیجه است و با ok: true و verified: false برمی‌گردد؛ هزینه دارد. پیدا نشدن هویت در ثبت احوال کد identity_not_found دارد و رایگان است.

curl

curl -X POST 'https://ehrazino.com/api/v1/national-card-ocr/' \
  -H 'Authorization: Bearer ehr_live_…' \
  -F 'front=@card-front.jpg' \
  -F 'back=@card-back.jpg'

PHP

$ch = curl_init( 'https://ehrazino.com/api/v1/national-card-ocr/' );
curl_setopt_array( $ch, array(
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => array( 'Authorization: Bearer ' . EHRAZINO_API_KEY ),
    // آرایه با CURLFile یعنی multipart؛ Content-Type را خود cURL می‌سازد.
    CURLOPT_POSTFIELDS     => array(
        'front' => new CURLFile( $front_path, 'image/jpeg' ),
    ),
) );
$body = json_decode( curl_exec( $ch ), true );
curl_close( $ch );

Python

import os, requests

with open("selfie.jpg", "rb") as face:
    response = requests.post(
        "https://ehrazino.com/api/v1/face-verification/",
        headers={"Authorization": f"Bearer {os.environ['EHRAZINO_API_KEY']}"},
        data={
            "nationalCode": national_code,
            "birthDate": "1370/01/05",
            "nationalCardSerial": card_serial,
        },
        files={"face": face},
        timeout=30,
    )
body = response.json()
if body.get("ok") and body["data"]["verified"]:
    ...

Node.js

import { readFile } from 'node:fs/promises';

const form = new FormData();
form.append('nationalCode', nationalCode);
form.append('birthDate', '1370/01/05');
form.append('nationalCardSerial', cardSerial);
form.append('line', 'یک دو سه چهار پنج');
form.append('video', new Blob([await readFile('kyc.mp4')], { type: 'video/mp4' }), 'kyc.mp4');

const response = await fetch('https://ehrazino.com/api/v1/liveness/', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.EHRAZINO_API_KEY}` },
  body: form,
  signal: AbortSignal.timeout(90_000),
});
const body = await response.json();

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

• مبلغ پیش از تماس با سرویس مرجع از موجودی شما قفل می‌شود و پس از پاسخ تسویه. اگر پاسخی نیاید، کل مبلغ همان لحظه برمی‌گردد.
• فراخوانی که به سرویس مرجع نرسد، موجودی ناکافی، ورودی نامعتبر، قطعی، هیچ هزینه‌ای ندارد.
• کف شارژ حساب ۱٬۰۰۰٬۰۰۰ تومان است.

پیش‌فرض ۶۰ فراخوان در دقیقه برای هر سرویس است. عبور از آن پاسخ 429 با هدر Retry-After می‌گیرد و هیچ هزینه‌ای ندارد. اگر حجم بیشتری لازم دارید، بگویید تا برای حساب شما بالا ببریم.

⚠️ فراخوان ۴۲۹ در سابقهٔ مصرف شما ثبت نمی‌شود. سقف نرخ برای ریختن بار است و نوشتن یک ردیف به‌ازای هر درخواست ردشده، همان چیزی را می‌سازد که قرار بود جلویش را بگیرد. اگر شمارش لازم دارید، سمت خودتان پاسخ‌های ۴۲۹ را بشمارید.

درخواست و پاسخ هر فراخوان ذخیره می‌شود تا در پنل کسب‌وکارتان، کنار همان ردیف، ببینیدش و به‌صورت JSON دانلودش کنید. برای عیب‌یابی همین لازم است: بدون آن، «کدام ورودی غلط بود» فقط با تیکت درمی‌آمد.

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

سیاست حریم خصوصی و اقدامات امنیتی

حسابتان را همین حالا بسازید؛ تا رسیدن به اولین فراخوان موفق چند دقیقه بیشتر فاصله ندارید.

ساخت حساب کسب‌وکار

سؤالی دارید یا حجم ماهانه‌تان بالاست و تعرفهٔ اختصاصی می‌خواهید؟ با ما تماس بگیرید.