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

      Все запросы требуют указания ключа доступа (`key`).

paths:
  /search:
    get:
      tags:
        - Основные запросы
      summary: Поиск организаций
      description: Выполняет поиск организаций по наименованию, ИНН или ОГРН. Обязательно должен быть указан хотя бы один параметр — `query`, `inn` или `ogrn`.
      parameters:
        - name: key
          in: query
          required: true
          schema:
            type: string
          description: Ключ доступа (обязательный)
        - name: query
          in: query
          required: false
          schema:
            type: string
          description: Наименование организации (поиск по названию)
        - name: inn
          in: query
          required: false
          schema:
            type: string
          description: ИНН организации
        - name: ogrn
          in: query
          required: false
          schema:
            type: string
          description: ОГРН организации
        - 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'

  /details:
    get:
      tags:
        - Основные запросы
      summary: Получение детальной информации
      description: Возвращает общие сведения об организации и полную бухгалтерскую отчетность за все доступные годы по внутреннему ID организации, полученному из результатов поиска.
      parameters:
        - name: key
          in: query
          required: true
          schema:
            type: string
          description: Ключ доступа (обязательный)
        - name: id
          in: query
          required: true
          schema:
            type: integer
          description: Внутренний ID организации, полученный из результатов поиска (обязательный)
      responses:
        '200':
          description: Успешный ответ.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailsResponse'
        '400':
          description: Ошибка валидации запроса.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Ошибка доступа.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'

components:
  schemas:
    SearchResponse:
      type: object
      properties:
        success:
          type: integer
          description: Флаг успешности выполнения запроса, 1/0
          example: 1
        count:
          type: integer
          description: Общее количество найденных организаций
          example: 814
        pages:
          type: integer
          description: Общее количество страниц
          example: 41
        page:
          type: integer
          description: Текущая страница
          example: 1
        items:
          type: array
          description: Массив найденных организаций
          items:
            $ref: '#/components/schemas/SearchItem'

    SearchItem:
      type: object
      properties:
        id:
          type: integer
          description: Внутренний ID организации (используется для запроса детальной информации)
          example: 6622458
        inn:
          type: string
          description: ИНН
          example: "7736050003"
        ogrn:
          type: string
          description: ОГРН
          example: "1027700070518"
        short_name:
          type: string
          description: Краткое наименование
          example: "ПАО \"ГАЗПРОМ\""
        status_code:
          type: string
          description: Статус организации (ACTIVE — действующая)
          example: "ACTIVE"
        status_date:
          type: string
          description: Дата присвоения статуса
          example: "2002-08-02"
        index:
          type: string
          description: Почтовый индекс
          example: "197229"
        region:
          type: string
          description: Регион
          example: "САНКТ-ПЕТЕРБУРГ"
        district:
          type: string
          nullable: true
          description: Район
        city:
          type: string
          nullable: true
          description: Город
        settlement:
          type: string
          nullable: true
          description: Населенный пункт
        street:
          type: string
          description: Улица
          example: "ЛАХТИНСКИЙ"
        house:
          type: string
          description: Дом
          example: "2"
        building:
          type: string
          nullable: true
          description: Корпус/строение
          example: "3"
        office:
          type: string
          nullable: true
          description: Офис
        okved2:
          type: string
          description: Код ОКВЭД2
          example: "46.71"
        okopf:
          type: integer
          description: Код ОКОПФ
          example: 12247
        bfo:
          $ref: '#/components/schemas/BfoSummary'

    BfoSummary:
      type: object
      description: Сводка по последней бухгалтерской отчетности
      properties:
        period:
          type: string
          description: Отчетный период (год)
          example: "2025"
        actual_bfo_date:
          type: string
          description: Дата актуальной отчетности
          example: "2026-03-16"
        gain_sum:
          type: integer
          description: Выручка (тыс. руб.)
          example: 5846351786
        knd:
          type: string
          description: Код формы по КНД
          example: "0710099"
        has_az:
          type: boolean
          description: Наличие аудиторского заключения
          example: true
        has_ks:
          type: boolean
          description: Наличие консолидированной отчетности
          example: false
        actual_correction_number:
          type: integer
          description: Номер корректировки
          example: 0
        actual_correction_date:
          type: string
          description: Дата корректировки
          example: "2026-03-16"
        is_cb:
          type: boolean
          description: Является ли отчетность ЦБ
          example: false

    DetailsResponse:
      type: object
      properties:
        success:
          type: integer
          description: Флаг успешности выполнения запроса, 1/0
          example: 1
        organization:
          $ref: '#/components/schemas/Organization'
        reports:
          type: array
          description: Массив отчетов за все доступные годы
          items:
            $ref: '#/components/schemas/Report'

    Organization:
      type: object
      description: Сведения об организации
      properties:
        id:
          type: integer
          description: Внутренний ID
          example: 6622458
        inn:
          type: string
          description: ИНН
          example: "7736050003"
        kpp:
          type: string
          description: КПП
          example: "781401001"
        ogrn:
          type: string
          description: ОГРН
          example: "1027700070518"
        short_name:
          type: string
          description: Краткое наименование
          example: "ПАО \"ГАЗПРОМ\""
        full_name:
          type: string
          description: Полное наименование
          example: "ПУБЛИЧНОЕ АКЦИОНЕРНОЕ ОБЩЕСТВО \"ГАЗПРОМ\""
        status_code:
          type: string
          description: Статус (ACTIVE — действующая)
          example: "ACTIVE"
        status_date:
          type: string
          description: Дата присвоения статуса
          example: "1993-02-25"
        registration_date:
          type: string
          description: Дата регистрации
          example: "1993-02-25"
        authorized_capital:
          type: integer
          description: Уставный капитал (руб.)
          example: 118367564500
        index:
          type: string
          description: Почтовый индекс
          example: "197229"
        region:
          type: string
          description: Регион
          example: "САНКТ-ПЕТЕРБУРГ"
        district:
          type: string
          nullable: true
          description: Район
        city:
          type: string
          nullable: true
          description: Город
        settlement:
          type: string
          nullable: true
          description: Населенный пункт
        street:
          type: string
          description: Улица
          example: "ЛАХТИНСКИЙ"
        house:
          type: string
          description: Дом
          example: "2"
        building:
          type: string
          nullable: true
          description: Корпус/строение
          example: "3"
        office:
          type: string
          nullable: true
          description: Офис
        okved2:
          $ref: '#/components/schemas/Okved2'
        okopf:
          $ref: '#/components/schemas/Classifier'
        okfs:
          $ref: '#/components/schemas/Classifier'
        okpo:
          type: string
          description: ОКПО
          example: "00040778"
        location:
          type: object
          description: Сведения о регистрирующем налоговом органе
          properties:
            name:
              type: string
              description: Наименование
              example: "Инспекция ФНС России № 28 по г.Москве"
            code:
              type: integer
              description: Код
              example: 7728

    Okved2:
      type: object
      description: ОКВЭД2
      properties:
        id:
          type: string
          description: Код
          example: "46.71"
        name:
          type: string
          description: Наименование
          example: "Торговля оптовая твердым, жидким и газообразным топливом и подобными продуктами"

    Classifier:
      type: object
      description: Классификатор
      properties:
        id:
          type: integer
          description: Код
          example: 12247
        name:
          type: string
          description: Наименование
          example: "Публичные акционерные общества"

    Report:
      type: object
      description: Отчет за период
      properties:
        period:
          type: string
          description: Отчетный период (год)
          example: "2025"
        detail_id:
          type: integer
          description: ID корректировки (используется для скачивания PDF файлов)
          example: 54366105
        actual_bfo_date:
          type: string
          description: Дата актуальной отчетности
          example: "2026-03-16"
        gain_sum:
          type: integer
          description: Выручка (тыс. руб.)
          example: 5846351786
        actives:
          type: integer
          description: Активы (тыс. руб.)
          example: 25736328136
        knd:
          type: string
          description: Код формы по КНД
          example: "0710099"
        correction_number:
          type: integer
          description: Номер корректировки
          example: 0
        correction_date:
          type: string
          description: Дата корректировки
          example: "2026-03-16"
        published_date:
          type: string
          description: Дата публикации
          example: "2026-03-17"
        required_audit:
          type: integer
          description: Обязательный аудит (1 — да, 0 — нет)
          example: 1
        date_present:
          type: string
          description: Дата представления отчетности
          example: "2026-03-16T18:51:12"
        organization_info:
          $ref: '#/components/schemas/ReportOrganizationInfo'
        url:
          type: string
          description: Прямая ссылка на скачивание PDF всей отчетности за период
          example: "https://bo.nalog.gov.ru/download/bfo/pdf/6622458?period=2025&detailId=54366105"
        original_url:
          type: string
          description: Прямая ссылка на скачивание исходных файлов отчетности
          example: "https://bo.nalog.gov.ru/download/original/54366105?isCb=false"
        balance:
          type: array
          description: "Бухгалтерский баланс. Содержит данные по строкам за три периода: текущий (current), предыдущий (previous) и предшествующий предыдущему (before_previous). Все суммы в тысячах рублей."
          items:
            $ref: '#/components/schemas/BalanceRow'
        financial_result:
          type: array
          description: "Отчет о финансовых результатах. Содержит данные за два периода: текущий (current) и предыдущий (previous). Все суммы в тысячах рублей."
          items:
            $ref: '#/components/schemas/FinancialResultRow'
        capital_change:
          type: array
          description: "Отчет об изменениях капитала. Каждая строка имеет разбивку по столбцам капитала."
          items:
            $ref: '#/components/schemas/CapitalChangeRow'
        funds_movement:
          type: array
          description: "Отчет о движении денежных средств за два периода: текущий (current) и предыдущий (previous). Все суммы в тысячах рублей."
          items:
            $ref: '#/components/schemas/FundsMovementRow'
        targeted_funds_using:
          type: array
          description: "Отчет о целевом использовании средств за два периода: текущий (current) и предыдущий (previous). Заполняется некоммерческими организациями. Все суммы в тысячах рублей."
          items:
            $ref: '#/components/schemas/TargetedFundsRow'
        audit_report:
          nullable: true
          description: Аудиторское заключение (null если отсутствует)
          allOf:
            - $ref: '#/components/schemas/AuditReport'
        clarification:
          nullable: true
          description: Пояснения к бухгалтерскому балансу (null если отсутствует)
          allOf:
            - $ref: '#/components/schemas/Clarification'

    ReportOrganizationInfo:
      type: object
      description: Сведения об организации из БФО
      properties:
        full_name:
          type: string
          description: Полное наименование
          example: "Публичное акционерное общество \"Газпром\""
        inn:
          type: string
          description: ИНН
          example: "7736050003"
        kpp:
          type: string
          description: КПП
          example: "997250001"
        address:
          type: string
          description: Адрес
          example: "197229, Санкт-Петербург, Лахтинский пр-кт, д.2, к.3, стр.1"
        okopf:
          $ref: '#/components/schemas/Classifier'
        okfs:
          $ref: '#/components/schemas/Classifier'
        okpo:
          type: string
          description: ОКПО
          example: "00040778"

    BalanceRow:
      type: object
      description: Строка бухгалтерского баланса
      properties:
        code:
          type: integer
          description: Код строки
          example: 1110
        name:
          type: string
          description: Наименование строки
          example: "Нематериальные активы"
        current:
          type: number
          nullable: true
          description: Значение на отчетную дату текущего периода (тыс. руб.)
          example: 32601871
        previous:
          type: number
          nullable: true
          description: Значение на 31 декабря предыдущего года (тыс. руб.)
          example: 26164163
        before_previous:
          type: number
          nullable: true
          description: Значение на 31 декабря года, предшествующего предыдущему (тыс. руб.)
          example: 24427548
        details:
          type: array
          description: Детализация строки (при наличии расшифровки)
          items:
            $ref: '#/components/schemas/BalanceDetailRow'

    BalanceDetailRow:
      type: object
      description: Подстрока бухгалтерского баланса
      properties:
        code:
          type: integer
          description: Код подстроки
          example: 115001
        name:
          type: string
          description: Наименование
          example: "объекты основных средств"
        current:
          type: number
          nullable: true
          description: Значение на отчетную дату текущего периода (тыс. руб.)
          example: 12241946225
        previous:
          type: number
          nullable: true
          description: Значение на 31 декабря предыдущего года (тыс. руб.)
          example: 12184641603
        before_previous:
          type: number
          nullable: true
          description: Значение на 31 декабря года, предшествующего предыдущему (тыс. руб.)
          example: 11760797370

    FinancialResultRow:
      type: object
      description: Строка отчета о финансовых результатах
      properties:
        code:
          type: integer
          description: Код строки
          example: 2110
        name:
          type: string
          description: Наименование строки
          example: "Выручка"
        current:
          type: number
          nullable: true
          description: Значение за отчетный период (тыс. руб.)
          example: 5846351786
        previous:
          type: number
          nullable: true
          description: Значение за аналогичный период предыдущего года (тыс. руб.)
          example: 6256625972
        details:
          type: array
          description: Детализация строки (при наличии расшифровки)
          items:
            $ref: '#/components/schemas/FinancialResultDetailRow'

    FinancialResultDetailRow:
      type: object
      description: Подстрока отчета о финансовых результатах
      properties:
        code:
          type: integer
          description: Код подстроки
          example: 211001
        name:
          type: string
          description: Наименование
          example: "продажа газа"
        current:
          type: number
          nullable: true
          description: Значение за отчетный период (тыс. руб.)
          example: 3674478562
        previous:
          type: number
          nullable: true
          description: Значение за аналогичный период предыдущего года (тыс. руб.)
          example: 3889517030

    CapitalChangeRow:
      type: object
      description: "Строка отчета об изменениях капитала. Столбцы: authorized — уставный капитал, redeemed — собственные акции выкупленные у акционеров, additional — добавочный капитал, reserve — резервный капитал, unallocated — нераспределенная прибыль (непокрытый убыток), revaluation — накопленная дооценка внеоборотных активов, total — итого."
      properties:
        code:
          type: integer
          description: Код строки
          example: 3100
        name:
          type: string
          description: Наименование строки
          example: "Величина капитала на 31 декабря года, предшествующего предыдущему"
        authorized:
          type: number
          nullable: true
          description: Уставный капитал
          example: 118367564
        redeemed:
          type: number
          nullable: true
          description: Собственные акции, выкупленные у акционеров
        additional:
          type: number
          nullable: true
          description: Добавочный капитал
          example: 228765559
        reserve:
          type: number
          nullable: true
          description: Резервный капитал
          example: 8636001
        unallocated:
          type: number
          nullable: true
          description: Нераспределенная прибыль (непокрытый убыток)
          example: 17059695671
        revaluation:
          type: number
          nullable: true
          description: Накопленная дооценка внеоборотных активов
        total:
          type: number
          nullable: true
          description: Итого
          example: 17415464795
        details:
          type: array
          description: Детализация строки (при наличии расшифровки)
          items:
            $ref: '#/components/schemas/CapitalChangeDetailRow'

    CapitalChangeDetailRow:
      type: object
      description: Подстрока отчета об изменениях капитала
      properties:
        code:
          type: integer
          description: Код подстроки
          example: 324001
        name:
          type: string
          description: Наименование
          example: "операции, связанные с бессрочными облигациями и займами"
        authorized:
          type: number
          nullable: true
          description: Уставный капитал
        redeemed:
          type: number
          nullable: true
          description: Собственные акции, выкупленные у акционеров
        additional:
          type: number
          nullable: true
          description: Добавочный капитал
        reserve:
          type: number
          nullable: true
          description: Резервный капитал
        unallocated:
          type: number
          nullable: true
          description: Нераспределенная прибыль (непокрытый убыток)
        revaluation:
          type: number
          nullable: true
          description: Накопленная дооценка внеоборотных активов
        total:
          type: number
          nullable: true
          description: Итого

    FundsMovementRow:
      type: object
      description: Строка отчета о движении денежных средств
      properties:
        code:
          type: integer
          description: Код строки
          example: 4110
        name:
          type: string
          description: Наименование строки
          example: "Поступления — всего"
        current:
          type: number
          nullable: true
          description: Значение за отчетный период (тыс. руб.)
          example: 7566949191
        previous:
          type: number
          nullable: true
          description: Значение за аналогичный период предыдущего года (тыс. руб.)
          example: 7431051822
        details:
          type: array
          description: Детализация строки (при наличии расшифровки)
          items:
            $ref: '#/components/schemas/FundsMovementDetailRow'

    FundsMovementDetailRow:
      type: object
      description: Подстрока отчета о движении денежных средств
      properties:
        code:
          type: integer
          description: Код подстроки
          example: 431401
        name:
          type: string
          description: Наименование
          example: "от бессрочных облигаций и займов"
        current:
          type: number
          nullable: true
          description: Значение за отчетный период (тыс. руб.)
        previous:
          type: number
          nullable: true
          description: Значение за аналогичный период предыдущего года (тыс. руб.)

    TargetedFundsRow:
      type: object
      description: Строка отчета о целевом использовании средств
      properties:
        code:
          type: integer
          description: Код строки
          example: 6100
        name:
          type: string
          description: Наименование строки
          example: "Остаток средств на начало отчетного года"
        current:
          type: number
          nullable: true
          description: Значение за отчетный период (тыс. руб.)
          example: 0
        previous:
          type: number
          nullable: true
          description: Значение за аналогичный период предыдущего года (тыс. руб.)
          example: 0

    AuditReport:
      type: object
      description: Аудиторское заключение
      properties:
        auditor_inn:
          type: string
          description: ИНН аудитора
          example: "7701017140"
        auditor_ogrn:
          type: string
          description: ОГРН аудитора
          example: "1027700058286"
        auditor_name:
          type: string
          description: Наименование аудитора
          example: "Общество с ограниченной ответственностью \"Финансовые и бухгалтерские консультанты\""
        is_organization:
          type: boolean
          description: Аудитор является организацией
          example: true
        file_name:
          type: string
          description: Оригинальное имя файла
          example: "NO_BUHAZ_...pdf"
        file_url:
          type: string
          description: Прямая ссылка на скачивание PDF
          example: "https://bo.nalog.gov.ru/download/audit/54366105"

    Clarification:
      type: object
      description: Пояснения к бухгалтерскому балансу
      properties:
        file_name:
          type: string
          description: Оригинальное имя файла
          example: "NO_BUHPZ_...pdf"
        file_url:
          type: string
          description: Прямая ссылка на скачивание PDF
          example: "https://bo.nalog.gov.ru/download/clarification/54366105"

    Error400:
      type: object
      properties:
        error:
          type: string
          description: Текст ошибки
          example: "Empty request. Please provide query, inn or ogrn"
        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