Техническая документация по API проверки паспортов РФ

Опубликовано: 14.09.2025

Техническая документация: Эндпоинт /api/passport

1. Введение и назначение

Эндпоинт /api/passport предоставляет программный интерфейс для проверки действительности паспорта гражданина Российской Федерации. Сервис предназначен для интеграции в различные информационные системы, где требуется валидация паспортных данных, например, при проведении KYC (Know Your Customer) процедур, оформлении финансовых продуктов или регистрации пользователей.

Метод выполняет запрос к базе данных недействительных паспортов (базе ФМС/ГУВМ МВД) и возвращает структурированную информацию о статусе документа, его выдаче и наличии в списке недействительных.

Базовый URL: https://api.example.com/api/passport HTTP Метод: GET

2. Подробное описание параметров запроса

Все параметры передаются в строке запроса (query string).

Параметр Тип Обязательный Описание Пример значения
api_key String Да Уникальный ключ доступа (API Key), выданный поставщиком сервиса. Используется для аутентификации и авторизации запроса. a1b2c3d4-e5f6-7890-abcd-ef1234567890
ser String Да Серия проверяемого паспорта. Состоит из 4 цифр. 4501
nom String Да Номер проверяемого паспорта. Состоит из 6 цифр. 123456

3. Примеры использования

Пример успешного HTTP-запроса

GET /api/passport?api_key=your_actual_api_key&ser=4501&nom=123456 HTTP/1.1
Host: api.example.com

Примеры кода на различных языках программирования

Python (используя библиотеку requests)

import requests

url = "https://api.example.com/api/passport"
params = {
    "api_key": "your_actual_api_key",
    "ser": "4501",
    "nom": "123456"
}

response = requests.get(url, params=params)
data = response.json()

if data['success']:
    passport_status = data['passport_check'][1]['passport']
    if passport_status == '0':
        print("Паспорт недействителен.")
    elif passport_status == '2':
        print("Паспорт с такой серией не выдавался.")
    else:
        print("Статус неизвестен.")
else:
    print("Произошла ошибка на уровне API.")

JavaScript (Fetch API)

const apiKey = 'your_actual_api_key';
const ser = '4501';
const nom = '123456';
const url = `https://api.example.com/api/passport?api_key=${apiKey}&ser=${ser}&nom=${nom}`;

fetch(url)
  .then(response => response.json())
  .then(data => {
    if (data.success) {
      const info = data.passport_check.find(item => item.info).info;
      console.log(info);
    } else {
      console.error('API request failed');
    }
  })
  .catch(error => console.error('Error:', error));

PHP

<?php
$api_key = 'your_actual_api_key';
$ser = '4501';
$nom = '123456';
$url = "https://api.example.com/api/passport?api_key=$api_key&ser=$ser&nom=$nom";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

if ($data['success']) {
    $dop = $data['passport_check'][2]['dop'];
    foreach ($dop as $item) {
        echo key($item) . ': ' . current($item) . "\n";
    }
} else {
    echo "Ошибка запроса.";
}
?>

Java (используя HttpURLConnection)

import java.net.HttpURLConnection;
import java.net.URL;
import java.io.BufferedReader;
import java.io.InputStreamReader;

public class PassportCheck {
    public static void main(String[] args) {
        try {
            String apiKey = "your_actual_api_key";
            String ser = "4501";
            String nom = "123456";
            String urlStr = "https://api.example.com/api/passport?api_key=" + apiKey + "&ser=" + ser + "&nom=" + nom;

            URL url = new URL(urlStr);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("GET");

            BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
            String inputLine;
            StringBuffer content = new StringBuffer();
            while ((inputLine = in.readLine()) != null) {
                content.append(inputLine);
            }
            in.close();
            conn.disconnect();

            // Здесь следует использовать библиотеку JSON (например, Gson, Jackson) для парсинга content.toString()
            System.out.println(content.toString());

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Go

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "log"
)

type Response struct {
    PassportCheck []map[string]interface{} `json:"passport_check"`
    Success       bool                     `json:"success"`
}

func main() {
    apiKey := "your_actual_api_key"
    ser := "4501"
    nom := "123456"
    url := fmt.Sprintf("https://api.example.com/api/passport?api_key=%s&ser=%s&nom=%s", apiKey, ser, nom)

    resp, err := http.Get(url)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()

    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }

    var data Response
    err = json.Unmarshal(body, &data)
    if err != nil {
        log.Fatal(err)
    }

    if data.Success {
        fmt.Println("Запрос выполнен успешно.")
        // Дальнейшая обработка data.PassportCheck
    }
}

1C (на примере встроенного языка 1С)

// Внимание: Пример упрощен. Реализация может отличаться в зависимости от версии платформы 1С.
Запрос = Новый HTTPЗапрос();
URL = "https://api.example.com/api/passport?api_key=your_actual_api_key&ser=4501&nom=123456";

Соединение = Новый HTTPСоединение("api.example.com", 443, "", "", Новый ЗащищенноеСоединениеOpenSSL()); // Используем порт 443 для HTTPS
Ответ = Соединение.Получить(URL);

Если Ответ.КодСостояния = 200 Тогда
    ЧтениеJSON = Новый ЧтениеJSON;
    ЧтениеJSON.ПотокВвода = Новый ПотокВводаИзСтроки(Ответ.ПолучитьТелоКакСтроку());
    Результат = ПрочитатьJSON(ЧтениеJSON);
    // Далее разбираем структуру Результат
Иначе
    Сообщить("Ошибка HTTP: " + Ответ.КодСостояния);
КонецЕсли;

4. Обработка ошибок и интерпретация ответов

Ответ всегда возвращается с HTTP статусом 200 OK, если запрос корректно достиг сервера. Критичность ошибок и статус операции определяются по полю success и структуре объекта passport_check.

Ключевые поля ответа:

  • success: true - Индикатор того, что запрос был корректно обработан API. Важно: true не означает, что паспорт действителен, а лишь то, что сервис дал ответ на запрос.

  • passport_check[1].passport - Основной код статуса паспорта.

    • "0" - Паспорт найден в базе недействительных паспортов.
    • "1" - Паспорт не найден в базе недействительных паспортов.
    • "2" - Паспорт с указанной серией не выдавался на территории РФ.
    • "3" - Ошибка валидации (неправильно введены данные).

  • passport_check[3].info - Текстовое описание результата проверки, предназначенное для разработчика или логирования.

  • passport_check[2].dop - Массив с дополнительной информацией о выдаче паспорта (место и дата), актуальной только для статуса "0".

Логика обработки на стороне клиента:

  1. Проверить response.success == true.
  2. Извлечь код статуса passport_status = response.passport_check[1].passport.
  3. В зависимости от кода принять решение:
    • "0" - Паспорт недействителен. Не пропускать пользователя.
    • "1" - Паспорт не найден в БД недействительных паспортов. Пропустить пользователя.
    • "2" - Серия паспорта не существует. Не пропускать пользователя.
    • "3" - Ошибка ввода. Запросить данные у пользователя повторно.
    • Любое другое значение - Логировать и обработать как неизвестную ошибку.

5. Best Practices (Рекомендации по использованию)

  1. Безопасность API ключа: Никогда не храните API ключ в клиентском коде (frontend, мобильные приложения). Все запросы должны выполняться с вашего серверного backend.
  2. Валидация на стороне клиента: Перед отправкой запроса обязательно проверяйте формат серии (4 цифры) и номера (6 цифр) на стороне клиента, чтобы избежать лишних вызовов API и ошибок типа "3".
  3. Кэширование: Рассмотрите возможность кэширования результатов проверки на короткое время (несколько часов) на своей стороне для повторяющихся запросов на одни и те же паспортные данные, чтобы снизить нагрузку и затраты.
  4. Асинхронная обработка: Выполняйте запросы асинхронно, чтобы не блокировать основной поток вашего приложения, особенно в веб-интерфейсах.
  5. Обработка исключений: Всегда обрабатывайте возможные сетевые ошибки, таймауты и исключения, связанные с парсингом JSON.
  6. Логирование: Ведите логи всех запросов и ответов (замаскировав при этом api_key в логах) для отладки и анализа проблем.

6. Ограничения и лимиты

  • Частота запросов (Rate Limiting): Доступ к API обычно ограничен по количеству запросов в секунду/минуту/сутки. Точные лимиты указываются в договоре с поставщиком сервиса. Превышение лимита приводит к ответу с HTTP кодом 429 Too Many Requests.
  • Точность данных: Сервис оперирует данными из официальной базы, но возможны задержки в обновлении информации. Поставщик услуги не гарантирует 100% точность и актуальность данных на момент запроса.
  • Тарификация: Обращение к API, как правило, является платным. Стоимость одного запроса или пакета запросов уточняется у поставщика услуги.