a apifast.ir
Endpoints خطاها پشتیبانی دریافت کلید
REST API · نسخه ۱

مستندات apifast.ir

زیرساخت سریع و امن برای استعلام شاهکار، اطلاعات هویتی و خلافی خودرو و موتورسیکلت — همگی از طریق یک REST API ساده.

SLA ۹۹.۹٪
پاسخ < ۲ ثانیه
TLS 1.3
JSON / REST

۰۱ معرفی

apifast.ir یک Gateway استعلامی برای سامانه‌های KYC، فین‌تک، نئوبانک، بیمه و خدمات خودرویی است. سه سرویس اصلی به‌صورت یکپارچه و با ساختار پاسخ واحد ارائه می‌شود.

شاهکار

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

اطلاعات هویتی

نام، نام خانوادگی، نام پدر و وضعیت حیات با کد ملی و تاریخ تولد.

خلافی خودرو و موتور

استعلام خلافی به‌صورت دو مرحله‌ای با تأیید پیامکی مالک پلاک.

کلید اختصاصی

API Key با محدودیت IP و سقف نرخ قابل تنظیم برای هر مشتری.

۰۲ آدرس پایه

تمام درخواست از طریق HTTPS به آدرس پایه زیر ارسال می شوند.

Base URL
https://api.apifast.ir
نکته

مثلاً /v1/inquiry/shahkar یعنی https://api.apifast.ir/v1/inquiry/shahkar.

۰۳ احراز هویت

هر درخواست باید کلید API را در هدر Authorization همراه داشته باشد. کلید توسط تیم apifast.ir صادر و در پنل اختصاصی شما قابل مشاهده است.

Bearer Token (پیشنهادی)

HTTP Header
Authorization: Bearer YOUR_API_KEY
محافظت از کلید

API Key معادل گذرواژه است. هرگز در سمت کلاینت (مرورگر، اپ موبایل، مخزن عمومی) قرار ندهید. در صورت لو رفتن، فوراً از طریق پشتیبانی کلید را Rotate کنید.

۰۴ محدودیت نرخ درخواست

پیش‌فرض هر کلید ۱۰۰ درخواست در دقیقه است و قابل افزایش بنا به درخواست. در پاسخ هر فراخوانی هدرهای زیر نیز ارسال می‌شوند:

هدرتوضیح
X-RateLimit-Limitحداکثر تعداد درخواست در دقیقه
X-RateLimit-Remainingتعداد درخواست باقی‌مانده در پنجره فعلی
X-RateLimit-ResetUNIX timestamp زمان ریست شمارنده
Retry-After(در پاسخ ۴۲۹) ثانیه‌های باقی‌مانده تا تلاش بعدی

۰۵ استعلام شاهکار

بررسی تطابق شماره موبایل و کد ملی از سامانه‌ی رسمی شاهکار.

POST /v1/inquiry/shahkar روی https://api.apifast.ir

پارامترهای بدنه

فیلدنوعوضعیتتوضیح
phoneNumberstringالزامیشماره موبایل ۱۱ رقمی (مثلاً 09123456789)
nationalIdstringالزامیکد ملی ۱۰ رقمی

نمونه درخواست

cURL
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   تطابق تأیید شد

JSON
{
  "message": "عملیات با موفقیت انجام شد.",
  "data": { "status": "MATCHED" },
  "timestamp": "2026-05-29T13:16:38+03:30"
}

200 OK   عدم تطابق

JSON
{
  "message": "عدم تطابق اطلاعات",
  "data": { "status": "UNMATCHED" },
  "code": "UNMATCHED",
  "errors": null,
  "timestamp": "2026-05-29T13:16:38+03:30"
}
تشخیص نتیجه

مقدار data.status را بررسی کنید: "MATCHED" تطابق دارد، "UNMATCHED" تطابق ندارد.

۰۶ استعلام اطلاعات هویتی

دریافت اطلاعات کامل هویتی شامل نام، نام خانوادگی، نام پدر و وضعیت حیات با کد ملی و تاریخ تولد.

POST /v1/inquiry/nid روی https://api.apifast.ir

پارامترهای بدنه

فیلدنوعوضعیتتوضیح
nationalCodestringالزامیکد ملی ۱۰ رقمی
birthDatestringالزامیتاریخ تولد شمسی به فرمت YYYYMMDD (مثلاً 13560101)

نمونه درخواست

cURL
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   اطلاعات یافت شد

JSON
{
  "message": "عملیات با موفقیت انجام شد.",
  "data": {
    "nationalCode": "0012345678",
    "firstName":   "حسین",
    "lastName":    "محمدی",
    "fatherName":  "حسن",
    "birthDate":   "13560101",
    "alive":       true,
    "fullName":    "حسین محمدی"
  },
  "timestamp": "2026-05-29T13:16:38+03:30"
}

فیلدهای پاسخ موفق

فیلدنوعتوضیح
nationalCodestringکد ملی
firstNamestringنام
lastNamestringنام خانوادگی
fatherNamestringنام پدر
birthDatestringتاریخ تولد شمسی (YYYYMMDD)
alivebooleanوضعیت حیات (true = در قید حیات)
fullNamestringنام و نام خانوادگی کامل

200 OK   اطلاعات یافت نشد

JSON
{
  "message": "اطلاعات هویتی پیدا نشد یا تاریخ تولد با کد ملی همخوانی ندارد",
  "data": null,
  "code": "NOT_FOUND",
  "errors": null,
  "timestamp": "2026-05-29T13:16:38+03:30"
}

۰۷ استعلام خلافی خودرو و موتورسیکلت

استعلام خلافی به‌صورت دو مرحله‌ای انجام می‌شود: مرحله اول یک کد تأیید به شماره موبایل مالک پلاک ارسال می‌گردد و مرحله دوم با ارسال آن کد، نتیجه‌ی استعلام بازگردانده می‌شود.

POST /v1/inquiry/violation روی https://api.apifast.ir

قواعد فرمت پلاک

پلاک خودرو

پلاک خودرو باید با کلمه‌ی ایران شروع شود:

Format
ایران {کد ایران 2 رقم} - {3 رقم وسط} {حرف} {2 رقم اول}

نمونه‌های معتبر: ایران 35 - 123 ط 77 یا ایران ۳۵ – ۱۲۳ ط ۷۷

پلاک معلولین (ویلچر)

برای ورود علامت ویلچر کافی‌ست کاربر کلمه‌ی معلولین را به‌جای حرف وسط بنویسد. مثال: ایران 35 - 123 معلولین 77

پلاک موتورسیکلت

۳ رقم + جداکننده (فاصله، _ یا -) + ۵ رقم:

Format
155 87695
۱

درخواست کد تأیید

ابتدا بدنه‌ی درخواست را تنها با فیلد plateNumber ارسال کنید. در پاسخ، کد تأیید به شماره موبایل مالک پلاک ارسال خواهد شد.

نمونه — خودرو

cURL
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
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   پاسخ موفق مرحله ۱

JSON
{
  "message": "کد تایید به شماره موبایل مالک پلاک ارسال شد.",
  "data": {
    "step":        "verify_code_required",
    "vehicleType": "car"
  },
  "timestamp": "2026-01-15T10:00:00+00:00"
}
۲

ارسال کد تأیید و دریافت خلافی

پس از دریافت پیامک، همان درخواست را به‌همراه فیلد verifyCode دوباره ارسال کنید تا اطلاعات خلافی بازگردد.

cURL
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   پاسخ موفق مرحله ۲

JSON
{
  "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"
}

فیلدهای پاسخ موفق

فیلدنوعتوضیح
vehicleTypestringنوع وسیله نقلیه: car یا motorcycle
plateCharstringمتن کامل پلاک به‌صورت رسمی
priceStatusstringوضعیت قبض خلافی
pageCountintegerتعداد صفحات قبض
paperIdstringشناسه قبض
paymentIdstringشناسه پرداخت
warningPriceintegerمبلغ ریز خلافی (ریال)
inquirePriceintegerمبلغ کل خلافی (ریال)
ejrInquireNostringشماره استعلام اجرائیات
اعتبار کد تأیید

کد تأیید برای مدت محدودی معتبر است. در صورت انقضا، مرحله ۱ را تکرار کنید تا کد جدیدی صادر شود.

۰۸ ساختار یکپارچه پاسخ

تمام پاسخ‌های API از ساختار زیر پیروی می‌کنند:

پاسخ موفق

JSON
{
  "message": "عملیات با موفقیت انجام شد.",
  "data":    { ... },
  "timestamp": "2026-05-29T13:16:38+03:30"
}

پاسخ ناموفق

JSON
{
  "message":  "متن خطا به فارسی",
  "data":     null,
  "code":     "ERROR_CODE",
  "errors":   null,
  "timestamp": "2026-05-29T13:16:38+03:30"
}
فیلدتوضیح
messageپیام قابل نمایش به کاربر (فارسی)
dataداده پاسخ — در صورت موفقیت پر، در صورت خطا null
codeکد خطا (فقط در پاسخ‌های ناموفق)
errorsجزئیات خطا (در صورت وجود)
timestampزمان پاسخ به فرمت ISO 8601

۰۹ کدهای خطا

HTTPcodeتوضیح
400INVALID_JSONبدنه‌ی JSON معتبر نیست
401MISSING_API_KEYهدر API Key ارسال نشده
401INVALID_API_KEYAPI Key معتبر نیست
403ACCOUNT_DISABLEDحساب کاربری غیرفعال است
403IP_NOT_ALLOWEDIP درخواست در لیست مجاز نیست
404NOT_FOUNDمسیر یا اطلاعات یافت نشد
422INVALID_PHONEفرمت شماره موبایل اشتباه است
422INVALID_NATIONAL_IDکد ملی معتبر نیست
422MISSING_BIRTH_DATEتاریخ تولد ارسال نشده
422INVALID_BIRTH_DATEفرمت تاریخ تولد اشتباه است (باید YYYYMMDD)
422INVALID_PLATEفرمت پلاک معتبر نیست
422INVALID_VERIFY_CODEکد تأیید نادرست یا منقضی است
429RATE_LIMIT_EXCEEDEDعبور از سقف نرخ درخواست
200UNMATCHED(فقط شاهکار) موبایل و کد ملی تطابق ندارند
502UPSTREAM_ERRORخطا در ارتباط با سرویس بالادست
503SERVICE_DISABLEDسرویس موقتاً غیرفعال است
500INTERNAL_ERRORخطای داخلی سرور

۱۰ نمونه کد در زبان‌های مختلف

نمونه‌های زیر استعلام شاهکار را پیاده‌سازی می‌کنند؛ برای سایر endpointها کافی‌ست آدرس و بدنه را تغییر دهید.

cURL
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
<?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');
}
Python
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')}")
Node.js
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);
}
C#
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("تطابق تأیید شد");
}
Java
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());
Go
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