ناوبری سریع

APIهای مرتبط

Bank Card OCR API

این API تصویر کارت بانکی را دریافت کرده و شماره …

National Card OCR API

این API تصویر کارت ملی را دریافت کرده و اطلاعات …

Video Authentication API

این API ویدیو احراز هویت کاربر را دریافت کرده و …

National Code Birthday Match API

This API verifies whether an Iranian national code matches a …

Compare Images API

این API دو تصویر چهره را دریافت می‌کند و آن‌ها …

Selfie National Code Birthday Match API

این API تصویر سلفی کاربر را به همراه کد ملی …

POST احراز هویت

Mobile National Code Match API

This API endpoint allows you to verify if a mobile number matches a given national code. The service requires authentication and deducts credits from your wallet upon successful verification.

POST /api/services/mobile-national-code-match/

نیاز به احراز هویت Token 100 requests/minute

مستندات

Overview

The Mobile National Code Match API allows you to verify if a mobile number matches a given Iranian national code. This service is useful for identity verification and fraud prevention.

When you make a successful API call, the service will:

Verify the mobile number format
Verify the national code format
Check if they match
Deduct credits from your wallet
Return a unique request reference number

Authentication

This API requires authentication using a Token-based authentication system.

How to authenticate:

Obtain your API token from the admin panel
Include the token in the Authorization header
Format: Authorization: Token YOUR_AUTH_TOKEN

Example:

Authorization: Token abc123def456ghi789

If authentication fails, you will receive a 401 Unauthorized response.

Request Format

All requests must be sent as POST requests with JSON payload.

Required Headers:

Authorization: Token YOUR_AUTH_TOKEN
Content-Type: application/json

Request Body:

The request body must be a JSON object containing:

mobile (string, required): Mobile number in Iranian format (09...) or international format (+98 or 0098)
national_code (string, required): Iranian national code (10 digits)

Example Request:

{
  "mobile": "09123456789",
  "national_code": "1234567890"
}

Response Format

All responses are returned as JSON objects.

Success Response (200 OK):

When the request is successful, you will receive a response containing:

success: Boolean indicating success
request_ref: Unique reference number for this request
amount: Amount deducted from your wallet (in Rials)
response_data: The actual response data from the service
response_time_ms: Response time in milliseconds
error_message: null for successful requests

Error Response:

When an error occurs, you will receive a response containing:

success: false
error: Object containing error details
- code: Error code
- message: Error message
- details: Additional error details (optional)

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

200 OK: Request successful
400 Bad Request: Invalid parameters provided
401 Unauthorized: Authentication failed or missing
402 Payment Required: Insufficient wallet balance
500 Internal Server Error: Server encountered an error

Common Error Codes:

INVALID_PARAMETERS: One or more parameters are invalid
AUTHENTICATION_ERROR: Authentication token is missing or invalid
INSUFFICIENT_BALANCE: Not enough credits in wallet
SERVICE_ERROR: Service encountered an internal error
SERVICE_NOT_FOUND: Service not found or inactive

Always check the success field in the response to determine if the request was successful.

Rate Limiting

This API has rate limiting to ensure fair usage:

Limit: 100 requests per minute
Per IP: Rate limits are applied per IP address

If you exceed the rate limit, you will receive a 429 Too Many Requests response.

Best Practices:

Implement exponential backoff for retries
Cache responses when appropriate
Monitor your request rate

Best Practices

To ensure optimal usage of this API:

Validate inputs client-side: Validate mobile and national code formats before sending requests
Handle errors gracefully: Always check the response status and handle errors appropriately
Store request references: Save the request_ref for tracking and support purposes
Monitor your balance: Keep track of your wallet balance to avoid 402 errors
Use HTTPS: Always use HTTPS in production to protect sensitive data
Implement retry logic: For transient errors (5xx), implement retry logic with exponential backoff

پارامترهای درخواست

پارامتر	نوع	اجباری	توضیحات	مثال
`mobile`	String	اجباری	Mobile number in Iranian format (starting with 09) or international format (+98 or 0098). Spaces and dashes will be automatically removed. اعتبارسنجی: Must start with 09, +98, or 0098. Max length: 20 characters.	`09123456789`
`national_code`	String	اجباری	Iranian national code (10 digits). Must contain only digits. اعتبارسنجی: Must be exactly 10 digits. Only numeric characters allowed.	`1234567890`

مثال‌های کد

Python Example

Example using Python requests library

import requests

url = "https://inquiry.sepal.ir/api/services/mobile-national-code-match/"
headers = {
    "Authorization": "Token YOUR_AUTH_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "mobile": "09123456789",
    "national_code": "1234567890"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

C# Example

Example using C# HttpClient

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Token YOUR_AUTH_TOKEN");
        
        var data = new
        {
            mobile = "09123456789",
            national_code = "1234567890"
        };
        
        var json = JsonSerializer.Serialize(data);
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        
        var response = await client.PostAsync(
            "https://inquiry.sepal.ir/api/services/mobile-national-code-match/",
            content
        );
        
        var result = await response.Content.ReadAsStringAsync();
        Console.WriteLine(result);
    }
}

PHP Example

Example using PHP cURL

<?php

$url = "https://inquiry.sepal.ir/api/services/mobile-national-code-match/";
$data = [
    "mobile" => "09123456789",
    "national_code" => "1234567890"
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Token YOUR_AUTH_TOKEN",
    "Content-Type: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

cURL Example

Example using cURL command line

curl -X POST "https://inquiry.sepal.ir/api/services/mobile-national-code-match/" \
  -H "Authorization: Token YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mobile": "09123456789",
    "national_code": "1234567890"
  }'

فرمت پاسخ

200

پاسخ موفق

Successful response when the mobile number matches the national code.

ساختار پاسخ:

{
  "amount": "integer",
  "success": "boolean",
  "request_ref": "string",
  "error_message": "null",
  "response_data": "object",
  "response_time_ms": "integer"
}

مثال پاسخ:

{
  "amount": 1000,
  "success": true,
  "request_ref": "ABC123XYZ456DEF789GHI012JKL345MNO",
  "error_message": null,
  "response_data": {
    "match": true,
    "message": "Mobile number matches the national code"
  },
  "response_time_ms": 250
}

401

خطا

Unauthorized - Authentication token is missing or invalid.

ساختار پاسخ:

{
  "error": {
    "code": "string (optional)",
    "errors": "list (optional)",
    "details": "object (optional)",
    "message": "string"
  },
  "success": "boolean"
}

مثال پاسخ:

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Authentication credentials were not provided."
  },
  "success": false
}

402

خطا

Payment Required - Insufficient wallet balance.

ساختار پاسخ:

{
  "error": {
    "code": "string (optional)",
    "errors": "list (optional)",
    "details": "object (optional)",
    "message": "string"
  },
  "success": "boolean"
}

مثال پاسخ:

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient wallet balance."
  },
  "success": false
}

400

خطا

Sepal Yar validation error (returned as-is).

ساختار پاسخ:

{
  "error": {
    "code": "string (optional)",
    "errors": "list (optional)",
    "details": "object (optional)",
    "message": "string"
  },
  "success": "boolean"
}

مثال پاسخ:

{
  "error": {
    "errors": [
      {
        "code": "81007",
        "message": "اطلاعات هویتی یافت نشد."
      }
    ]
  },
  "success": false
}