openapi: 3.1.0
info:
  title: API XCalls
  version: 1.0.0
  description: Единый API XCalls для запуска телефонных сценариев, передачи аудиофайлов на обработку и получения результатов.
servers:
  - url: https://app.xcalls.ru
security:
  - bearerAuth: []
tags:
  - name: A-Call
    description: Исходящий вызов с подтверждением по коду.
  - name: B-Call
    description: Обратное подтверждение звонком с формированием номера и QR-кода.
  - name: Pin-Call
    description: Исходящий вызов с озвучиванием PIN-кода.
  - name: R-Call
    description: Исходящий вызов с озвучиванием переданной фразы.
  - name: Транскрибация
    description: Преобразование аудио в текст.
  - name: Суммаризация
    description: Получение краткого содержания аудио.
  - name: Диаризация
    description: Разделение аудио по говорящим.
  - name: ИОПН
    description: Получение сведений об операторе связи по номеру телефона.
paths:
  /acall/add:
    post:
      tags:
        - A-Call
      summary: Запустить A-Call
      description: Запускает исходящий вызов, во время которого система ожидает ввод кода подтверждения.
      operationId: createACall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ACallRequest'
            examples:
              default:
                value:
                  phone: '79876543210'
                  code: '1234'
                  cbUrl: https://app.xcalls.ru/null
      responses:
        '200':
          description: Результат запуска A-Call.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CallIdSuccess'
                  - $ref: '#/components/schemas/CallError'
              examples:
                success:
                  value:
                    status: true
                    callid: 00000000-0000-0000-0000-000000000000
                invalidPhone:
                  value:
                    status: false
                    error: Invalid phone
                invalidCall:
                  value:
                    status: false
                    error: Invalid call
        '401':
          $ref: '#/components/responses/Unauthorized'
  /bcall/add:
    post:
      tags:
        - B-Call
      summary: Запустить B-Call
      description: 'Запускает сценарий обратного подтверждения: сервис возвращает номер для звонка, время ожидания и ссылку на QR-код.'
      operationId: createBCall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BCallRequest'
            examples:
              default:
                value:
                  phone: '79876543210'
                  cbUrl: https://app.xcalls.ru/null
      responses:
        '200':
          description: Результат запуска B-Call.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/BCallSuccess'
                  - $ref: '#/components/schemas/CallError'
              examples:
                success:
                  value:
                    status: true
                    callid: 00000000-0000-0000-0000-000000000000
                    code: '74951234567'
                    timeout: 180
                    qr: https://app.xcalls.ru/public/img/qr/example.png
                invalidPhone:
                  value:
                    status: false
                    error: Invalid phone
                invalidCall:
                  value:
                    status: false
                    error: Invalid call
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pincall/add:
    post:
      tags:
        - Pin-Call
      summary: Запустить Pin-Call
      description: Запускает исходящий вызов, в котором система озвучивает переданный или сгенерированный PIN-код.
      operationId: createPinCall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PinCallRequest'
            examples:
              default:
                value:
                  phone: '79876543210'
                  code: '1234'
                  repeats: 1
                  lang: ru
                  cbUrl: https://app.xcalls.ru/null
      responses:
        '200':
          description: Результат запуска Pin-Call.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CallIdSuccess'
                  - $ref: '#/components/schemas/CallError'
              examples:
                success:
                  value:
                    status: true
                    callid: 00000000-0000-0000-0000-000000000000
                invalidRepeats:
                  value:
                    status: false
                    error: Invalid repeats
                invalidLang:
                  value:
                    status: false
                    error: Invalid lang
                invalidCall:
                  value:
                    status: false
                    error: Invalid call
        '401':
          $ref: '#/components/responses/Unauthorized'
  /rcall/add:
    post:
      tags:
        - R-Call
      summary: Запустить R-Call
      description: Запускает исходящий вызов с озвучиванием переданной фразы.
      operationId: createRCall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RCallRequest'
            examples:
              default:
                value:
                  phone: '79876543210'
                  code: Это тестовая фраза
                  cbUrl: https://app.xcalls.ru/null
      responses:
        '200':
          description: Результат запуска R-Call.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/RCallSuccess'
                  - $ref: '#/components/schemas/RCallError'
              examples:
                success:
                  value:
                    status: true
                    callid: rcall0000
                error:
                  value:
                    status: false
                    message: synt_fail
                    callid: rcall0000
        '401':
          $ref: '#/components/responses/Unauthorized'
  /transcription/add:
    post:
      tags:
        - Транскрибация
      summary: Запустить транскрибацию
      description: Принимает аудиофайл и ставит его в очередь на транскрибацию.
      operationId: createTranscription
      requestBody:
        $ref: '#/components/requestBodies/AudioRequest'
      responses:
        '200':
          $ref: '#/components/responses/AudioEmptySuccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /summarization/add:
    post:
      tags:
        - Суммаризация
      summary: Запустить суммаризацию
      description: Принимает аудиофайл и ставит его в очередь на суммаризацию.
      operationId: createSummarization
      requestBody:
        $ref: '#/components/requestBodies/AudioRequest'
      responses:
        '200':
          $ref: '#/components/responses/AudioEmptySuccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /diarization/add:
    post:
      tags:
        - Диаризация
      summary: Запустить диаризацию
      description: Принимает аудиофайл и ставит его в очередь на диаризацию.
      operationId: createDiarization
      requestBody:
        $ref: '#/components/requestBodies/AudioRequest'
      responses:
        '200':
          $ref: '#/components/responses/AudioRequestIdSuccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /bdpn/add:
    post:
      tags:
        - ИОПН
      summary: Обработать номер в ИОПН
      description: Передаёт номер телефона на обработку.
      operationId: createIopnRequest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IopnRequest'
            examples:
              default:
                value:
                  phone: '79876543210'
      responses:
        '200':
          description: Результат обработки номера со сведениями об операторе связи.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/IopnSuccess'
                  - $ref: '#/components/schemas/CallError'
              examples:
                success:
                  value:
                    status: true
                    data:
                      - phone: '79876543210'
                        fullname: '<полное наименование оператора>'
                        inn: '<ИНН оператора>'
                        shortname: '<краткое наименование оператора>'
                invalidPhone:
                  value:
                    status: false
                    error: Invalid phone
        '401':
          $ref: '#/components/responses/Unauthorized'
webhooks:
  acallResult:
    post:
      tags:
        - A-Call
      summary: Результат A-Call
      description: Уведомление, которое система отправляет на cbUrl после завершения вызова.
      operationId: receiveACallResult
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallStatusWebhook'
            examples:
              default:
                value:
                  callid: 00000000-0000-0000-0000-000000000000
                  status: ANSWERED
      responses:
        '200':
          description: Уведомление принято.
  bcallResult:
    post:
      tags:
        - B-Call
      summary: Результат B-Call
      description: Уведомление, которое система отправляет на cbUrl после успешного обратного звонка.
      operationId: receiveBCallResult
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BCallWebhook'
            examples:
              default:
                value:
                  callid: 00000000-0000-0000-0000-000000000000
                  dstNumber: '74951234567'
                  srcNumber: '79876543210'
      responses:
        '200':
          description: Уведомление принято.
  pincallResult:
    post:
      tags:
        - Pin-Call
      summary: Результат Pin-Call
      description: Уведомление, которое система отправляет на cbUrl после завершения вызова.
      operationId: receivePinCallResult
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallStatusWebhook'
            examples:
              default:
                value:
                  callid: 00000000-0000-0000-0000-000000000000
                  status: ANSWERED
      responses:
        '200':
          description: Уведомление принято.
  rcallResult:
    post:
      tags:
        - R-Call
      summary: Результат R-Call
      description: Уведомление, которое система отправляет на cbUrl после завершения вызова.
      operationId: receiveRCallResult
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RCallWebhook'
            examples:
              default:
                value:
                  callid: rcall0000
                  status: ANSWERED
                  billsec: 15
      responses:
        '200':
          description: Уведомление принято.
  transcriptionResult:
    post:
      tags:
        - Транскрибация
      summary: Результат транскрибации
      description: Уведомление, которое система отправляет на cbUrl после завершения транскрибации.
      operationId: receiveTranscriptionResult
      requestBody:
        $ref: '#/components/requestBodies/AudioWebhookRequest'
      responses:
        '200':
          description: Уведомление принято.
  summarizationResult:
    post:
      tags:
        - Суммаризация
      summary: Результат суммаризации
      description: Уведомление, которое система отправляет на cbUrl после завершения суммаризации.
      operationId: receiveSummarizationResult
      requestBody:
        $ref: '#/components/requestBodies/AudioWebhookRequest'
      responses:
        '200':
          description: Уведомление принято.
  diarizationResult:
    post:
      tags:
        - Диаризация
      summary: Результат диаризации
      description: Уведомление, которое система отправляет на cbUrl после завершения диаризации.
      operationId: receiveDiarizationResult
      requestBody:
        $ref: '#/components/requestBodies/AudioWebhookRequest'
      responses:
        '200':
          description: Уведомление принято.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API token
      description: 'Токен в заголовке Authorization: Bearer <token>.'
  requestBodies:
    AudioRequest:
      required: true
      content:
        multipart/form-data:
          schema:
            $ref: '#/components/schemas/AudioRequest'
          encoding:
            audio:
              contentType: audio/wav
          examples:
            default:
              value:
                cbUrl: https://app.xcalls.ru/null
                audio: audio_record.wav
    AudioWebhookRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AudioWebhook'
          examples:
            default:
              value:
                requestId: 5
                textResult: Текстовый результат обработки
  responses:
    AudioEmptySuccess:
      description: Запрос на обработку принят. Результат будет передан на cbUrl, если адрес указан.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AudioEmptySuccess'
          examples:
            default:
              value:
                status: true
                data: []
    AudioRequestIdSuccess:
      description: Запрос на обработку принят. Ответ содержит идентификатор запроса; результат будет передан на cbUrl, если адрес указан.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AudioRequestIdSuccess'
          examples:
            default:
              value:
                status: true
                data:
                  requestId: 5
    Unauthorized:
      description: Ошибка авторизации.
      content:
        application/json:
          schema:
            type: object
            required:
              - error
            properties:
              error:
                type: string
                const: Unauthorized
            additionalProperties: false
          examples:
            default:
              value:
                error: Unauthorized
  schemas:
    ACallRequest:
      type: object
      required:
        - phone
      properties:
        phone:
          type: string
          description: Номер телефона в формате 11 цифр.
          examples:
            - '79876543210'
        code:
          type: string
          description: Код подтверждения. Если не указан, генерируется автоматически.
          examples:
            - '1234'
        cbUrl:
          type: string
          format: uri
          description: URL для получения callback-уведомления.
          examples:
            - https://app.xcalls.ru/null
      additionalProperties: true
    BCallRequest:
      type: object
      required:
        - phone
      properties:
        phone:
          type: string
          description: Номер телефона в формате 11 цифр.
          examples:
            - '79876543210'
        cbUrl:
          type: string
          format: uri
          description: URL для получения callback-уведомления.
          examples:
            - https://app.xcalls.ru/null
      additionalProperties: false
    PinCallRequest:
      type: object
      required:
        - phone
      properties:
        phone:
          type: string
          description: Номер телефона для вызова.
          examples:
            - '79876543210'
        code:
          type: string
          description: PIN-код для озвучивания. Если не указан, генерируется автоматически.
          examples:
            - '1234'
        repeats:
          type: integer
          minimum: 1
          maximum: 3
          default: 1
          description: Количество повторов озвучивания.
        lang:
          type: string
          enum:
            - ru
            - en
          default: ru
          description: Язык озвучивания.
        cbUrl:
          type: string
          format: uri
          description: URL для получения callback-уведомления.
          examples:
            - https://app.xcalls.ru/null
      additionalProperties: false
    RCallRequest:
      type: object
      required:
        - phone
        - code
      properties:
        phone:
          type: string
          description: Номер телефона для звонка.
          examples:
            - '79876543210'
        code:
          type: string
          description: Фраза для озвучивания.
          examples:
            - Это тестовая фраза
        cbUrl:
          type: string
          format: uri
          description: URL для получения callback-уведомления.
          examples:
            - https://app.xcalls.ru/null
        timeLimit:
          type: integer
          minimum: 0
          description: Ограничение времени звонка в секундах.
      additionalProperties: false
    CallIdSuccess:
      type: object
      required:
        - status
        - callid
      properties:
        status:
          type: boolean
          const: true
        callid:
          type: string
      additionalProperties: true
    BCallSuccess:
      type: object
      required:
        - status
        - callid
        - code
        - timeout
        - qr
      properties:
        status:
          type: boolean
          const: true
        callid:
          type: string
        code:
          type: string
          description: Номер, на который необходимо совершить звонок.
        timeout:
          type: integer
          description: Время ожидания звонка в секундах.
        qr:
          type: string
          format: uri
          description: Ссылка на QR-код для звонка.
      additionalProperties: true
    CallError:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: boolean
          const: false
        error:
          type: string
      additionalProperties: true
    RCallSuccess:
      type: object
      required:
        - status
        - callid
      properties:
        status:
          type: boolean
          const: true
        callid:
          type: string
      additionalProperties: true
    RCallError:
      type: object
      required:
        - status
        - message
        - callid
      properties:
        status:
          type: boolean
          const: false
        message:
          type: string
        callid:
          type: string
      additionalProperties: true
    CallStatusWebhook:
      type: object
      required:
        - callid
        - status
      properties:
        callid:
          type: string
        status:
          type: string
      additionalProperties: true
    BCallWebhook:
      type: object
      required:
        - callid
        - dstNumber
        - srcNumber
      properties:
        callid:
          type: string
        dstNumber:
          type: string
        srcNumber:
          type: string
      additionalProperties: true
    RCallWebhook:
      type: object
      required:
        - callid
        - status
      properties:
        callid:
          type: string
        status:
          type: string
        billsec:
          type:
            - integer
            - 'null'
        call_record:
          type:
            - string
            - 'null'
        numa:
          type:
            - string
            - 'null'
      additionalProperties: true
    AudioRequest:
      type: object
      required:
        - audio
      properties:
        cbUrl:
          type: string
          format: uri
          description: URL для получения callback-уведомления.
          examples:
            - https://app.xcalls.ru/null
        audio:
          type: string
          format: binary
      additionalProperties: false
    AudioEmptySuccess:
      type: object
      required:
        - status
        - data
      properties:
        status:
          type: boolean
          const: true
        data:
          type: array
          maxItems: 0
          items: {}
      additionalProperties: false
    AudioRequestIdSuccess:
      type: object
      required:
        - status
        - data
      properties:
        status:
          type: boolean
          const: true
        data:
          type: object
          required:
            - requestId
          properties:
            requestId:
              type: integer
      additionalProperties: true
    AudioWebhook:
      type: object
      required:
        - requestId
        - textResult
      properties:
        requestId:
          oneOf:
            - type: integer
            - type: string
        textResult:
          type: string
      additionalProperties: true
    ErrorResponse:
      type: object
      required:
        - status
      properties:
        status:
          type: boolean
          const: false
        message:
          type: string
      additionalProperties: true
    IopnRequest:
      type: object
      required:
        - phone
      properties:
        phone:
          type: string
          minLength: 11
          maxLength: 11
          description: Номер телефона длиной 11 символов.
          examples:
            - '79876543210'
      additionalProperties: false
    IopnSuccess:
      type: object
      required:
        - status
        - data
      properties:
        status:
          type: boolean
          const: true
        data:
          type: array
          description: Массив сведений об операторе связи.
          items:
            $ref: '#/components/schemas/IopnOperatorData'
      additionalProperties: true
    IopnOperatorData:
      type: object
      required:
        - phone
        - fullname
        - inn
        - shortname
      properties:
        phone:
          type: string
          description: Номер телефона.
        fullname:
          type: string
          description: Полное наименование оператора связи.
        inn:
          type: string
          description: ИНН оператора связи.
        shortname:
          type: string
          description: Краткое наименование оператора связи.
      additionalProperties: false
