مستندات apifast.ir
زیرساخت سریع و امن برای استعلام شاهکار، اطلاعات هویتی و خلافی خودرو و موتورسیکلت — همگی از طریق یک REST API ساده.
۰۱ معرفی
apifast.ir یک Gateway استعلامی برای سامانههای KYC، فینتک، نئوبانک، بیمه و خدمات خودرویی است. سه سرویس اصلی بهصورت یکپارچه و با ساختار پاسخ واحد ارائه میشود.
شاهکار
تطابق شماره موبایل با کد ملی از سامانه رسمی شاهکار.
اطلاعات هویتی
نام، نام خانوادگی، نام پدر و وضعیت حیات با کد ملی و تاریخ تولد.
خلافی خودرو و موتور
استعلام خلافی بهصورت دو مرحلهای با تأیید پیامکی مالک پلاک.
کلید اختصاصی
API Key با محدودیت IP و سقف نرخ قابل تنظیم برای هر مشتری.
۰۲ آدرس پایه
تمام درخواست از طریق HTTPS به آدرس پایه زیر ارسال می شوند.
https://api.apifast.ir
مثلاً /v1/inquiry/shahkar یعنی https://api.apifast.ir/v1/inquiry/shahkar.
۰۳ احراز هویت
هر درخواست باید کلید API را در هدر Authorization همراه داشته باشد. کلید توسط تیم apifast.ir صادر و در پنل اختصاصی شما قابل مشاهده است.
Bearer Token (پیشنهادی)
Authorization: Bearer YOUR_API_KEY
API Key معادل گذرواژه است. هرگز در سمت کلاینت (مرورگر، اپ موبایل، مخزن عمومی) قرار ندهید. در صورت لو رفتن، فوراً از طریق پشتیبانی کلید را Rotate کنید.
۰۴ محدودیت نرخ درخواست
پیشفرض هر کلید ۱۰۰ درخواست در دقیقه است و قابل افزایش بنا به درخواست. در پاسخ هر فراخوانی هدرهای زیر نیز ارسال میشوند:
| هدر | توضیح |
|---|---|
X-RateLimit-Limit | حداکثر تعداد درخواست در دقیقه |
X-RateLimit-Remaining | تعداد درخواست باقیمانده در پنجره فعلی |
X-RateLimit-Reset | UNIX timestamp زمان ریست شمارنده |
Retry-After | (در پاسخ ۴۲۹) ثانیههای باقیمانده تا تلاش بعدی |
۰۵ استعلام شاهکار
بررسی تطابق شماره موبایل و کد ملی از سامانهی رسمی شاهکار.
https://api.apifast.ir
پارامترهای بدنه
| فیلد | نوع | وضعیت | توضیح |
|---|---|---|---|
phoneNumber | string | الزامی | شماره موبایل ۱۱ رقمی (مثلاً 09123456789) |
nationalId | string | الزامی | کد ملی ۱۰ رقمی |
نمونه درخواست
curl -X POST https://api.apifast.ir/v1/inquiry/shahkar \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"phoneNumber": "09123456789",
"nationalId": "1234567890"
}'
پاسخها
200 OK تطابق تأیید شد
{
"message": "عملیات با موفقیت انجام شد.",
"data": { "status": "MATCHED" },
"timestamp": "2026-05-29T13:16:38+03:30"
}
200 OK عدم تطابق
{
"message": "عدم تطابق اطلاعات",
"data": { "status": "UNMATCHED" },
"code": "UNMATCHED",
"errors": null,
"timestamp": "2026-05-29T13:16:38+03:30"
}
مقدار data.status را بررسی کنید: "MATCHED" تطابق دارد، "UNMATCHED" تطابق ندارد.
۰۶ استعلام اطلاعات هویتی
دریافت اطلاعات کامل هویتی شامل نام، نام خانوادگی، نام پدر و وضعیت حیات با کد ملی و تاریخ تولد.
https://api.apifast.ir
پارامترهای بدنه
| فیلد | نوع | وضعیت | توضیح |
|---|---|---|---|
nationalCode | string | الزامی | کد ملی ۱۰ رقمی |
birthDate | string | الزامی | تاریخ تولد شمسی به فرمت YYYYMMDD (مثلاً 13560101) |
نمونه درخواست
curl -X POST https://api.apifast.ir/v1/inquiry/nid \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"nationalCode": "0012345678",
"birthDate": "13560101"
}'
پاسخ موفق
200 OK اطلاعات یافت شد
{
"message": "عملیات با موفقیت انجام شد.",
"data": {
"nationalCode": "0012345678",
"firstName": "حسین",
"lastName": "محمدی",
"fatherName": "حسن",
"birthDate": "13560101",
"alive": true,
"fullName": "حسین محمدی"
},
"timestamp": "2026-05-29T13:16:38+03:30"
}
فیلدهای پاسخ موفق
| فیلد | نوع | توضیح |
|---|---|---|
nationalCode | string | کد ملی |
firstName | string | نام |
lastName | string | نام خانوادگی |
fatherName | string | نام پدر |
birthDate | string | تاریخ تولد شمسی (YYYYMMDD) |
alive | boolean | وضعیت حیات (true = در قید حیات) |
fullName | string | نام و نام خانوادگی کامل |
200 OK اطلاعات یافت نشد
{
"message": "اطلاعات هویتی پیدا نشد یا تاریخ تولد با کد ملی همخوانی ندارد",
"data": null,
"code": "NOT_FOUND",
"errors": null,
"timestamp": "2026-05-29T13:16:38+03:30"
}
۰۷ استعلام خلافی خودرو و موتورسیکلت
استعلام خلافی بهصورت دو مرحلهای انجام میشود: مرحله اول یک کد تأیید به شماره موبایل مالک پلاک ارسال میگردد و مرحله دوم با ارسال آن کد، نتیجهی استعلام بازگردانده میشود.
https://api.apifast.ir
قواعد فرمت پلاک
پلاک خودرو
پلاک خودرو باید با کلمهی ایران شروع شود:
ایران {کد ایران 2 رقم} - {3 رقم وسط} {حرف} {2 رقم اول}
نمونههای معتبر: ایران 35 - 123 ط 77 یا ایران ۳۵ – ۱۲۳ ط ۷۷
برای ورود علامت ویلچر کافیست کاربر کلمهی معلولین را بهجای حرف وسط بنویسد. مثال: ایران 35 - 123 معلولین 77
پلاک موتورسیکلت
۳ رقم + جداکننده (فاصله، _ یا -) + ۵ رقم:
155 87695
درخواست کد تأیید
ابتدا بدنهی درخواست را تنها با فیلد plateNumber ارسال کنید. در پاسخ، کد تأیید به شماره موبایل مالک پلاک ارسال خواهد شد.
نمونه — خودرو
curl -X POST https://api.apifast.ir/v1/inquiry/violation \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"plateNumber": "ایران 35 - 123 ط 77"
}'
نمونه — موتورسیکلت
curl -X POST https://api.apifast.ir/v1/inquiry/violation \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"plateNumber": "155 87695"
}'
200 OK پاسخ موفق مرحله ۱
{
"message": "کد تایید به شماره موبایل مالک پلاک ارسال شد.",
"data": {
"step": "verify_code_required",
"vehicleType": "car"
},
"timestamp": "2026-01-15T10:00:00+00:00"
}
ارسال کد تأیید و دریافت خلافی
پس از دریافت پیامک، همان درخواست را بههمراه فیلد verifyCode دوباره ارسال کنید تا اطلاعات خلافی بازگردد.
curl -X POST https://api.apifast.ir/v1/inquiry/violation \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"plateNumber": "ایران 35 - 123 ط 77",
"verifyCode": "54182"
}'
200 OK پاسخ موفق مرحله ۲
{
"message": "استعلام خلافی با موفقیت انجام شد.",
"data": {
"vehicleType": "car",
"plateChar": "شخصي ايران 35 ــ 123ط77",
"priceStatus": "1",
"pageCount": 0,
"paperId": "7598833500196",
"paymentId": "150007678",
"warningPrice": 1500000,
"inquirePrice": 1500000,
"ejrInquireNo": "1275988335"
},
"timestamp": "2026-01-15T10:00:00+00:00"
}
فیلدهای پاسخ موفق
| فیلد | نوع | توضیح |
|---|---|---|
vehicleType | string | نوع وسیله نقلیه: car یا motorcycle |
plateChar | string | متن کامل پلاک بهصورت رسمی |
priceStatus | string | وضعیت قبض خلافی |
pageCount | integer | تعداد صفحات قبض |
paperId | string | شناسه قبض |
paymentId | string | شناسه پرداخت |
warningPrice | integer | مبلغ ریز خلافی (ریال) |
inquirePrice | integer | مبلغ کل خلافی (ریال) |
ejrInquireNo | string | شماره استعلام اجرائیات |
کد تأیید برای مدت محدودی معتبر است. در صورت انقضا، مرحله ۱ را تکرار کنید تا کد جدیدی صادر شود.
۰۸ ساختار یکپارچه پاسخ
تمام پاسخهای API از ساختار زیر پیروی میکنند:
پاسخ موفق
{
"message": "عملیات با موفقیت انجام شد.",
"data": { ... },
"timestamp": "2026-05-29T13:16:38+03:30"
}
پاسخ ناموفق
{
"message": "متن خطا به فارسی",
"data": null,
"code": "ERROR_CODE",
"errors": null,
"timestamp": "2026-05-29T13:16:38+03:30"
}
| فیلد | توضیح |
|---|---|
message | پیام قابل نمایش به کاربر (فارسی) |
data | داده پاسخ — در صورت موفقیت پر، در صورت خطا null |
code | کد خطا (فقط در پاسخهای ناموفق) |
errors | جزئیات خطا (در صورت وجود) |
timestamp | زمان پاسخ به فرمت ISO 8601 |
۰۹ کدهای خطا
| HTTP | code | توضیح |
|---|---|---|
| 400 | INVALID_JSON | بدنهی JSON معتبر نیست |
| 401 | MISSING_API_KEY | هدر API Key ارسال نشده |
| 401 | INVALID_API_KEY | API Key معتبر نیست |
| 403 | ACCOUNT_DISABLED | حساب کاربری غیرفعال است |
| 403 | IP_NOT_ALLOWED | IP درخواست در لیست مجاز نیست |
| 404 | NOT_FOUND | مسیر یا اطلاعات یافت نشد |
| 422 | INVALID_PHONE | فرمت شماره موبایل اشتباه است |
| 422 | INVALID_NATIONAL_ID | کد ملی معتبر نیست |
| 422 | MISSING_BIRTH_DATE | تاریخ تولد ارسال نشده |
| 422 | INVALID_BIRTH_DATE | فرمت تاریخ تولد اشتباه است (باید YYYYMMDD) |
| 422 | INVALID_PLATE | فرمت پلاک معتبر نیست |
| 422 | INVALID_VERIFY_CODE | کد تأیید نادرست یا منقضی است |
| 429 | RATE_LIMIT_EXCEEDED | عبور از سقف نرخ درخواست |
| 200 | UNMATCHED | (فقط شاهکار) موبایل و کد ملی تطابق ندارند |
| 502 | UPSTREAM_ERROR | خطا در ارتباط با سرویس بالادست |
| 503 | SERVICE_DISABLED | سرویس موقتاً غیرفعال است |
| 500 | INTERNAL_ERROR | خطای داخلی سرور |
۱۰ نمونه کد در زبانهای مختلف
نمونههای زیر استعلام شاهکار را پیادهسازی میکنند؛ برای سایر endpointها کافیست آدرس و بدنه را تغییر دهید.
curl -X POST https://api.apifast.ir/v1/inquiry/shahkar \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"phoneNumber": "09123456789",
"nationalId": "1234567890"
}'
<?php
$ch = curl_init('https://api.apifast.ir/v1/inquiry/shahkar');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Authorization: Bearer YOUR_API_KEY',
],
CURLOPT_POSTFIELDS => json_encode([
'phoneNumber' => '09123456789',
'nationalId' => '1234567890',
]),
CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
if (($data['data']['status'] ?? null) === 'MATCHED') {
echo "تطابق تأیید شد";
} elseif (($data['code'] ?? null) === 'UNMATCHED') {
echo "عدم تطابق اطلاعات";
} else {
echo "خطا: " . ($data['message'] ?? 'unknown');
}
import requests
response = requests.post(
"https://api.apifast.ir/v1/inquiry/shahkar",
headers={
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_KEY",
},
json={
"phoneNumber": "09123456789",
"nationalId": "1234567890",
},
timeout=30,
)
data = response.json()
if data.get("data", {}).get("status") == "MATCHED":
print("تطابق تأیید شد")
elif data.get("code") == "UNMATCHED":
print("عدم تطابق اطلاعات")
else:
print(f"خطا: {data.get('message')}")
const response = await fetch("https://api.apifast.ir/v1/inquiry/shahkar", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_KEY",
},
body: JSON.stringify({
phoneNumber: "09123456789",
nationalId: "1234567890",
}),
});
const data = await response.json();
if (data?.data?.status === "MATCHED") {
console.log("تطابق تأیید شد");
} else if (data?.code === "UNMATCHED") {
console.log("عدم تطابق اطلاعات");
} else {
console.log("خطا:", data?.message);
}
using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_KEY");
var payload = new {
phoneNumber = "09123456789",
nationalId = "1234567890"
};
var response = await client.PostAsJsonAsync(
"https://api.apifast.ir/v1/inquiry/shahkar",
payload
);
var json = await response.Content.ReadAsStringAsync();
var data = JsonDocument.Parse(json).RootElement;
if (data.GetProperty("data").GetProperty("status").GetString() == "MATCHED") {
Console.WriteLine("تطابق تأیید شد");
}
import java.net.URI;
import java.net.http.*;
import java.time.Duration;
HttpClient client = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(10))
.build();
String body = """
{
"phoneNumber": "09123456789",
"nationalId": "1234567890"
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.apifast.ir/v1/inquiry/shahkar"))
.header("Content-Type", "application/json")
.header("Authorization", "Bearer YOUR_API_KEY")
.timeout(Duration.ofSeconds(30))
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = client.send(
request, HttpResponse.BodyHandlers.ofString()
);
System.out.println(response.body());
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
"time"
)
func main() {
payload, _ := json.Marshal(map[string]string{
"phoneNumber": "09123456789",
"nationalId": "1234567890",
})
req, _ := http.NewRequest("POST",
"https://api.apifast.ir/v1/inquiry/shahkar",
bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
client := &http.Client{Timeout: 30 * time.Second}
resp, _ := client.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
۱۱ SLA و امنیت
پایداری سرویس، حریم خصوصی و امنیت ارتباط برای ما در اولویت است.
۹۹.۹٪ Uptime
تضمین در دسترس بودن سرویس بهصورت ماهانه.
پاسخ < ۱.۵s
میانگین زمان پاسخ برای ۹۵٪ درخواستها.
CDN داخلی
پشتیبانی ArvanCloud با لتنسی پایین در سراسر ایران.
TLS 1.3
تمام ارتباطات با رمزنگاری end-to-end انجام میشود.
- IP Whitelist — بهازای هر کلید (شامل CIDR) قابل اعمال است.
- کلید ۲۵۶ بیت — تولید کلید با entropy کامل و امکان Rotate سریع.
- بدون cache — هیچ دادهای ذخیره نمیشود، هر استعلام بهصورت زنده انجام میشود.
- استانداردهای امنیتی — مطابق با الزامات NIST و بانک مرکزی.
هرگز API Key را در سمت کلاینت قرار ندهید · همیشه از Backend خود فراخوانی کنید · از IP Whitelist استفاده کنید · در صورت شک به نشت، فوراً Rotate کنید.
۱۲ پشتیبانی
تیم apifast.ir آمادهی پاسخگویی به سؤالات فنی و قراردادی است.
ایمیل
support@apifast.ir
چت آنلاین
از طریق وبسایت در ساعات اداری.
وبسایت
https://apifast.ir
وضعیت سرویس
status.apifast.ir