openapi: 3.0.2
info:
  title: API parser-api.com egrul.nalog.ru
  description: Документация API parser-api.com для получения сведений из ЕГРЮЛ/ЕГРИП и официальных выписок в формате PDF с портала ФНС России egrul.nalog.ru.
  version: 1.0.0
servers:
  - url: https://parser-api.com/parser/nalog_egrul_api
tags:
  - name: Основные запросы
    description: |
      Сервис поддерживает два основных типа запросов:
      1. **Поиск в ЕГРЮЛ/ЕГРИП** — поиск юридических лиц и индивидуальных предпринимателей по ИНН, ОГРН/ОГРНИП, наименованию организации или ФИО предпринимателя.
      2. **Скачивание выписки (PDF)** — получение официальной выписки из ЕГРЮЛ/ЕГРИП в формате PDF по ИНН или ОГРН.

      Все запросы требуют указания ключа доступа (`key`).
  - name: Справочные запросы
    description: |
      Справочные запросы предоставляют дополнительную информацию, необходимую для работы с основными запросами.

paths:
  /search:
    get:
      tags:
        - Основные запросы
      summary: Поиск в ЕГРЮЛ/ЕГРИП
      description: Выполняет поиск юридических лиц и индивидуальных предпринимателей по ИНН, ОГРН/ОГРНИП, наименованию организации или ФИО предпринимателя. Обязательно должен быть указан хотя бы один параметр — `inn`, `ogrn` или `name`. Общее число страниц возвращается в поле `pages`.
      parameters:
        - name: key
          in: query
          required: true
          schema:
            type: string
          description: Ключ доступа (обязательный)
        - name: inn
          in: query
          required: false
          schema:
            type: string
          description: ИНН (10 цифр для организации, 12 цифр для индивидуального предпринимателя)
        - name: ogrn
          in: query
          required: false
          schema:
            type: string
          description: ОГРН организации (13 цифр) или ОГРНИП индивидуального предпринимателя (15 цифр)
        - name: name
          in: query
          required: false
          schema:
            type: string
          description: Наименование организации или ФИО индивидуального предпринимателя
        - name: nameExact
          in: query
          required: false
          schema:
            type: boolean
          description: Искать по точному соответствию наименования юридического лица или фамилии, имени и отчества. Учитывается только вместе с параметром `name`
        - name: regionID
          in: query
          required: false
          schema:
            type: string
          description: Код региона для уточнения поиска. Если не указан, поиск выполняется по всем регионам. Допускается перечисление нескольких регионов через запятую, например `77,50`. Список регионов доступен через справочный запрос `/get_regions`
          example: "77,50"
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
          description: Номер страницы (нумерация с 1, по умолчанию 1)
      responses:
        '200':
          description: Успешный ответ.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Ошибка валидации запроса.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Ошибка доступа.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'

  /pdf_download:
    get:
      tags:
        - Основные запросы
      summary: Скачивание выписки из ЕГРЮЛ/ЕГРИП (PDF)
      description: |
        Возвращает официальную выписку из ЕГРЮЛ/ЕГРИП в формате PDF. Обязательно должен быть указан один из параметров — `inn` или `ogrn`.

        Содержимое файла возвращается в поле `pdf_content` в кодировке base64 — его нужно декодировать и сохранить под именем из поля `file_name`. Если запись по указанным реквизитам не найдена, запрос считается успешным, а поля `file_name` и `pdf_content` возвращаются пустыми.

        Выписка выдается строго по записи, реквизиты которой совпали с запрошенными — подстановка «похожей» организации не выполняется.
      parameters:
        - name: key
          in: query
          required: true
          schema:
            type: string
          description: Ключ доступа (обязательный)
        - name: inn
          in: query
          required: false
          schema:
            type: string
          description: ИНН (10 цифр для организации, 12 цифр для индивидуального предпринимателя)
        - name: ogrn
          in: query
          required: false
          schema:
            type: string
          description: ОГРН организации (13 цифр) или ОГРНИП индивидуального предпринимателя (15 цифр)
      responses:
        '200':
          description: Успешный ответ.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PdfDownloadResponse'
        '400':
          description: Ошибка валидации запроса.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Ошибка доступа.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'

  /get_regions:
    get:
      tags:
        - Справочные запросы
      summary: Получение списка регионов
      description: Возвращает справочник кодов регионов для параметра `regionID`. Список статичен — результат можно закэшировать на своей стороне. Запрос не обращается к источнику и не расходует оплаченный лимит.
      parameters:
        - name: key
          in: query
          required: true
          schema:
            type: string
          description: Ключ доступа (обязательный)
      responses:
        '200':
          description: Справочник регионов — код региона в качестве ключа, наименование в качестве значения.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                example:
                  "01": "Республика Адыгея"
                  "02": "Республика Башкортостан"
                  "77": "Москва"
                  "78": "Санкт-Петербург"
                  "99": "Байконур"
        '403':
          description: Ошибка доступа.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'

components:
  schemas:
    SearchResponse:
      type: object
      properties:
        success:
          type: integer
          description: Признак успешного выполнения запроса
          example: 1
        count:
          type: integer
          description: Общее количество найденных записей
          example: 1064
        available_count:
          type: integer
          description: Количество записей, доступных к выдаче (источник отдает не более 100000)
          example: 1064
        pages:
          type: integer
          description: Общее количество страниц
          example: 54
        page:
          type: integer
          description: Текущая страница
          example: 1
        items:
          type: array
          description: Найденные записи
          items:
            $ref: '#/components/schemas/SearchItem'

    SearchItem:
      type: object
      properties:
        type:
          type: string
          description: Вид записи
          enum:
            - organization
            - entrepreneur
          example: organization
        name:
          type: string
          nullable: true
          description: Полное наименование организации или ФИО индивидуального предпринимателя
          example: ПУБЛИЧНОЕ АКЦИОНЕРНОЕ ОБЩЕСТВО "ГАЗПРОМ"
        short_name:
          type: string
          nullable: true
          description: Сокращенное наименование, null для индивидуального предпринимателя
          example: ПАО "ГАЗПРОМ"
        inn:
          type: string
          nullable: true
          description: ИНН
          example: "7736050003"
        kpp:
          type: string
          nullable: true
          description: КПП, null для индивидуального предпринимателя
          example: "781401001"
        ogrn:
          type: string
          nullable: true
          description: ОГРН организации или ОГРНИП индивидуального предпринимателя
          example: "1027700070518"
        registration_date:
          type: string
          format: date
          nullable: true
          description: Дата присвоения ОГРН/ОГРНИП
          example: "2002-08-02"
        termination_date:
          type: string
          format: date
          nullable: true
          description: Дата прекращения деятельности, null если запись действующая
          example: null
        invalidation_date:
          type: string
          format: date
          nullable: true
          description: Дата признания государственной регистрации недействительной
          example: null
        region:
          type: string
          nullable: true
          description: Регион регистрации, null для индивидуального предпринимателя
          example: Г.Санкт-Петербург
        manager:
          allOf:
            - $ref: '#/components/schemas/Manager'
          nullable: true
          description: Сведения о руководителе, null если отсутствуют
        new_territory:
          type: boolean
          description: Признак юридического лица, принятого в РФ вместе с новыми территориями (Федеральный закон № 184-ФЗ)
          example: false
        prior_registration_number:
          type: string
          nullable: true
          description: Регистрационный номер на день принятия в РФ. Приходит только при new_territory = true
        prior_registration_date:
          type: string
          format: date
          nullable: true
          description: Дата регистрации на день принятия в РФ. Приходит только при new_territory = true
        identification_code:
          type: string
          nullable: true
          description: Идентификационный код юридического лица. Приходит только при new_territory = true

    Manager:
      type: object
      properties:
        position:
          type: string
          nullable: true
          description: Должность руководителя
          example: ПРЕДСЕДАТЕЛЬ ПРАВЛЕНИЯ
        name:
          type: string
          description: ФИО руководителя
          example: Миллер Алексей Борисович

    PdfDownloadResponse:
      type: object
      properties:
        success:
          type: integer
          description: Признак успешного выполнения запроса
          example: 1
        file_name:
          type: string
          nullable: true
          description: Имя файла выписки — `ul-` для организации, `fl-` для индивидуального предпринимателя. null, если запись не найдена
          example: ul-1027700070518-20260803190034.pdf
        pdf_content:
          type: string
          format: byte
          nullable: true
          description: Содержимое PDF-файла в кодировке base64. null, если запись не найдена
          example: JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL1BhZ2Vz

    Error400:
      type: object
      properties:
        success:
          type: integer
          description: Признак успешного выполнения запроса
          example: 0
        error:
          type: string
          description: Текст ошибки
          example: "Empty request. Please provide inn, ogrn or name"
        error_code:
          type: string
          description: Код ошибки
          example: "40001"

    Error403:
      type: object
      properties:
        error:
          type: string
          description: Текст ошибки
          enum:
            - "Invalid access key"
            - "The subscription period has expired"
            - "Invalid IP"
            - "Day limit of requests exceeded"
            - "Month limit of requests exceeded"
        error_code:
          type: integer
          description: Код ошибки
          enum:
            - 40301
            - 40302
            - 40303
            - 40304
            - 40305