openapi: 3.0.2
info:
  title: API parser-api.com проверка водительского удостоверения
  description: Сервис предназначен для получения информации о водительских удостоверениях и истории лишений права управления транспортными средствами.
  version: 1.0.0
servers:
  - url: https://parser-api.com/parser/driver_api

paths:
  /:
    get:
      summary: Получение информации о водительском удостоверении
      description: Для получения информации о водительском удостоверении и истории лишений права управления ТС используйте следующий запрос с указанием серии, номера и даты выдачи.
      parameters:
        - name: key
          in: query
          required: true
          schema:
            type: string
          description: Ключ доступа к API.
        - name: num
          in: query
          required: true
          schema:
            type: string
          description: Серия и номер водительского удостоверения (без пробелов).
          example: "5034401752"
        - name: date
          in: query
          required: true
          schema:
            type: string
            pattern: '^\d{2}\.\d{2}\.\d{4}$'
          description: Дата выдачи водительского удостоверения (формат DD.MM.YYYY).
          example: "31.10.2017"
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: integer
                    description: Флаг успешного выполнения запроса (1 - успех, 0 - не удалось получить информацию от источника).
                  document:
                    type: object
                    description: Информация о найденном водительском удостоверении.
                    properties:
                      dob:
                        type: string
                        format: date
                        description: Дата рождения владельца.
                      categories:
                        type: string
                        description: Открытые категории.
                      date_from:
                        type: string
                        format: date
                        description: Дата начала действия удостоверения.
                      date_to:
                        type: string
                        format: date
                        description: Дата окончания действия удостоверения.
                      comment:
                        type: string
                        nullable: true
                        description: Комментарий (при наличии).
                      status:
                        type: string
                        enum: [Действует, Недействителен]
                        description: Статус удостоверения.
                  decision:
                    type: object
                    nullable: true
                    description: Информация о лишении права управления ТС (при наличии).
                    properties:
                      bplace:
                        type: string
                        description: Место вынесения постановления.
                      date:
                        type: string
                        format: date
                        description: Дата вынесения постановления о лишении.
                      period:
                        type: string
                        description: Период лишения (в месяцах).
                      state:
                        type: string
                        enum:
                          - Вынесено постановление о лишении права управления ТС
                          - Постановление о лишении права управления ТС вступило в законную силу
                          - Исчисление срока лишения права управления ТС прервано
                          - Поступление информации об уплате штрафа
                          - Поступление информации об уплате штрафа (от банка)
                          - Начато исчисление срока лишения права управления
                          - Окончено исчисление срока лишения права управления (возвращено ВУ)
                          - Проведение проверки знаний ПДД
                        description: Текущее состояние лишения.
              example:
                success: 1
                document:
                  dob: "1979-11-11"
                  categories: "В, В1, М"
                  date_from: "2017-10-31"
                  date_to: "2027-10-31"
                  comment: "Срок действия водительского удостоверения продлен в соответствии с постановлением Правительства Российской Федерации от 09.04.2022 № 626 на 3 года."
                  status: "Действует"
                decision:
                  bplace: "г. Москва"
                  date: "2020-05-15"
                  period: "18"
                  state: "Постановление о лишении права управления ТС вступило в законную силу"
        '400':
          description: Ошибка валидации запроса
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Сообщение об ошибке.
                  error_code:
                    type: integer
                    description: Код ошибки (всегда 40001 для ошибок валидации).
              examples:
                EmptyNum:
                  value:
                    error: "Empty num"
                    error_code: 40001
                EmptyDate:
                  value:
                    error: "Empty date"
                    error_code: 40001
        '403':
          $ref: '#/components/responses/AccessError'

components:
  schemas: {}
  responses:
    AccessError:
      description: Ошибка ограничения доступа
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              error_code:
                type: integer
          examples:
            InvalidAccessKey:
              value:
                error: "Invalid access key"
                error_code: 40301
            SubscriptionExpired:
              value:
                error: "The subscription period has expired"
                error_code: 40302
            InvalidIP:
              value:
                error: "Invalid IP"
                error_code: 40303
            DayLimitExceeded:
              value:
                error: "Day limit of requests exceeded"
                error_code: 40304
            MonthLimitExceeded:
              value:
                error: "Month limit of requests exceeded"
                error_code: 40305