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

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

شروع سریع

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

نشانی پایه

https://gereh.virgule.studio/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.virgule.studio/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
}

هزینه

خطاها

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

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

نمونه کد

PHP

$ch = curl_init("https://gereh.virgule.studio/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.virgule.studio/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.virgule.studio/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);

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

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