openapi: 3.1.0
info: {title: HAN Bitrix24 Local App, version: 1.0.0}
paths:
  /bitrix/handler:
    get: {responses: {"200": {description: Callback probe}}}
    post:
      requestBody:
        required: true
        content:
          application/json: {schema: {type: object}}
          application/x-www-form-urlencoded: {schema: {type: object}}
          multipart/form-data: {schema: {type: object}}
      responses:
        "200": {description: Duplicate or ignored callback}
        "202": {description: Durably accepted callback}
        "400": {description: Invalid callback}
        "403": {description: Invalid application token}
  /bitrix/install:
    get: {responses: {"200": {description: Install probe}}}
    post:
      responses:
        "200": {description: OAuth saved and setup attempted}
        "400": {description: Invalid install callback}
  /bitrix/placement:
    get: {responses: {"200": {description: Connector placement HTML}}}
  /health/live:
    get: {responses: {"200": {description: Live}}}
  /health/ready:
    get: {responses: {"200": {description: Ready}, "503": {description: Not ready}}}
  /internal/openlines/v1/messages:
    post:
      security: [{BearerAuth: []}]
      parameters:
        - {name: Idempotency-Key, in: header, required: true, schema: {type: string}}
        - {$ref: "#/components/parameters/RequestId"}
      requestBody:
        required: true
        content:
          application/json: {schema: {$ref: "#/components/schemas/OutboundMessage"}}
      responses:
        "201": {description: Delivered}
        "200": {description: Idempotent duplicate}
        "400": {description: Invalid request}
        "401": {description: Unauthorized}
        "409": {description: Idempotency key reused}
        "503": {description: Dependency unavailable or ambiguous delivery}
  /internal/openlines/v1/dialogs/{external_chat_id}:
    get:
      security: [{BearerAuth: []}]
      parameters:
        - {name: external_chat_id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        "200": {description: Active dialog mapping}
        "404": {description: Mapping not found}
  /internal/openlines/v1/status:
    get:
      security: [{BearerAuth: []}]
      responses: {"200": {description: Safe adapter status}}
  /internal/openlines/v1/setup/retry:
    post:
      security: [{BearerAuth: []}]
      responses: {"200": {description: Idempotent setup reconcile result}}
components:
  securitySchemes:
    BearerAuth: {type: http, scheme: bearer}
  parameters:
    RequestId: {name: X-Request-ID, in: header, required: false, schema: {type: string}}
  schemas:
    OutboundFile:
      type: object
      additionalProperties: false
      required: [attachment_id, name, mime_type, size_bytes, download_url]
      properties:
        attachment_id: {type: string, format: uuid}
        name: {type: string, maxLength: 255}
        mime_type: {type: string, maxLength: 255}
        size_bytes: {type: integer, minimum: 1, maximum: 5242880}
        download_url: {type: string, maxLength: 4096}
    OutboundMessage:
      type: object
      additionalProperties: false
      required: [message_id, external_chat_id, occurred_at, user, message]
      properties:
        message_id: {type: string, format: uuid}
        external_chat_id: {type: string, format: uuid}
        occurred_at: {type: string, format: date-time}
        user:
          type: object
          additionalProperties: false
          required: [id, display_name]
          properties:
            id: {type: string, format: uuid}
            display_name: {type: string, maxLength: 255}
            phone: {type: string, minLength: 1, maxLength: 32}
        message:
          type: object
          additionalProperties: false
          required: [content_kind, text, files]
          properties:
            content_kind: {type: string, enum: [text, file]}
            text: {type: string, maxLength: 10000}
            files:
              type: array
              maxItems: 1
              items: {$ref: "#/components/schemas/OutboundFile"}