openapi: 3.0.3
info:
  title: Delta Messenger API
  version: "1.0"
  description: |
    Публичный HTTP API для сторонних сервисов и интеграций.

    ## Аутентификация

    Ключ выдаётся в админке (`/admin/`, вкладка «Сервисы / API-ключи»).
    Ключ начинается с префикса `svc_`. Передавайте его в заголовке:

    ```
    Authorization: Bearer svc_<ваш-ключ>
    ```

    Пользовательские эндпоинты (`/v1/auth/*`, `/v1/users/*`) принимают
    обычный JWT, выдаваемый при логине Android-клиента — для сторонних
    интеграций они не интересны и здесь не документированы.

    ## Доставка

    Сообщения, отправленные через `/v1/svc/messages`, доходят получателю
    как обычные входящие в его Android-клиенте, помеченные как «сервисные»
    (значок ⚙ в превью). Шифрование E2E на этом канале НЕ применяется —
    сервер хранит и пересылает текст «как есть».

servers:
  - url: https://messenger.delta.online
    description: Production

components:
  securitySchemes:
    serviceKey:
      type: http
      scheme: bearer
      bearerFormat: svc_xxx
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code: { type: string, example: AUTH_REQUIRED }
            message: { type: string }
    SendMessageRequest:
      type: object
      required: [text]
      properties:
        to_email:
          type: string
          format: email
          description: Email получателя. Один из `to_email` или `to_user_id` обязателен.
          example: user@example.com
        to_user_id:
          type: string
          format: uuid
          description: UUID получателя (если уже известен).
        text:
          type: string
          maxLength: 16000
          example: "Заказ #1234 принят, оператор ответит в течение 5 минут."
    SendMessageResponse:
      type: object
      properties:
        envelope_id:
          type: string
          format: uuid
          description: Идентификатор доставленного сообщения.
        status:
          type: string
          enum: [delivered, queued]
          description: |
            `delivered` — получатель сейчас онлайн, сообщение ушло сразу.
            `queued` — отдадим при следующем подключении (push отправлен).
    ServiceMe:
      type: object
      properties:
        service_id: { type: string, format: uuid }
        name: { type: string, example: crm-bridge }
        shadow_user_id: { type: string, format: uuid }
        created_at: { type: integer, format: int64, description: unix-ms }

security:
  - serviceKey: []

paths:
  /v1/svc/me:
    get:
      summary: Информация о текущем сервисе
      description: Полезно для смоук-теста ключа.
      tags: [Service]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceMe'
        "401":
          description: Ключ не передан/просрочен/отозван
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }

  /v1/svc/messages:
    post:
      summary: Отправить сообщение пользователю
      description: |
        Кладёт plaintext-сообщение в очередь получателю. У получателя
        в чатах появится сервисный диалог (имя — имя сервиса, иконка ⚙).

        Лимит длины — 16 000 символов. Файлы и медиа в этой версии не
        поддерживаются.
      tags: [Service]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SendMessageRequest' }
            examples:
              by_email:
                summary: Отправка по email
                value:
                  to_email: user@example.com
                  text: "Привет от CRM!"
              by_user_id:
                summary: Отправка по user_id (если уже известен)
                value:
                  to_user_id: 8aa10ea5-24bc-4d41-82ec-b0304c01b422
                  text: "Заказ #42 готов к выдаче."
      responses:
        "200":
          description: Принято к доставке
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SendMessageResponse' }
        "400":
          description: |
            Битый JSON (`BAD_JSON`), пустой текст (`EMPTY_TEXT`),
            длинный (`TOO_LONG`) или неверный user_id (`BAD_USER_ID`).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        "401":
          description: Невалидный/отозванный ключ
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        "404":
          description: Получатель с указанным email не найден.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }