openapi: 3.1.0
info:
  title: SMSintegrus API
  version: 1.0.0
  description: >
    Gateway de SMS — envio e leitura de respostas por canal autenticado.
    Toda requisição usa os headers `x-canal` (slug do canal) e
    `Authorization: Bearer <chave>`.
    Observação: se o canal tiver um "nome do remetente" configurado no painel,
    ele é antecedido automaticamente ao texto enviado (ex.: "AndCare - ...").
servers:
  - url: https://sms.integr.us/api
    description: Produção
  - url: http://localhost:8000/api
    description: Desenvolvimento
security:
  - ChannelHeader: []
    BearerAuth: []
paths:
  /messages:
    post:
      summary: Enviar mensagem
      operationId: sendMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
      responses:
        '201':
          description: Enfileirada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
        '401': { $ref: '#/components/responses/Unauthorized' }
        '422': { $ref: '#/components/responses/ValidationError' }
    get:
      summary: Listar envios
      operationId: listMessages
      parameters:
        - name: status
          in: query
          schema: { type: string, enum: [queued, sent, failed] }
        - name: per_page
          in: query
          schema: { type: integer, default: 50, maximum: 200 }
        - name: page
          in: query
          schema: { type: integer, default: 1 }
      responses:
        '200':
          description: Lista paginada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageList'
        '401': { $ref: '#/components/responses/Unauthorized' }
  /messages/{uuid}:
    get:
      summary: Status de um envio
      operationId: getMessage
      parameters:
        - name: uuid
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageStatus'
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /inbounds:
    get:
      summary: Listar respostas (inbound)
      operationId: listInbounds
      parameters:
        - name: per_page
          in: query
          schema: { type: integer, default: 50, maximum: 200 }
        - name: page
          in: query
          schema: { type: integer, default: 1 }
      responses:
        '200':
          description: Respostas correlacionadas ao canal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundList'
        '401': { $ref: '#/components/responses/Unauthorized' }
components:
  securitySchemes:
    ChannelHeader:
      type: apiKey
      in: header
      name: x-canal
      description: Slug do canal (origem da mensagem).
    BearerAuth:
      type: http
      scheme: bearer
      description: Chave de API do canal.
  responses:
    Unauthorized:
      description: Credenciais ausentes/invalidas ou canal inativo
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: Recurso não encontrado para o canal
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    ValidationError:
      description: Erro de validação
      content:
        application/json:
          schema:
            type: object
            properties:
              message: { type: string }
              errors: { type: object, additionalProperties: { type: array, items: { type: string } } }
  schemas:
    SendMessageRequest:
      type: object
      required: [phone, message]
      properties:
        phone: { type: string, example: '+5521981735100' }
        message: { type: string, maxLength: 1600, example: 'Olá! Responda #AND' }
    SendMessageResponse:
      type: object
      properties:
        uuid: { type: string, format: uuid }
        status: { type: string, example: queued }
    MessageStatus:
      type: object
      properties:
        uuid: { type: string, format: uuid }
        phone: { type: string }
        status: { type: string, enum: [queued, sent, failed] }
        error: { type: [string, 'null'] }
        sent_at: { type: [string, 'null'], format: date-time }
    Message:
      allOf:
        - $ref: '#/components/schemas/MessageStatus'
        - type: object
          properties:
            body: { type: string }
            code: { type: [string, 'null'] }
            created_at: { type: string, format: date-time }
    MessageList:
      type: object
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/Message' } }
        meta: { $ref: '#/components/schemas/PaginationMeta' }
    Inbound:
      type: object
      properties:
        uuid: { type: string, format: uuid }
        from: { type: string }
        message: { type: string }
        code: { type: [string, 'null'] }
        message_uuid: { type: [string, 'null'], format: uuid }
        received_at: { type: string, format: date-time }
    InboundList:
      type: object
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/Inbound' } }
        meta: { $ref: '#/components/schemas/PaginationMeta' }
    PaginationMeta:
      type: object
      properties:
        current_page: { type: integer }
        last_page: { type: integer }
        per_page: { type: integer }
        total: { type: integer }
    Error:
      type: object
      properties:
        error: { type: string }
