openapi: 3.0.2
info:
  title: API проверки паспорта на действительность
  description: Сервис позволяет проверить действительность паспорта по его серии, номеру, имени и фамилии владельца. Все запросы требуют указания ключа доступа (`key`).
  version: 1.0.0
servers:
  - url: https://parser-api.com/parser/passport_api
paths:
  /:
    get:
      summary: Проверка действительности паспорта
      description: Для проверки действительности паспорта используйте следующий запрос.
      parameters:
        - name: key
          in: query
          required: true
          schema:
            type: string
          description: Ключ доступа (обязательный).
        - name: passport_series
          in: query
          required: true
          schema:
            type: string
          description: Серия паспорта (обязательный).
        - name: passport_number
          in: query
          required: true
          schema:
            type: string
          description: Номер паспорта (обязательный).
        - name: first_name
          in: query
          required: true
          schema:
            type: string
          description: Имя владельца паспорта (обязательный).
        - name: last_name
          in: query
          required: true
          schema:
            type: string
          description: Фамилия владельца паспорта (обязательный).
      responses:
        '200':
          description: Успешная валидация и обработка запроса.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: integer
                    description: Флаг успешности выполнения запроса. При получении 0 сделайте повторный запрос сразу же или через несколько минут.
                    example: 1
                  status:
                    type: string
                    enum:
                      - VALID
                      - NOT_VALID
                      - NOT_FOUND
                    description: Статус паспорта. Возможные значения: VALID - Действителен, NOT_VALID - Недействителен, NOT_FOUND - Не найден.
                    example: VALID
              examples:
                validPassport:
                  value:
                    success: 1
                    status: VALID
        '400':
          description: Ошибка валидации запроса.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Подробное описание ошибки.
                    example: Missing first_name in input params
                  error_code:
                    type: integer
                    description: Код ошибки.
                    example: 40001
        '403':
          description: Ограничение доступа к сервису.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Подробное описание ошибки.
                    example: Invalid access key
                  error_code:
                    type: integer
                    description: Код ошибки.
                    example: 40301
              examples:
                invalidKey:
                  value:
                    error: Invalid access key
                    error_code: 40301
                expiredSubscription:
                  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