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

از اولین درخواست تا مدیریت خطا، با نمونه کد.

REST · JSONنسخه ۱

API استعلام گره یک REST API ساده است: یک درخواست POST با ورودی‌های JSON می‌فرستید و پاسخ را در قالب JSON می‌گیرید. همه مبالغ به تومان است.

شروع سریع

در گره ثبت‌نام کنید و احراز هویت حساب را کامل کنید.
در پنل › API استعلام دکمه «فعال‌سازی API» را بزنید؛ API Key و API Password ساخته می‌شود.
با حالت sandbox (رایگان) برنامه را توسعه دهید، سپس کیف پول را شارژ کنید و درخواست واقعی بفرستید.

نشانی پایه

https://gereh.net/api/inquiry/v1

احراز هویت

کلید و رمز را در سربرگ‌های X-Api-Key و X-Api-Password بفرستید (یا با HTTP Basic به شکل key:password). رمز را فقط سمت سرور نگه دارید؛ هرگز در اپ موبایل یا کد مرورگر قرار ندهید.

export GEREH_KEY="..."        # API Key
export GEREH_PASSWORD="..."   # API Password
curl -s https://gereh.net/api/inquiry/v1/balance -H "X-Api-Key: $GEREH_KEY" -H "X-Api-Password: $GEREH_PASSWORD"

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

حالت آزمایشی (sandbox)

سربرگ X-Sandbox: 1 را بفرستید تا پاسخ نمونه با همان ساختار واقعی برگردد. این درخواست‌ها رایگان هستند، به سامانه مرجع نمی‌روند و در گزارش با برچسب sandbox دیده می‌شوند. در sandbox ورودی‌ای که با 0000 تمام شود پاسخ «یافت نشد» و ورودی‌ای که با 9999 تمام شود خطای سرویس‌دهنده برمی‌گرداند تا مسیرهای خطا را هم تست کنید.

قالب پاسخ

{
  "ok": true,
  "trackId": "INQ-M1X2Y3Z4AB",
  "service": "cards",
  "status": "success",
  "result": { "bank": "بانک ملی", "owner": "علی محمدی" },
  "charged": 572,
  "balance": 1249428
}

فیلد	توضیح
`status`	`success` (پیدا شد) یا `not_found` (پاسخ قطعی: وجود ندارد)
`result`	داده‌های استعلام؛ در `not_found` برابر `null`
`charged`	مبلغی که برای این درخواست کسر شد
`trackId`	کد پیگیری؛ در گزارش پنل و برای پشتیبانی

هزینه

نتیجه	هزینه
موفق	قیمت سرویس
یافت نشد	قیمت سرویس
ورودی نامعتبر	رایگان
خطای سامانه مرجع	رایگان (مبلغ خودکار برمی‌گردد)

خطاها

{ "ok": false, "error": { "code": "invalid_input", "message": "…", "fields": { "card": "شماره کارت: شماره کارت معتبر نیست" } } }

HTTP	code	معنی
400	`invalid_input`	ورودی نامعتبر (رایگان)؛ جزئیات در `fields`
401	`unauthorized`	کلید یا رمز نادرست
402	`insufficient_balance`	موجودی کیف پول کافی نیست
403	`access_required`	سرویس نیاز به تأیید کاربرد دارد
403	`ip_not_allowed`	درخواست از IP مجاز نیامده
404	`unknown_service`	شناسه سرویس اشتباه است
429	`rate_limited`	بیش از ۶۰۰ درخواست در دقیقه
502	`upstream_error`	سامانه مرجع پاسخ نداد (رایگان)؛ کمی بعد دوباره تلاش کنید

مسیرهای عمومی

متد	مسیر	توضیح
GET	`/balance`	موجودی کیف پول
GET	`/services`	فهرست سرویس‌ها، قیمت و وضعیت دسترسی شما
POST	`/{service}`	استعلام

نمونه کد

PHP

$ch = curl_init("https://gereh.net/api/inquiry/v1/cards");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["X-Api-Key: " . getenv("GEREH_KEY"), "X-Api-Password: " . getenv("GEREH_PASSWORD"), "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["card" => "6037991234567893"]),
]);
$res = json_decode(curl_exec($ch), true);
echo $res["ok"] ? $res["result"]["owner"] : $res["error"]["message"];

Python

import os, requests
r = requests.post("https://gereh.net/api/inquiry/v1/cards",
    headers={"X-Api-Key": os.environ["GEREH_KEY"], "X-Api-Password": os.environ["GEREH_PASSWORD"]},
    json={"card": "6037991234567893"}, timeout=20)
data = r.json()
print(data["result"]["owner"] if data["ok"] else data["error"]["message"])

Node.js

const res = await fetch("https://gereh.net/api/inquiry/v1/cards", {
  method: "POST",
  headers: { "X-Api-Key": process.env.GEREH_KEY, "X-Api-Password": process.env.GEREH_PASSWORD, "Content-Type": "application/json" },
  body: JSON.stringify({ card: "6037991234567893" }),
});
const data = await res.json();
console.log(data.ok ? data.result.owner : data.error.message);

هویت و ثبت احوال

استعلام ثبت احوال نسخه ۲ — `identity_v2`

با کد ملی و تاریخ تولد، نام، نام خانوادگی، نام پدر، جنسیت و وضعیت حیات فرد را از ثبت احوال برمی‌گرداند. قیمت: ۶٬۹۵۰ تومان · نیاز به تأیید کاربرد

پارامتر	توضیح	نمونه
`nationalCode`	کد ملی	`0012345679`
`birthDate`	تاریخ تولد (شمسی)	`1370/05/12`

curl -s -X POST https://gereh.net/api/inquiry/v1/identity_v2 \
  -H "X-Api-Key: $GEREH_KEY" -H "X-Api-Password: $GEREH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"nationalCode":"0012345679","birthDate":"1370/05/12"}'

{
  "ok": true,
  "trackId": "INQ-M1X2Y3Z4AB",
  "service": "identity_v2",
  "status": "success",
  "result": {
    "firstName": "علی",
    "lastName": "محمدی",
    "fatherName": "حسن",
    "gender": "male",
    "alive": true,
    "birthDate": "1370/05/12"
  },
  "charged": 6950,
  "balance": 1250000
}

تطابق نام با کد ملی — `identity_match`

بررسی می‌کند نام و نام خانوادگی واردشده با کد ملی و تاریخ تولد در ثبت احوال یکی است یا نه؛ بدون برگرداندن اطلاعات شخص. قیمت: ۳٬۹۵۰ تومان · نیاز به تأیید کاربرد

پارامتر	توضیح	نمونه
`nationalCode`	کد ملی	`0012345679`
`birthDate`	تاریخ تولد (شمسی)	`1370/05/12`
`firstName`	نام	`علی`
`lastName`	نام خانوادگی	`محمدی`

curl -s -X POST https://gereh.net/api/inquiry/v1/identity_match \
  -H "X-Api-Key: $GEREH_KEY" -H "X-Api-Password: $GEREH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"nationalCode":"0012345679","birthDate":"1370/05/12","firstName":"علی","lastName":"محمدی"}'

{
  "ok": true,
  "trackId": "INQ-M1X2Y3Z4AB",
  "service": "identity_match",
  "status": "success",
  "result": {
    "firstNameMatch": true,
    "lastNameMatch": true
  },
  "charged": 3950,
  "balance": 1250000
}

شاهکار لایت — `shahkar_lite`

تطابق مالکیت سیم‌کارت با کد ملی (سامانه شاهکار)؛ برای ثبت‌نام امن و جلوگیری از حساب‌های جعلی. قیمت: ۱٬۴۳۰ تومان · نیاز به تأیید کاربرد

پارامتر	توضیح	نمونه
`mobile`	شماره موبایل	`09121234567`
`nationalCode`	کد ملی	`0012345679`

curl -s -X POST https://gereh.net/api/inquiry/v1/shahkar_lite \
  -H "X-Api-Key: $GEREH_KEY" -H "X-Api-Password: $GEREH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"mobile":"09121234567","nationalCode":"0012345679"}'

{
  "ok": true,
  "trackId": "INQ-M1X2Y3Z4AB",
  "service": "shahkar_lite",
  "status": "success",
  "result": {
    "matched": true
  },
  "charged": 1430,
  "balance": 1250000
}

بانکی

استعلام شماره شبا — `ibans`

نام صاحب حساب، بانک و وضعیت حساب (فعال، مسدود، راکد) را پیش از واریز برمی‌گرداند. قیمت: ۵۷۲ تومان

پارامتر	توضیح	نمونه
`iban`	شماره شبا	`IR820540102680020817909002`

curl -s -X POST https://gereh.net/api/inquiry/v1/ibans \
  -H "X-Api-Key: $GEREH_KEY" -H "X-Api-Password: $GEREH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"iban":"IR820540102680020817909002"}'

{
  "ok": true,
  "trackId": "INQ-M1X2Y3Z4AB",
  "service": "ibans",
  "status": "success",
  "result": {
    "bank": "بانک سامان",
    "bankCode": "056",
    "owners": [
      "علی محمدی"
    ],
    "depositStatus": "active",
    "deposit": "1268002081790900"
  },
  "charged": 572,
  "balance": 1250000
}

استعلام کارت بانکی — `cards`

نام دارنده کارت و بانک صادرکننده را برمی‌گرداند؛ برای نمایش نام گیرنده پیش از کارت‌به‌کارت. قیمت: ۵۷۲ تومان

پارامتر	توضیح	نمونه
`card`	شماره کارت	`6037991234567893`

curl -s -X POST https://gereh.net/api/inquiry/v1/cards \
  -H "X-Api-Key: $GEREH_KEY" -H "X-Api-Password: $GEREH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"card":"6037991234567893"}'

{
  "ok": true,
  "trackId": "INQ-M1X2Y3Z4AB",
  "service": "cards",
  "status": "success",
  "result": {
    "bank": "بانک صادرات",
    "owner": "علی محمدی"
  },
  "charged": 572,
  "balance": 1250000
}

تبدیل شماره کارت به شبا — `cards_iban`

شماره شبای حساب متصل به کارت را همراه با نام صاحب حساب برمی‌گرداند. قیمت: ۶۴۴ تومان

پارامتر	توضیح	نمونه
`card`	شماره کارت	`6037991234567893`

curl -s -X POST https://gereh.net/api/inquiry/v1/cards_iban \
  -H "X-Api-Key: $GEREH_KEY" -H "X-Api-Password: $GEREH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"card":"6037991234567893"}'

{
  "ok": true,
  "trackId": "INQ-M1X2Y3Z4AB",
  "service": "cards_iban",
  "status": "success",
  "result": {
    "iban": "IR820540102680020817909002",
    "bank": "بانک سامان",
    "owner": "علی محمدی"
  },
  "charged": 644,
  "balance": 1250000
}

تبدیل شماره کارت به حساب — `cards_deposit`

شماره حساب متصل به کارت و بانک آن را برمی‌گرداند. قیمت: ۶۴۴ تومان

پارامتر	توضیح	نمونه
`card`	شماره کارت	`6037991234567893`

curl -s -X POST https://gereh.net/api/inquiry/v1/cards_deposit \
  -H "X-Api-Key: $GEREH_KEY" -H "X-Api-Password: $GEREH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"card":"6037991234567893"}'

{
  "ok": true,
  "trackId": "INQ-M1X2Y3Z4AB",
  "service": "cards_deposit",
  "status": "success",
  "result": {
    "deposit": "1268002081790900",
    "bank": "بانک سامان",
    "owner": "علی محمدی"
  },
  "charged": 644,
  "balance": 1250000
}

تبدیل شماره حساب به شبا — `deposit_iban`

با کد بانک و شماره حساب، شماره شبای معتبر و نام صاحب حساب را برمی‌گرداند. قیمت: ۶۴۴ تومان

پارامتر	توضیح	نمونه
`bankCode`	کد بانک (سه رقم)	`056`
`deposit`	شماره حساب	`1268002081790900`

curl -s -X POST https://gereh.net/api/inquiry/v1/deposit_iban \
  -H "X-Api-Key: $GEREH_KEY" -H "X-Api-Password: $GEREH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"bankCode":"056","deposit":"1268002081790900"}'

{
  "ok": true,
  "trackId": "INQ-M1X2Y3Z4AB",
  "service": "deposit_iban",
  "status": "success",
  "result": {
    "iban": "IR820540102680020817909002",
    "owner": "علی محمدی"
  },
  "charged": 644,
  "balance": 1250000
}

تطابق شبا با کد ملی — `iban_owner`

بررسی می‌کند حساب متعلق به همین کد ملی است؛ برای تسویه امن با کاربران و فروشندگان. قیمت: ۱٬۱۵۰ تومان

پارامتر	توضیح	نمونه
`iban`	شماره شبا	`IR820540102680020817909002`
`nationalCode`	کد ملی	`0012345679`
`birthDate`	تاریخ تولد (شمسی)	`1370/05/12`

curl -s -X POST https://gereh.net/api/inquiry/v1/iban_owner \
  -H "X-Api-Key: $GEREH_KEY" -H "X-Api-Password: $GEREH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"iban":"IR820540102680020817909002","nationalCode":"0012345679","birthDate":"1370/05/12"}'

{
  "ok": true,
  "trackId": "INQ-M1X2Y3Z4AB",
  "service": "iban_owner",
  "status": "success",
  "result": {
    "matched": true
  },
  "charged": 1150,
  "balance": 1250000
}

تطابق کارت با کد ملی — `card_owner`

بررسی می‌کند کارت متعلق به همین کد ملی است؛ جلوی پرداخت با کارت دیگران را می‌گیرد. قیمت: ۱٬۱۵۰ تومان

پارامتر	توضیح	نمونه
`card`	شماره کارت	`6037991234567893`
`nationalCode`	کد ملی	`0012345679`
`birthDate`	تاریخ تولد (شمسی)	`1370/05/12`

curl -s -X POST https://gereh.net/api/inquiry/v1/card_owner \
  -H "X-Api-Key: $GEREH_KEY" -H "X-Api-Password: $GEREH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"card":"6037991234567893","nationalCode":"0012345679","birthDate":"1370/05/12"}'

{
  "ok": true,
  "trackId": "INQ-M1X2Y3Z4AB",
  "service": "card_owner",
  "status": "success",
  "result": {
    "matched": true
  },
  "charged": 1150,
  "balance": 1250000
}

احراز هویت دیجیتال

خواندن کارت ملی (OCR) — `national_card_ocr`

از عکس کارت ملی هوشمند، کد ملی، نام، نام خانوادگی، تاریخ تولد و تاریخ انقضا را می‌خواند. قیمت: ۱٬۹۹۰ تومان

پارامتر	توضیح	نمونه
`image`	تصویر روی کارت (base64)	`data:image/jpeg;base64,…`

curl -s -X POST https://gereh.net/api/inquiry/v1/national_card_ocr \
  -H "X-Api-Key: $GEREH_KEY" -H "X-Api-Password: $GEREH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"image":"data:image/jpeg;base64,…"}'

{
  "ok": true,
  "trackId": "INQ-M1X2Y3Z4AB",
  "service": "national_card_ocr",
  "status": "success",
  "result": {
    "nationalCode": "0012345679",
    "firstName": "علی",
    "lastName": "محمدی",
    "birthDate": "1370/05/12",
    "expiry": "1410/05/12"
  },
  "charged": 1990,
  "balance": 1250000
}

تطابق چهره با کارت ملی — `face_match`

عکس سلفی را با تصویر ثبت‌شده در ثبت احوال مقایسه و درصد شباهت و نتیجه زنده‌بودن را برمی‌گرداند. قیمت: ۳٬۹۰۰ تومان · نیاز به تأیید کاربرد

پارامتر	توضیح	نمونه
`nationalCode`	کد ملی	`0012345679`
`birthDate`	تاریخ تولد (شمسی)	`1370/05/12`
`image`	عکس سلفی (base64)	`data:image/jpeg;base64,…`

curl -s -X POST https://gereh.net/api/inquiry/v1/face_match \
  -H "X-Api-Key: $GEREH_KEY" -H "X-Api-Password: $GEREH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"nationalCode":"0012345679","birthDate":"1370/05/12","image":"data:image/jpeg;base64,…"}'

{
  "ok": true,
  "trackId": "INQ-M1X2Y3Z4AB",
  "service": "face_match",
  "status": "success",
  "result": {
    "matched": true,
    "similarity": 0.94,
    "liveness": true
  },
  "charged": 3900,
  "balance": 1250000
}

کسب‌وکار و چک

استعلام اشخاص حقوقی — `company`

نام ثبتی، شماره و تاریخ ثبت، نوع شرکت، وضعیت (فعال، منحل…) و نشانی را با شناسه ملی برمی‌گرداند. قیمت: ۲٬۴۰۰ تومان

پارامتر	توضیح	نمونه
`companyId`	شناسه ملی شرکت	`10101234567`

curl -s -X POST https://gereh.net/api/inquiry/v1/company \
  -H "X-Api-Key: $GEREH_KEY" -H "X-Api-Password: $GEREH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"companyId":"10101234567"}'

{
  "ok": true,
  "trackId": "INQ-M1X2Y3Z4AB",
  "service": "company",
  "status": "success",
  "result": {
    "name": "شرکت نمونه فناوران",
    "registrationNumber": "123456",
    "registrationDate": "1395/02/20",
    "type": "سهامی خاص",
    "status": "active",
    "address": "تهران، ونک"
  },
  "charged": 2400,
  "balance": 1250000
}

استعلام کد اقتصادی — `economic_code`

ثبت‌نام در نظام مالیاتی و ارزش افزوده را برای صدور فاکتور رسمی و سامانه مودیان بررسی می‌کند. قیمت: ۱٬۵۰۰ تومان

پارامتر	توضیح	نمونه
`companyId`	شناسه ملی یا کد ملی	`10101234567`

curl -s -X POST https://gereh.net/api/inquiry/v1/economic_code \
  -H "X-Api-Key: $GEREH_KEY" -H "X-Api-Password: $GEREH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"companyId":"10101234567"}'

{
  "ok": true,
  "trackId": "INQ-M1X2Y3Z4AB",
  "service": "economic_code",
  "status": "success",
  "result": {
    "name": "شرکت نمونه فناوران",
    "economicCode": "411111111111",
    "vatRegistered": true
  },
  "charged": 1500,
  "balance": 1250000
}

استعلام رنگ چک صیادی — `sayad_cheque`

وضعیت اعتباری صادرکننده چک (سفید، زرد، نارنجی، قهوه‌ای، قرمز) را از سامانه صیاد برمی‌گرداند. قیمت: ۲٬۹۰۰ تومان · نیاز به تأیید کاربرد

پارامتر	توضیح	نمونه
`nationalCode`	کد ملی	`0012345679`

curl -s -X POST https://gereh.net/api/inquiry/v1/sayad_cheque \
  -H "X-Api-Key: $GEREH_KEY" -H "X-Api-Password: $GEREH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"nationalCode":"0012345679"}'

{
  "ok": true,
  "trackId": "INQ-M1X2Y3Z4AB",
  "service": "sayad_cheque",
  "status": "success",
  "result": {
    "color": "white",
    "colorName": "سفید",
    "bouncedCount": 0
  },
  "charged": 2900,
  "balance": 1250000
}

نشانی و ارتباط

تشخیص اپراتور موبایل — `mobile_operator`

اپراتور (همراه اول، ایرانسل، رایتل…) و نوع سیم‌کارت را برای ارسال پیامک یا شارژ مستقیم تشخیص می‌دهد. قیمت: ۱۲۰ تومان

پارامتر	توضیح	نمونه
`mobile`	شماره موبایل	`09121234567`

curl -s -X POST https://gereh.net/api/inquiry/v1/mobile_operator \
  -H "X-Api-Key: $GEREH_KEY" -H "X-Api-Password: $GEREH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"mobile":"09121234567"}'

{
  "ok": true,
  "trackId": "INQ-M1X2Y3Z4AB",
  "service": "mobile_operator",
  "status": "success",
  "result": {
    "operator": "MCI",
    "operatorName": "همراه اول",
    "ported": false
  },
  "charged": 120,
  "balance": 1250000
}

استعلام کد پستی — `postal_code`

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

پارامتر	توضیح	نمونه
`postalCode`	کد پستی	`1434863111`

curl -s -X POST https://gereh.net/api/inquiry/v1/postal_code \
  -H "X-Api-Key: $GEREH_KEY" -H "X-Api-Password: $GEREH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"postalCode":"1434863111"}'

{
  "ok": true,
  "trackId": "INQ-M1X2Y3Z4AB",
  "service": "postal_code",
  "status": "success",
  "result": {
    "province": "تهران",
    "city": "تهران",
    "street": "خیابان کارگر شمالی",
    "plate": "۱۲",
    "floor": "۳",
    "address": "تهران، خیابان کارگر شمالی، پلاک ۱۲، طبقه ۳"
  },
  "charged": 990,
  "balance": 1250000
}

نکته‌های ورودی

اعداد فارسی و عربی، فاصله و خط تیره خودکار پاک می‌شوند (۶۰۳۷-۹۹۱۲-... پذیرفته است).
شبا را با یا بدون IR بفرستید.
تاریخ تولد شمسی و به شکل 1370/05/12 است.
تصویرها به‌صورت data URL (JPEG، PNG یا WebP) و کمتر از ۲ مگابایت.

شروع سریع

نشانی پایه

احراز هویت

حالت آزمایشی (sandbox)

قالب پاسخ

هزینه

خطاها

مسیرهای عمومی

نمونه کد

PHP

Python

Node.js

هویت و ثبت احوال

استعلام ثبت احوال نسخه ۲ — identity_v2

تطابق نام با کد ملی — identity_match

شاهکار لایت — shahkar_lite

بانکی

استعلام شماره شبا — ibans

استعلام کارت بانکی — cards

تبدیل شماره کارت به شبا — cards_iban

تبدیل شماره کارت به حساب — cards_deposit

تبدیل شماره حساب به شبا — deposit_iban

تطابق شبا با کد ملی — iban_owner

تطابق کارت با کد ملی — card_owner