openapi: 3.0.3
info:
  title: bit_http_api — REST API для 1С:Бухгалтерия
  description: |
    HTTP-сервис расширения bit_http_api для 1С:Бухгалтерия предприятия 3.0 (3.0.190.22+).
    Аутентификация — Basic Auth. Суммы в JSON — в копейках (целые числа).
    Документация и примеры — https://bit22.ru/rest-api-1c
  version: 0.4.0
  contact:
    name: CodeLab — Группа компаний БИТ
    url: https://bit22.ru/contacts
servers:
  - url: '{baseUrl}/hs/bit_http_api'
    description: Опубликованный HTTP-сервис 1С
    variables:
      baseUrl:
        default: https://your-1c.example/base
        description: URL публикации информационной базы 1С
security:
  - basicAuth: []
tags:
  - name: invoices
    description: Счета на оплату
  - name: acts
    description: Акты выполненных работ
  - name: tax-invoices
    description: Счета-фактуры
  - name: counterparties
    description: Контрагенты
paths:
  /invoices:
    get:
      tags: [invoices]
      summary: Список счетов за период
      description: Фильтры и пагинация (v0.4.0). limit по умолчанию 10, offset — 0.
      parameters:
        - name: dateBegin
          in: query
          schema: { type: string, format: date, example: '2026-02-01' }
        - name: dateEnd
          in: query
          schema: { type: string, format: date, example: '2026-02-28' }
        - name: sellerInn
          in: query
          schema: { type: string, example: '7799434926' }
        - name: payerInn
          in: query
          schema: { type: string }
        - name: offset
          in: query
          schema: { type: integer, default: 0 }
        - name: limit
          in: query
          schema: { type: integer, default: 10 }
        - name: comment
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Массив счетов
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Invoice' }
    post:
      tags: [invoices]
      summary: Создать счёт
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/InvoiceCreate' }
            example:
              seller_inn: '7799434926'
              payer_inn: '770987654321'
              comment: order-8842
              items:
                - name: Услуга
                  price: 1000000
                  quantity: 1
      responses:
        '200':
          description: Созданный счёт
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Invoice' }
        '400':
          description: Ошибка валидации JSON
        '401':
          description: Неверный Basic Auth или нет роли bitHttpApi_ОсновнаяРоль
  /invoices/{id}:
    get:
      tags: [invoices]
      summary: Получить счёт или поиск по комментарию
      parameters:
        - $ref: '#/components/parameters/documentId'
        - name: comment
          in: query
          schema: { type: integer, enum: [1] }
          description: comment=1 — поиск по фрагменту в path (v0.2.0)
      responses:
        '200':
          description: Счёт
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Invoice' }
    put:
      tags: [invoices]
      summary: Обновить счёт
      parameters:
        - $ref: '#/components/parameters/documentId'
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/InvoiceCreate' }
      responses:
        '200':
          description: Обновлённый счёт
    delete:
      tags: [invoices]
      summary: Пометить счёт удалённым
      parameters:
        - $ref: '#/components/parameters/documentId'
      responses:
        '200':
          description: OK
  /invoices/{id}/print:
    get:
      tags: [invoices]
      summary: PDF печатной формы счёта
      parameters:
        - $ref: '#/components/parameters/documentId'
        - name: facsimile
          in: query
          schema: { type: integer, enum: [0, 1], default: 1 }
          description: facsimile=0 — без подписей и печатей (v0.1.2)
      responses:
        '200':
          description: PDF
          content:
            application/pdf:
              schema: { type: string, format: binary }
  /acts:
    get:
      tags: [acts]
      summary: Список актов
      parameters:
        - name: dateBegin
          in: query
          schema: { type: string, format: date }
        - name: dateEnd
          in: query
          schema: { type: string, format: date }
        - name: invoiceId
          in: query
          schema: { type: string }
        - name: offset
          in: query
          schema: { type: integer, default: 0 }
        - name: limit
          in: query
          schema: { type: integer, default: 10 }
      responses:
        '200':
          description: Массив актов
    post:
      tags: [acts]
      summary: Создать акт
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ActCreate' }
      responses:
        '200':
          description: Созданный акт
  /acts/{id}:
    get:
      tags: [acts]
      summary: Получить акт
      parameters:
        - $ref: '#/components/parameters/documentId'
      responses:
        '200':
          description: Акт
    put:
      tags: [acts]
      summary: Обновить акт
      parameters:
        - $ref: '#/components/parameters/documentId'
      responses:
        '200':
          description: OK
    delete:
      tags: [acts]
      summary: Пометить акт удалённым
      parameters:
        - $ref: '#/components/parameters/documentId'
      responses:
        '200':
          description: OK
  /acts/{id}/print:
    get:
      tags: [acts]
      summary: PDF акта
      parameters:
        - $ref: '#/components/parameters/documentId'
        - name: facsimile
          in: query
          schema: { type: integer, enum: [0, 1] }
      responses:
        '200':
          description: PDF
  /tax-invoices:
    post:
      tags: [tax-invoices]
      summary: Создать счёт-фактуру по акту
      description: v0.3.0
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [act_id]
              properties:
                act_id: { type: string, example: '0000-000006_20260225' }
      responses:
        '200':
          description: Счёт-фактура
  /tax-invoices/{id}:
    get:
      tags: [tax-invoices]
      summary: Получить счёт-фактуру
      parameters:
        - $ref: '#/components/parameters/documentId'
      responses:
        '200':
          description: Счёт-фактура
  /tax-invoices/{id}/print:
    get:
      tags: [tax-invoices]
      summary: PDF счёта-фактуры
      parameters:
        - $ref: '#/components/parameters/documentId'
      responses:
        '200':
          description: PDF
  /counterparties/{inn}:
    get:
      tags: [counterparties]
      summary: Найти контрагента по ИНН
      parameters:
        - name: inn
          in: path
          required: true
          schema: { type: string, example: '771234567890' }
      responses:
        '200':
          description: Контрагент
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Counterparty' }
        '404':
          description: Не найден
    put:
      tags: [counterparties]
      summary: Обновить контрагента
      parameters:
        - name: inn
          in: path
          required: true
          schema: { type: string }
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Counterparty' }
      responses:
        '200':
          description: OK
  /counterparties:
    post:
      tags: [counterparties]
      summary: Создать контрагента
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Counterparty' }
      responses:
        '200':
          description: Созданный контрагент
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  parameters:
    documentId:
      name: id
      in: path
      required: true
      schema: { type: string }
      description: |
        Формат id: {номер}_{дата} или {номер}_{дата}_{ИНН_продавца}_{ИНН_покупателя}
      example: '0000-000596_20161227'
  schemas:
    InvoiceItem:
      type: object
      required: [name, price, quantity]
      properties:
        name: { type: string }
        description: { type: string }
        price: { type: integer, description: 'Цена в копейках' }
        quantity: { type: number }
        total: { type: integer }
    InvoiceCreate:
      type: object
      required: [seller_inn, payer_inn, items]
      properties:
        seller_inn: { type: string }
        payer_inn: { type: string }
        comment: { type: string }
        items:
          type: array
          items: { $ref: '#/components/schemas/InvoiceItem' }
    Invoice:
      type: object
      properties:
        id: { type: string }
        number: { type: string }
        date: { type: string, format: date }
        seller_inn: { type: string }
        payer: { $ref: '#/components/schemas/CounterpartyShort' }
        items:
          type: array
          items: { $ref: '#/components/schemas/InvoiceItem' }
        total_amount: { type: integer }
        paid_amount: { type: integer }
        deleted: { type: boolean }
        comment: { type: string }
    ActCreate:
      type: object
      properties:
        seller_inn: { type: string }
        payer_inn: { type: string }
        invoice_id: { type: string }
        items:
          type: array
          items: { $ref: '#/components/schemas/InvoiceItem' }
    CounterpartyShort:
      type: object
      properties:
        inn: { type: string }
        name: { type: string }
    Counterparty:
      type: object
      properties:
        inn: { type: string }
        kpp: { type: string }
        name: { type: string }
        address: { type: string }
        account_number: { type: string }
        bank_bik: { type: string }
        email: { type: string, format: email }
