openapi: 3.1.0
info:
  title: ConectZap API
  version: 1.0.0-draft.1
  summary: API REST multi-tenant para instâncias WhatsApp.
  description: |
    Contrato **preliminar** da API pública do ConectZap (`/v1`).

    **Contrato próprio do ConectZap (ADR-026).** **Modelo de produto — API de passagem (ADR-025):** o ConectZap mantém sessões de WhatsApp Web
    ativas e conecta chatbots, ERPs e CRMs. **Não armazena conversas**: mensagens recebidas, status de
    entrega e eventos de conexão chegam **somente** por webhook (e realtime). Não há endpoints de
    histórico, contatos ou conversas guardados. Consultas como grupos e verificação de número são
    feitas ao vivo na sessão. Mídia recebida fica disponível por URL temporária (padrão 24 h). Este arquivo é a fonte
    de verdade do contrato: o código do gateway é gerado/validado a partir dele
    (ver `conectzap-code-standards`).

    ## Convenções
    - Autenticação: `Authorization: Bearer <api_key>` (chave por tenant, com escopos).
    - IDs públicos são opacos e prefixados (`inst_`, `msg_`, `whk_`, `med_`, `key_`, `evt_`, `dlv_`, `iev_`).
    - Erros seguem RFC 9457 (`application/problem+json`) com `code` estável.
    - Paginação por cursor (`limit`, `cursor`) — nunca por offset.
    - `POST` que cria efeitos aceita `Idempotency-Key` (24 h de retenção).
    - Envio de mensagens é **assíncrono**: `202 Accepted` + status `queued`; o resultado
      final chega por webhook / realtime (`message.sent`, `message.updated`, `message.failed`).
    - Idioma: `Accept-Language` escolhe `pt-BR` (padrão), `en` ou `es` para os textos de erro; o contrato (caminhos, campos, `code`, enums) não depende do idioma (ADR-034).
    - Datas em RFC 3339 UTC.
    - Recursos marcados com `x-conectzap-tier: optional` não fazem parte do MVP.
    - **Estabilidade:** enquanto a versão for `1.0.0-draft.*` o contrato pode mudar. A partir do GA
      (Fase 08) `/v1` fica congelado: apenas adições compatíveis.
    - Telefones: E.164 **somente dígitos, sem `+`**.
    - Usuários, convites e papéis do painel são geridos pelo AuthGateway (interno, não público), fora de `/v1` nesta versão.
    - **Painel (ADR-045):** o painel do cliente (`app.conectzap.app`) usa as operações de conta, instância, webhook e `createRealtimeTicket` por uma ponte de sessão do AuthGateway (`/api/v1/*`, interna, não pública), com os escopos do papel da pessoa. Não há contrato novo: as respostas são as mesmas deste documento. O painel não monta as rotas de mensagem, mídia, contatos, grupos nem chaves de API de `/v1`.
    - Chaves restritas a instâncias não acessam recursos de tenant inteiro (`/account`, `/api-keys`, webhooks sem `instanceId`, mídia de upload): `403 forbidden`.

    ## Limites de taxa
    Respostas incluem `RateLimit-Policy`, `RateLimit` e, em `429`, `Retry-After`.
    Os limites dependem do plano do tenant.

    ## Aviso
    O runtime atual usa um cliente **não oficial** do WhatsApp Web (Baileys). Recursos
    podem mudar sem aviso por decisão da Meta. O contrato é independente de provedor
    (campo `provider` da instância) para permitir a API oficial Cloud API no futuro.
  contact:
    name: ConectZap
    url: https://docs.conectzap.app
servers:
  - url: https://api.conectzap.app/v1
    description: Produção (ambiente único, ADR-023)
security:
  - apiKey: []
tags:
  - name: Instances
  - name: Messages
  - name: Media
  - name: Contacts
  - name: Chats
  - name: Groups
  - name: Webhooks
  - name: Realtime
  - name: Account
  - name: Health

paths:
  /health:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
    get:
      tags: [Health]
      operationId: getHealth
      summary: Verificação de saúde do gateway (pública, sem dados internos).
      security: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Health' }
        default: { $ref: '#/components/responses/Error' }

  /account:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
    get:
      tags: [Account]
      operationId: getAccount
      summary: Tenant atual, plano, limites e uso.
      x-required-scopes: [account:read]
      responses:
        '200':
          description: OK
          headers:
            RateLimit-Policy: { $ref: '#/components/headers/RateLimit-Policy' }
            RateLimit: { $ref: '#/components/headers/RateLimit' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Account' }
        '401': { $ref: '#/components/responses/Error' }
        '403': { $ref: '#/components/responses/Error' }
        '429': { $ref: '#/components/responses/Error' }
        default: { $ref: '#/components/responses/Error' }

  /instances:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
    get:
      tags: [Instances]
      operationId: listInstances
      summary: Lista instâncias do tenant.
      x-required-scopes: [instances:read]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - name: status
          in: query
          schema: { $ref: '#/components/schemas/InstanceStatus' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - type: object
                    properties:
                      data:
                        type: array
                        items: { $ref: '#/components/schemas/Instance' }
        default: { $ref: '#/components/responses/Error' }
    post:
      tags: [Instances]
      operationId: createInstance
      summary: Cria uma instância lógica (não conecta automaticamente).
      description: |
        Falha com `409 plan_limit_reached` se o limite de números do plano foi atingido.
        Falha com `403 forbidden` se a API Key está restrita a instâncias específicas
        (uma chave restrita não cria instâncias novas).
      x-required-scopes: [instances:write]
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateInstanceRequest' }
      responses:
        '201':
          description: Criada
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Instance' }
        '403':
          $ref: '#/components/responses/Error'
        default: { $ref: '#/components/responses/Error' }

  /instances/{instanceId}:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/InstanceId'
    get:
      tags: [Instances]
      summary: Consulta uma instância.
      operationId: getInstance
      x-required-scopes: [instances:read]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Instance' }
        default: { $ref: '#/components/responses/Error' }
    patch:
      tags: [Instances]
      operationId: updateInstance
      summary: Atualiza nome e configurações da instância.
      x-required-scopes: [instances:write]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateInstanceRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Instance' }
        default: { $ref: '#/components/responses/Error' }
    delete:
      tags: [Instances]
      operationId: deleteInstance
      summary: Faz logout, encerra o runtime e agenda a remoção dos dados.
      description: |
        Exclusão lógica imediata; credenciais Signal são apagadas imediatamente;
        mensagens e mídia são removidas conforme a política de retenção (LGPD).
        Responde `202` com a instância em `deleting` mesmo quando o runtime está inacessível: o
        logout no aparelho e a liberação da vaga são repetidos em segundo plano. Depois disso a
        instância deixa de existir para a API (um segundo `DELETE` responde `404 not_found`).
      x-required-scopes: [instances:delete]
      responses:
        '202':
          description: Remoção agendada (instância em `deleting`).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Instance' }
        default: { $ref: '#/components/responses/Error' }

  /instances/{instanceId}/connect:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/InstanceId'
    post:
      tags: [Instances]
      operationId: connectInstance
      summary: Inicia o runtime e o pareamento (QR Code ou código de pareamento).
      description: |
        Idempotente: se já houver um pareamento ou uma sessão em andamento, repetir a chamada (mesmo
        com outro `method`) devolve o estado, o `method` e o `pairingCode` atuais, sem iniciar outro
        pareamento. Para trocar de método, chame `disconnect` antes.
        Instância em `banned` → `409 conflict`.
        Durante a pausa automática por restrição temporária (`pausedUntil` no futuro, visível em
        `GET /instances/{id}/status`) → `409 conflict` com `Retry-After` (segundos até `pausedUntil`).
        O cabeçalho `Idempotency-Key` é aceito, mas a resposta não é guardada; a idempotência vem do
        estado da instância.
        Responde `503 provider_unavailable` com `Retry-After` quando não há vaga em container para
        iniciar o runtime; tente de novo após o intervalo indicado.
        O QR Code é renovado periodicamente pelo WhatsApp; acompanhe por
        `GET /instances/{id}/qr`, realtime (`instance.qr.updated`) ou webhook.
      x-required-scopes: [instances:connect]
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ConnectRequest' }
      responses:
        '202':
          description: Pareamento iniciado
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ConnectResponse' }
        '503':
          $ref: '#/components/responses/Error'
        default: { $ref: '#/components/responses/Error' }

  /instances/{instanceId}/qr:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/InstanceId'
    get:
      tags: [Instances]
      operationId: getInstanceQr
      summary: QR Code atual (se a instância estiver aguardando pareamento).
      description: |
        Responde `409 conflict` quando não há QR válido: a instância não está em `pairing`
        ou o QR atual expirou.
      x-required-scopes: [instances:connect]
      parameters:
        - name: format
          in: query
          schema: { type: string, enum: [raw, png_base64], default: raw }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/QrCode' }
        '409':
          $ref: '#/components/responses/Error'
        default: { $ref: '#/components/responses/Error' }

  /instances/{instanceId}/disconnect:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/InstanceId'
    post:
      tags: [Instances]
      operationId: disconnectInstance
      summary: Desconecta o número.
      description: |
        `logout=true` encerra a sessão no WhatsApp e apaga as credenciais (exige novo pareamento);
        `phoneNumber` e `profileName` voltam a `null`.
        Se a instância não tem runtime ativo (ex.: `disconnected` ou `failed`), `logout=true` apaga as
        credenciais, mas não consegue desvincular o aparelho no celular: remova-o em
        "Aparelhos conectados" no WhatsApp.
        `logout=false` apenas para o runtime (as credenciais permanecem; reconecta em `connect`).
        Sem corpo equivale a `logout=false`.
      x-required-scopes: [instances:connect]
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                logout: { type: boolean, default: false }
      responses:
        '202':
          description: Desconexão iniciada
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Instance' }
        default: { $ref: '#/components/responses/Error' }

  /instances/{instanceId}/restart:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/InstanceId'
    post:
      tags: [Instances]
      operationId: restartInstance
      summary: Reinicia o runtime preservando credenciais.
      description: |
        Recria a conexão com as credenciais atuais (nunca pede QR). Em `connected` ou `reconnecting`
        a instância passa por `reconnecting`; em `failed` ou `disconnected` (com credenciais) volta a
        subir e responde `starting`. Instância sem credenciais (nunca pareada ou após `logout`) →
        `409 conflict`; use `connect`. Sem vaga em container → `503 provider_unavailable` com
        `Retry-After`.
        Durante a pausa automática por restrição temporária (`pausedUntil` no futuro, visível em
        `GET /instances/{id}/status`), o reinício não antecipa a reconexão: em `reconnecting` ela
        continua agendada para `pausedUntil` (`202`); parada (`disconnected` ou `failed`) responde
        `409 conflict` com `Retry-After` (segundos até `pausedUntil`).
        Não tem corpo: um corpo não vazio é recusado (`413` acima de 64 KB, `415` com outro
        `content-type`, `400` com JSON).
      x-required-scopes: [instances:connect]
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '202':
          description: Reinício agendado
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Instance' }
        default: { $ref: '#/components/responses/Error' }

  /instances/{instanceId}/status:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/InstanceId'
    get:
      tags: [Instances]
      summary: Consulta o status de conexão de uma instância.
      operationId: getInstanceStatus
      x-required-scopes: [instances:read]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InstanceStatusDetail' }
        default: { $ref: '#/components/responses/Error' }

  /instances/{instanceId}/events:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/InstanceId'
    get:
      tags: [Instances]
      operationId: listInstanceEvents
      summary: Histórico de transições de status da instância (auditoria operacional).
      description: |
        Devolve `InstanceLogEntry` (não o envelope `Event`): uma linha por transição de status da
        instância, mais recente primeiro, com **30 dias de retenção**. Transições muito rápidas são
        agrupadas ("a última vence"), e linhas em que `from` e `to` são iguais ficam de fora. A linha
        não tem `revision`, `Instance` nem `evt_` e nunca traz telefone. Para o evento completo use
        webhook ou tempo real.
      x-conectzap-sprint: 7
      x-required-scopes: [instances:read]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - name: type
          in: query
          description: Tipo da linha. Hoje só existe `status`.
          schema: { type: string, enum: [status] }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - type: object
                    properties:
                      data:
                        type: array
                        items: { $ref: '#/components/schemas/InstanceLogEntry' }
        default: { $ref: '#/components/responses/Error' }

  /instances/{instanceId}/metrics:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/InstanceId'
    get:
      tags: [Instances]
      operationId: getInstanceMetrics
      summary: Métricas agregadas (mensagens, falhas, uptime) por período.
      description: |
        Séries por intervalo (`bucket`) com contadores de mensagens enviadas, recebidas e com falha e o
        tempo conectado. Regras:
        - `from` deve ser anterior a `to`;
        - a janela (`to - from`) tem no máximo **31 dias** com `granularity=hour` e **90 dias** com `granularity=day`;
        - os intervalos são em **UTC** (`bucket` é o início do intervalo);
        - intervalos sem dados vêm com **zeros**;
        - o intervalo que contém `from` entra inteiro (com `hour`, até 745 intervalos);
        - a retenção é de **90 dias** (ESTIMADO).

        O que conta:
        - `received`: só mensagens **de fora** (`message.received`, sempre com `direction: inbound`).
          Mensagens enviadas pelo próprio celular da conta não geram `message.received` nem
          `message.sent` (só os recibos delas chegam, como `message.updated` sem `id`) e não entram em
          nenhum contador;
        - `sent` e `failed`: os envios feitos por esta API (`message.sent` e `message.failed`);
        - cada mensagem conta na hora do seu `occurredAt` (presa aos últimos 90 dias e ao momento atual);
        - `connectedSeconds`: tempo em `connected`, inclusive o trecho em curso.

        Violar qualquer regra devolve `400 validation_failed`. A contagem é *at-least-once*: após uma
        falha da instância pode contar a mais.
      x-conectzap-sprint: 7
      x-required-scopes: [instances:read]
      parameters:
        - name: from
          in: query
          required: true
          description: Início da janela (inclusive), anterior a `to`.
          schema: { type: string, format: date-time }
        - name: to
          in: query
          required: true
          description: Fim da janela (exclusivo).
          schema: { type: string, format: date-time }
        - name: granularity
          in: query
          schema: { type: string, enum: [hour, day], default: day }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InstanceMetrics' }
        default: { $ref: '#/components/responses/Error' }

  /instances/{instanceId}/messages:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/InstanceId'
    post:
      tags: [Messages]
      operationId: sendMessage
      x-conectzap-sprint: 6
      summary: Enfileira o envio de uma mensagem.
      description: |
        Retorna `202` com o id e o status `queued`; o conteúdo **não é guardado**. O resultado chega por
        webhook (`message.sent` / `message.failed`, depois `message.updated` com entrega e leitura).
        A fila da instância espaça os envios (intervalo do plano + `delaySeconds`). A instância precisa estar `connected`,
        caso contrário `409 instance_not_connected`. Mídia pode ser referenciada por
        `mediaId` (upload prévio) ou `url` (HTTPS público, baixado pela plataforma
        com limite de tamanho e tipo). Mídia (`image`, `video`, `audio`, `document`) é entregue na Parte II do Sprint 6;
        a Parte I cobre `text`, `location`, `contact`, `poll` e `reaction`.
      x-required-scopes: [messages:send]
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyRequired'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SendMessageRequest' }
      responses:
        '202':
          description: Enfileirada
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SendMessageAccepted' }
        default: { $ref: '#/components/responses/Error' }
  /instances/{instanceId}/messages/{messageId}:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/MessageId'
    patch:
      tags: [Messages]
      operationId: editMessage
      summary: Edita o texto de uma mensagem enviada pela instância.
      description: |
        Retorna `202`; o resultado chega por webhook (`message.updated` ou `message.failed`). Só vale para mensagens
        de **texto enviadas por esta plataforma**. O WhatsApp limita a edição a cerca de 15 minutos após o envio;
        o erro do provedor vira `message.failed`. Id desconhecido ou expirado (o mapa de ids dura 7 dias, ESTIMADO)
        retorna `404 message_not_found`. A instância precisa estar `connected` (`409 instance_not_connected`).
      x-conectzap-sprint: 6
      x-required-scopes: [messages:send]
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyRequired'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EditMessageRequest' }
      responses:
        '202':
          description: Edição enfileirada
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MessageActionAccepted' }
        '404':
          description: Mensagem desconhecida ou expirada (`message_not_found`).
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }
        default: { $ref: '#/components/responses/Error' }
    delete:
      tags: [Messages]
      operationId: deleteMessage
      summary: Apaga para todos uma mensagem enviada pela instância.
      description: |
        Retorna `202`; o resultado chega por webhook (`message.updated` com status `deleted` ou `message.failed`).
        Só vale para mensagens **enviadas por esta plataforma**. Id desconhecido ou expirado retorna
        `404 message_not_found`. A instância precisa estar `connected` (`409 instance_not_connected`).
      x-conectzap-sprint: 6
      x-required-scopes: [messages:send]
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyRequired'
      responses:
        '202':
          description: Exclusão enfileirada
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MessageActionAccepted' }
        '404':
          description: Mensagem desconhecida ou expirada (`message_not_found`).
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }
        default: { $ref: '#/components/responses/Error' }
  /media/uploads:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
    post:
      tags: [Media]
      operationId: createMediaUpload
      x-conectzap-sprint: 6
      summary: Cria um upload direto para o armazenamento (URL pré-assinada de curta duração).
      x-required-scopes: [messages:send]
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      description: |
        O objeto só fica `ready` após a plataforma confirmar tamanho, SHA-256 e tipo real (*magic bytes*)
        compatível com `mimeType`. `sizeBytes` acima do limite do plano (`plan.maxMediaMb`, padrão 64 MB)
        retorna `413 payload_too_large`; 100 MB é o teto absoluto do contrato.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [mimeType, sizeBytes, sha256]
              properties:
                mimeType:
                  type: string
                  enum: [image/jpeg, image/png, image/webp, video/mp4, video/3gpp, audio/ogg, audio/mpeg, audio/mp4, audio/aac, application/pdf, application/zip, text/plain, text/csv, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.openxmlformats-officedocument.presentationml.presentation]
                sizeBytes: { type: integer, minimum: 1, maximum: 104857600 }
                sha256: { type: string, pattern: '^[a-f0-9]{64}$' }
                fileName: { type: string, maxLength: 255 }
      responses:
        '201':
          description: URL de upload criada
          content:
            application/json:
              schema:
                type: object
                properties:
                  mediaId: { type: string }
                  uploadUrl:
                    type: string
                    format: uri
                    description: URL assinada de `uploadMediaContent` (com `tid`, `exp` e `sig`); usar exatamente como veio.
                  method: { type: string, const: PUT }
                  requiredHeaders: { type: object, additionalProperties: { type: string } }
                  expiresAt:
                    type: string
                    format: date-time
                    description: Validade da `uploadUrl` (15 minutos). Repetir a criação com o mesmo `Idempotency-Key` devolve o mesmo `mediaId` com uma URL nova.
        default: { $ref: '#/components/responses/Error' }

  /media/{mediaId}:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - name: mediaId
        in: path
        required: true
        schema: { type: string, pattern: '^med_[0-9A-Za-z]{20,32}$' }
    get:
      tags: [Media]
      operationId: getMedia
      x-conectzap-sprint: 6
      summary: URL temporária de download de mídia (recebida ou enviada); a mídia fica disponível por 24 h (retenção fixa).
      x-required-scopes: [messages:read]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Media' }
        default: { $ref: '#/components/responses/Error' }

  /media/uploads/{mediaId}/content:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - name: mediaId
        in: path
        required: true
        schema: { type: string, pattern: '^med_[0-9A-Za-z]{20,32}$' }
      - $ref: '#/components/parameters/SignedTid'
      - $ref: '#/components/parameters/SignedExp'
      - $ref: '#/components/parameters/SignedSig'
    put:
      tags: [Media]
      operationId: uploadMediaContent
      x-conectzap-sprint: 6
      security: []
      summary: Envia o conteúdo do arquivo para a URL assinada devolvida por `POST /media/uploads`.
      description: |
        **Sem API Key:** a assinatura (`sig`, HMAC sobre método, caminho, `mediaId`, `exp` e tenant `tid`) é a credencial;
        `exp` vale no máximo 15 minutos. O uso é único: depois de `ready`, nova tentativa retorna `409 already_uploaded`.
        O corpo é o arquivo bruto, em stream (nunca inteiro em memória), com `Content-Type` igual ao `mimeType`
        declarado na criação. A plataforma confere tamanho, SHA-256 e tipo real (*magic bytes*); divergência apaga o
        objeto e o torna `failed`. Retorna `204` sem corpo; o objeto fica disponível por 24 h.
        Parâmetros do `Content-Type` (ex.: `; charset=utf-8`) são ignorados; o tipo em si (sem diferenciar
        maiúsculas) tem de ser o declarado. `application/octet-stream` não é aceito.
        Erros: `validation_failed` 400 (tamanho ou SHA-256 diferente do declarado) · `invalid_signature` 403 ·
        `forbidden` 403 (`tenant_inactive`: tenant suspenso) · `media_not_found` 404 · `upload_expired` 410 ·
        `already_uploaded` 409 · `payload_too_large` 413 · `unsupported_media_type` 415 · `media_type_mismatch` 422.
      requestBody:
        required: true
        description: Bytes do arquivo (até 100 MB; limite do plano em `plan.maxMediaMb`).
        content:
          image/jpeg:
            schema: { type: string, format: binary }
          image/png:
            schema: { type: string, format: binary }
          image/webp:
            schema: { type: string, format: binary }
          video/mp4:
            schema: { type: string, format: binary }
          video/3gpp:
            schema: { type: string, format: binary }
          audio/ogg:
            schema: { type: string, format: binary }
          audio/mpeg:
            schema: { type: string, format: binary }
          audio/mp4:
            schema: { type: string, format: binary }
          audio/aac:
            schema: { type: string, format: binary }
          application/pdf:
            schema: { type: string, format: binary }
          application/zip:
            schema: { type: string, format: binary }
          text/plain:
            schema: { type: string, format: binary }
          text/csv:
            schema: { type: string, format: binary }
          application/msword:
            schema: { type: string, format: binary }
          application/vnd.openxmlformats-officedocument.wordprocessingml.document:
            schema: { type: string, format: binary }
          application/vnd.ms-excel:
            schema: { type: string, format: binary }
          application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
            schema: { type: string, format: binary }
          application/vnd.openxmlformats-officedocument.presentationml.presentation:
            schema: { type: string, format: binary }
      responses:
        '204':
          description: Conteúdo gravado; a mídia fica `ready`.
        '400':
          description: Tamanho ou SHA-256 diferente do declarado (`validation_failed`); a mídia fica `failed`.
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }
        '403':
          description: Assinatura inválida (`invalid_signature`) ou tenant suspenso (`forbidden`, `tenant_inactive`).
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }
        '404':
          description: Mídia desconhecida, de outro tenant ou vencida (`media_not_found`).
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }
        '409':
          description: Upload já concluído (`already_uploaded`).
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }
        '410':
          description: URL de upload vencida (`upload_expired`).
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }
        '413':
          description: Arquivo acima do limite (`payload_too_large`).
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }
        '415':
          description: Tipo não suportado (`unsupported_media_type`).
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }
        '422':
          description: Tipo real diferente do declarado (`media_type_mismatch`).
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }
        default: { $ref: '#/components/responses/Error' }

  /media/{mediaId}/content:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - name: mediaId
        in: path
        required: true
        schema: { type: string, pattern: '^med_[0-9A-Za-z]{20,32}$' }
      - $ref: '#/components/parameters/SignedTid'
      - $ref: '#/components/parameters/SignedExp'
      - $ref: '#/components/parameters/SignedSig'
    get:
      tags: [Media]
      operationId: downloadMediaContent
      x-conectzap-sprint: 6
      security: []
      summary: Baixa o conteúdo da mídia pela URL assinada (`downloadUrl` de `GET /media/{mediaId}`).
      description: |
        **Sem API Key:** a assinatura (`sig`, que cobre também `tid`) é a credencial; `exp` vale no máximo 15 minutos. O conteúdo é
        transmitido em stream, com `Content-Type` do arquivo, `Content-Disposition: attachment; filename="{mediaId}.{ext}"`
        (o nome original nunca é guardado), `Content-Security-Policy: default-src 'none'; sandbox`,
        `X-Content-Type-Options: nosniff` e `Cache-Control: private, no-store`. Mídia vencida
        (retenção de 24 h) ou de outro tenant retorna `404 media_not_found`; assinatura inválida, `403 invalid_signature`.
      responses:
        '200':
          description: Conteúdo do arquivo.
          headers:
            Content-Type:
              required: true
              schema: { type: string }
            Content-Disposition:
              required: true
              description: '`attachment; filename="{mediaId}.{ext}"`, com a extensão do `mimeType` (ex.: `med_….jpg`).'
              schema: { type: string }
            Content-Security-Policy:
              required: true
              description: "Sempre `default-src 'none'; sandbox` (o arquivo nunca roda como página no domínio da API)."
              schema: { type: string }
            X-Content-Type-Options:
              required: true
              description: Sempre `nosniff`.
              schema: { type: string }
            Cache-Control:
              required: true
              description: Sempre `private, no-store`.
              schema: { type: string }
            Content-Length:
              schema: { type: integer }
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        '403':
          description: Assinatura inválida ou vencida (`invalid_signature`).
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }
        '404':
          description: Mídia desconhecida ou expirada (`media_not_found`).
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }
        default: { $ref: '#/components/responses/Error' }

  /instances/{instanceId}/contacts/check:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/InstanceId'
    post:
      tags: [Contacts]
      operationId: checkNumbers
      summary: Verifica se números possuem WhatsApp (lote pequeno; sujeito a rate limit rígido).
      description: |
        Até 50 números por lote e no máximo 1 lote a cada 10 s por instância (ESTIMADO); acima disso
        `429 rate_limited` com `Retry-After`. Instância em pausa automática → `409 instance_paused` com
        `Retry-After`; fora de `connected` → `409 instance_not_connected`. Nada é armazenado.
      x-required-scopes: [contacts:read]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [phoneNumbers]
              properties:
                phoneNumbers:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items: { $ref: '#/components/schemas/PhoneNumber' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        phoneNumber: { $ref: '#/components/schemas/PhoneNumber' }
                        exists: { type: boolean }
                        chatId: { type: [string, 'null'] }
        default: { $ref: '#/components/responses/Error' }

  /instances/{instanceId}/chats/{chatId}/read:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/ChatId'
    post:
      tags: [Chats]
      operationId: markChatRead
      summary: Marca mensagens do chat como lidas.
      description: |
        Marca como lida a última mensagem recebida do chat que a plataforma ainda conhece (mapa de ids de
        7 dias, ESTIMADO); o WhatsApp marca as anteriores junto. `chatId` é o dos eventos (JID de pessoa
        ou de grupo; para um contato `@lid`, vale o JID de telefone mostrado no evento ou o `@lid`).
        Nenhuma mensagem conhecida no chat → `404 message_not_found`.
      x-conectzap-tier: optional
      x-required-scopes: [messages:send]
      responses:
        '202': { description: Aceito }
        default: { $ref: '#/components/responses/Error' }

  /instances/{instanceId}/groups:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/InstanceId'
    get:
      tags: [Groups]
      operationId: listGroups
      summary: Grupos dos quais o número participa (consulta ao vivo na sessão do WhatsApp; nada é armazenado).
      description: |
        A lista é lida ao vivo e reaproveitada pela paginação por até 60 s. Conta com mais de 2.000
        grupos, ou lista acima de 4 MiB, → `503 provider_unavailable` (teto ESTIMADO).
      x-required-scopes: [groups:read]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - type: object
                    properties:
                      data:
                        type: array
                        items: { $ref: '#/components/schemas/Group' }
        default: { $ref: '#/components/responses/Error' }

  /instances/{instanceId}/groups/{groupId}:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/InstanceId'
      - name: groupId
        in: path
        required: true
        schema: { type: string, pattern: '^[0-9-]+@g\.us$' }
    get:
      tags: [Groups]
      operationId: getGroup
      summary: Metadados e participantes do grupo.
      x-required-scopes: [groups:read]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Group' }
        default: { $ref: '#/components/responses/Error' }

  /webhooks:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
    get:
      tags: [Webhooks]
      summary: Lista os webhooks do tenant.
      operationId: listWebhooks
      x-conectzap-sprint: 7
      x-required-scopes: [webhooks:read]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - type: object
                    properties:
                      data:
                        type: array
                        items: { $ref: '#/components/schemas/Webhook' }
        default: { $ref: '#/components/responses/Error' }
    post:
      tags: [Webhooks]
      operationId: createWebhook
      x-conectzap-sprint: 7
      summary: Cria endpoint de webhook (tenant inteiro ou instância específica).
      description: |
        A URL deve ser HTTPS pública. Endereços privados, loopback, link-local e
        metadados de nuvem são rejeitados (proteção SSRF), inclusive após resolução DNS
        no momento da entrega. O `secret` é retornado **somente** nesta resposta.

        Esta operação **não** aceita `Idempotency-Key`: a resposta leva o segredo, que não pode ficar
        guardado como resposta idempotente (mesma regra de `createApiKey`). Repetir a chamada cria outro webhook.
      x-required-scopes: [webhooks:write]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateWebhookRequest' }
      responses:
        '201':
          description: Criado
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Webhook'
                  - type: object
                    properties:
                      secret: { type: string, description: 'Segredo HMAC (exibido uma única vez).' }
        default: { $ref: '#/components/responses/Error' }

  /webhooks/{webhookId}:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/WebhookId'
    get:
      tags: [Webhooks]
      summary: Consulta um webhook.
      operationId: getWebhook
      x-conectzap-sprint: 7
      x-required-scopes: [webhooks:read]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Webhook' }
        default: { $ref: '#/components/responses/Error' }
    patch:
      tags: [Webhooks]
      summary: Atualiza um webhook.
      operationId: updateWebhook
      x-conectzap-sprint: 7
      x-required-scopes: [webhooks:write]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateWebhookRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Webhook' }
        default: { $ref: '#/components/responses/Error' }
    delete:
      tags: [Webhooks]
      summary: Remove um webhook.
      operationId: deleteWebhook
      x-conectzap-sprint: 7
      x-required-scopes: [webhooks:write]
      responses:
        '204': { description: Removido }
        default: { $ref: '#/components/responses/Error' }

  /webhooks/{webhookId}/rotate-secret:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/WebhookId'
    post:
      tags: [Webhooks]
      operationId: rotateWebhookSecret
      x-conectzap-sprint: 7
      summary: Gera novo segredo; o anterior permanece válido por 24 h (assinatura dupla).
      description: |
        Esta operação **não** aceita `Idempotency-Key`: a resposta leva o segredo novo, que não pode ficar
        guardado como resposta idempotente (mesma regra de `createApiKey`).
      x-required-scopes: [webhooks:write]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  secret: { type: string }
                  previousSecretExpiresAt: { type: string, format: date-time }
        default: { $ref: '#/components/responses/Error' }

  /webhooks/{webhookId}/test:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/WebhookId'
    post:
      tags: [Webhooks]
      operationId: testWebhook
      x-conectzap-sprint: 7
      summary: Envia um evento `webhook.test` assinado e retorna o diagnóstico.
      description: |
        A entrega é síncrona: não passa pela fila nem pelo controle de concorrência do endpoint e não altera
        o estado de falha do webhook. Devolve `200` com `WebhookTestResult` mesmo quando o endpoint falha
        (`ok: false` e o código em `error`), inclusive quando o DNS do host não pôde ser conferido
        (`dns_blocked`) ou o segredo do webhook não pôde ser aberto (`secret_unavailable`).
        Limite próprio: 1 teste a cada 10 s por webhook; acima disso, `429` (`rate_limited`) com
        `Retry-After`.
      x-required-scopes: [webhooks:write]
      responses:
        '200':
          description: Resultado do teste
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WebhookTestResult' }
        '429': { $ref: '#/components/responses/Error' }
        default: { $ref: '#/components/responses/Error' }

  /webhooks/{webhookId}/deliveries:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/WebhookId'
    get:
      tags: [Webhooks]
      operationId: listWebhookDeliveries
      x-conectzap-sprint: 7
      summary: Falhas de entrega dos últimos 7 dias (metadados, sem payload). Entregas bem-sucedidas aparecem só nas métricas.
      x-required-scopes: [webhooks:read]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - name: status
          in: query
          schema: { type: string, enum: [retrying, dead] }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - type: object
                    properties:
                      data:
                        type: array
                        items: { $ref: '#/components/schemas/WebhookDelivery' }
        default: { $ref: '#/components/responses/Error' }

  /api-keys:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
    get:
      tags: [Account]
      operationId: listApiKeys
      summary: Lista chaves do tenant (somente metadados; o segredo nunca é retornado).
      x-required-scopes: [api_keys:read]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: OK
          headers:
            RateLimit-Policy: { $ref: '#/components/headers/RateLimit-Policy' }
            RateLimit: { $ref: '#/components/headers/RateLimit' }
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - type: object
                    properties:
                      data:
                        type: array
                        items: { $ref: '#/components/schemas/ApiKey' }
        '401': { $ref: '#/components/responses/Error' }
        '403': { $ref: '#/components/responses/Error' }
        '429': { $ref: '#/components/responses/Error' }
        default: { $ref: '#/components/responses/Error' }
    post:
      tags: [Account]
      operationId: createApiKey
      summary: Cria chave com escopos ⊆ escopos do chamador. O valor completo é exibido uma única vez.
      description: |
        Não aceita `Idempotency-Key`: a resposta contém o segredo, que não pode ser guardado para replay.
        Repetir a chamada cria outra chave; revogue a que sobrar.
      x-required-scopes: [api_keys:write]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [name, scopes]
              properties:
                name: { type: string, minLength: 1, maxLength: 80 }
                scopes:
                  type: array
                  minItems: 1
                  items: { $ref: '#/components/schemas/Scope' }
                instanceIds:
                  type: array
                  maxItems: 100
                  items: { type: string, pattern: '^inst_[0-9A-Za-z]{20,32}$' }
                expiresAt: { type: string, format: date-time }
      responses:
        '201':
          description: Criada
          headers:
            RateLimit-Policy: { $ref: '#/components/headers/RateLimit-Policy' }
            RateLimit: { $ref: '#/components/headers/RateLimit' }
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiKey'
                  - type: object
                    properties:
                      key: { type: string, description: 'Valor completo (exibido uma única vez).' }
        '401': { $ref: '#/components/responses/Error' }
        '403': { $ref: '#/components/responses/Error' }
        '429': { $ref: '#/components/responses/Error' }
        default: { $ref: '#/components/responses/Error' }

  /api-keys/{apiKeyId}:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
      - name: apiKeyId
        in: path
        required: true
        schema: { type: string, pattern: '^key_[0-9A-Za-z]{20,32}$' }
    delete:
      tags: [Account]
      operationId: revokeApiKey
      summary: Revoga a chave.
      description: Efetiva em até 30 s em operação normal; durante indisponibilidade do Control Plane, chaves já validadas podem continuar aceitas por até 5 min (ADR-008).
      x-required-scopes: [api_keys:write]
      responses:
        '204':
          description: Revogada
          headers:
            RateLimit-Policy: { $ref: '#/components/headers/RateLimit-Policy' }
            RateLimit: { $ref: '#/components/headers/RateLimit' }
        '401': { $ref: '#/components/responses/Error' }
        '403': { $ref: '#/components/responses/Error' }
        '429': { $ref: '#/components/responses/Error' }
        default: { $ref: '#/components/responses/Error' }

  /realtime/tickets:
    parameters:
      - $ref: '#/components/parameters/AcceptLanguage'
    post:
      tags: [Realtime]
      operationId: createRealtimeTicket
      summary: Emite ticket de uso único (TTL 60 s) para abrir o WebSocket em realtime.conectzap.app.
      description: |
        Conexão: `wss://realtime.conectzap.app/v1/stream?ticket=<ticket>`. A chave de API nunca
        trafega na URL do WebSocket. Esta operação **não** aceita `Idempotency-Key`: a resposta leva o
        ticket (segredo de uso único) e não pode ficar guardada. Repetir o pedido emite outro ticket,
        o que é inofensivo.

        **Ticket.** Vale 60 s e uma única conexão. O formato é opaco; não o registre em log.

        **Escopo.** `instanceIds` ausente ou vazio = todas as instâncias da chave. Instância fora da
        chave devolve `403`. Chave restrita a instâncias nunca recebe evento sem instância
        (`webhook.failed` de webhook do tenant inteiro). `events` ausente ou vazio = todos os tipos
        que a chave pode ler (`webhook.test` não é entregue em tempo real).

        **Escopos por tipo de evento.** `realtime:subscribe` só abre o canal; cada tipo exige também
        o escopo de leitura do conteúdo: `message.*` exige `messages:read`; `instance.qr.updated`
        exige `instances:connect`; os demais `instance.*` exigem `instances:read`; `webhook.failed`
        exige `webhooks:read`. Sem `events`, o ticket leva só os tipos permitidos. Pedir um tipo
        que a chave não pode ler, ou ter uma chave que não lê tipo nenhum, devolve `403 forbidden`.

        **Erros do *upgrade*.** `401` ticket inválido, vencido ou já usado; `403` `Origin` não
        permitido (sem `Origin`, como num cliente de servidor, é aceito; num navegador só
        `https://app.conectzap.app`); `429` limite por IP ou de conexões do tenant (50, ESTIMADO).

        **Mensagens do cliente** (JSON, até 4 KB, até 10 por segundo; mais que isso fecha com `1008`):
        `ping` (resposta `pong`), `resume {cursor}` e `subscribe {instanceIds?, events?}`. O
        `subscribe` só restringe: nunca alarga o escopo do ticket. Um `resume` por conexão a cada
        10 s (ESTIMADO): repetir antes disso devolve `error rate_limited`, e a 3ª repetição fecha
        com `1008`.

        **Mensagens do servidor.** `ready {cursor, reauthAt}` ao conectar; `events {items}` em lote
        (até 100 itens e 512 KB por frame, ESTIMADO), cada item com seu `cursor`; `resumed {cursor}`
        após um `resume` aceito; `resync_required` quando o cursor não serve; `pong`; `error {code}`.

        **Replay e cursor.** O cursor é por tenant (não por instância) e opaco. Guarde o do último
        item recebido e mande `resume` ao reconectar: o servidor reenvia o que ainda está no buffer
        (que só guarda enquanto alguém está conectado ou se conectou há pouco). Cursor
        desconhecido, de outra época, à frente do último ou mais velho que o buffer (10 min ou 5.000
        eventos) devolve `resync_required`: reconcilie pela API REST. `instance.qr.updated` nunca é
        guardado nem reenviado (peça `GET /instances/{instanceId}/qr`).

        **Entrega de melhor esforço.** O tempo real pode **perder** eventos (falha do hub, evento
        grande demais, reinício) e pode **repeti-los**: deduplique por `Event.id`. Para não perder
        nada, use webhooks (o canal oficial de integração).

        **Códigos de fechamento.** `4001` reautenticação (a cada 24 h, ou quando a chave não pôde
        ser revalidada por mais de 5 min, contados a partir do prazo da revalidação; peça novo
        ticket); `4401`
        credencial revogada, vencida ou tenant fora de `active`; `1008` violação de política (mensagem
        inválida ou ritmo excedido); `1009` frame grande demais; `1013` cliente lento; `1001` e `1012`
        deploy (normal: reconecte com backoff e novo ticket).
      x-conectzap-sprint: 7
      x-required-scopes: [realtime:subscribe]
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateRealtimeTicketRequest' }
      responses:
        '201':
          description: Ticket emitido
          headers:
            Cache-Control:
              description: Sempre `no-store`.
              schema: { type: string, const: no-store }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RealtimeTicket' }
        default: { $ref: '#/components/responses/Error' }

webhooks:
  event:
    post:
      summary: Evento entregue ao endpoint do cliente.
      description: |
        Cabeçalhos:
        - `Content-Type: application/json` e `User-Agent: ConectZap-Webhooks/1`.
        - `ConectZap-Event-Id`: id único do evento (`evt_…`). **Deduplique por ele**: a entrega é
          *at-least-once* e o mesmo evento pode chegar mais de uma vez (por exemplo, se o seu `2xx` se perder).
        - `ConectZap-Timestamp`: epoch em segundos da tentativa. Rejeite se divergir > 300 s.
        - `ConectZap-Signature`: `v1=<hex(HMAC-SHA256(secret, "{timestamp}.{rawBody}"))>`, refeita a cada
          tentativa com o timestamp dela. Durante a rotação do segredo vêm duas assinaturas
          (`v1=<novo>,v1=<anterior>`); o segredo anterior vale por 24 h.

        Responda `2xx` em até 10 s. Qualquer outra resposta (inclusive redirecionamento `3xx`, que não é
        seguido) e timeouts geram nova tentativa: 10 tentativas no total, com atrasos de 30 s, 2 min,
        10 min, 30 min, 1 h, 2 h, 4 h, 6 h e 8 h entre elas (jitter de ±20 %; cerca de 22 h no total).
        Esgotadas as tentativas, o evento é **descartado** (status `dead` registrado sem payload) e o
        evento `webhook.failed` é emitido para os outros canais. Um webhook que falha sem nenhum sucesso
        há mais de 3 dias é desativado (`enabled: false`, `disabledReason: consecutive_failures`); ao
        desativar, as entregas pendentes desse webhook viram `dead` **sem** novas tentativas e **sem**
        `webhook.failed` (o sinal é o próprio webhook com `enabled: false` e `disabledReason`).
        `PATCH` com `enabled: true` o reativa. O ConectZap não guarda eventos: o sistema do cliente é o
        registro das conversas.
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Event' }
      responses:
        '200': { description: Recebido }

components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: 'czk_{env}_{keyId}_{secret}'
      description: Chave de API do tenant. Armazenada apenas como hash; exibida uma única vez.

  parameters:
    SignedTid:
      name: tid
      in: query
      required: true
      description: |
        Roteamento opaco da URL assinada (uuid do tenant, coberto pela assinatura). Sem API Key, é o que leva a
        requisição ao shard certo; trocado ou adulterado, a assinatura não confere (`403 invalid_signature`).
        Copie a URL inteira como recebida.
      schema: { type: string, format: uuid }
    SignedExp:
      name: exp
      in: query
      required: true
      description: Instante de expiração da URL assinada (epoch em segundos; no máximo 15 minutos após a criação).
      schema: { type: integer }
    SignedSig:
      name: sig
      in: query
      required: true
      description: Assinatura HMAC da URL (credencial única destas rotas).
      schema: { type: string }
    InstanceId:
      name: instanceId
      in: path
      required: true
      schema: { type: string, pattern: '^inst_[0-9A-Za-z]{20,32}$' }
    MessageId:
      name: messageId
      in: path
      required: true
      schema: { type: string, pattern: '^msg_[0-9A-Za-z]{20,32}$' }
    WebhookId:
      name: webhookId
      in: path
      required: true
      schema: { type: string, pattern: '^whk_[0-9A-Za-z]{20,32}$' }
    ChatId:
      name: chatId
      in: path
      required: true
      schema: { type: string, maxLength: 128 }
    Limit:
      name: limit
      in: query
      schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
    Cursor:
      name: cursor
      in: query
      schema: { type: string, maxLength: 512 }
    AcceptLanguage:
      name: Accept-Language
      in: header
      required: false
      description: |
        Idioma dos textos para pessoas (`title`, `detail` e mensagens de validação do `Problem`):
        `pt-BR` (padrão), `en` ou `es`, com q-values (ex.: `es-AR,es;q=0.9,en;q=0.5`).
        Idioma desconhecido ou ausente → `pt-BR`. Caminhos, campos JSON, `Problem.code` e enums
        **não mudam** com o idioma. A resposta traz `Content-Language` e `Vary: Accept-Language`.
      schema: { type: string, maxLength: 1024, default: pt-BR, examples: ['en', 'es', 'pt-BR'] }
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: Chave única do cliente (≤ 128 chars). Mesma chave + corpo diferente = `422 idempotency_key_reused`.
      schema: { type: string, maxLength: 128 }
    IdempotencyKeyRequired:
      name: Idempotency-Key
      in: header
      required: true
      description: |
        Chave única do cliente (≤ 128 chars), **obrigatória** nas operações de mensagem: sem ela → `400 validation_failed`.
        Repetir a mesma chave não envia de novo (devolve a resposta gravada por 24 h, ou absorve o reenvio
        quando a resposta se perdeu). Mesma chave + corpo diferente = `422 idempotency_key_reused`.
        **Não reutilize uma chave por 7 dias** nas operações de mensagem: depois das 24 h a resposta
        gravada some, mas o id da mensagem derivado da chave continua valendo por 7 dias, e a mesma
        chave com outro corpo é aceita (`202`) sem enviar nada novo.
      schema: { type: string, minLength: 1, maxLength: 128 }

  headers:
    RateLimit-Policy:
      description: 'Política de cota do plano, ex.: `600;w=60`.'
      schema: { type: string }
    RateLimit:
      description: 'Estado da cota, ex.: `limit=600, remaining=12, reset=31`.'
      schema: { type: string }
    Retry-After:
      description: Segundos até nova tentativa (429/503).
      schema: { type: integer }
    Content-Language:
      description: Idioma escolhido para os textos (`pt-BR`, `en` ou `es`), conforme `Accept-Language`.
      schema: { type: string, enum: [pt-BR, en, es] }
    Allow:
      description: 'Métodos HTTP aceitos pela rota (somente em `405`), ex.: `GET, HEAD`.'
      schema: { type: string }
    WWW-Authenticate:
      description: >-
        Somente em `401`: sempre `Bearer`. Chave ausente, malformada, inexistente, revogada, vencida ou com
        segredo errado recebem o mesmo `401 unauthenticated`, sem distinguir o motivo.
      schema: { type: string, enum: [Bearer] }

  responses:
    Error:
      description: Erro padronizado (RFC 9457).
      headers:
        RateLimit-Policy: { $ref: '#/components/headers/RateLimit-Policy' }
        RateLimit: { $ref: '#/components/headers/RateLimit' }
        Retry-After: { $ref: '#/components/headers/Retry-After' }
        Allow: { $ref: '#/components/headers/Allow' }
        WWW-Authenticate: { $ref: '#/components/headers/WWW-Authenticate' }
        Content-Language: { $ref: '#/components/headers/Content-Language' }
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }

  schemas:
    Health:
      type: object
      required: [status, version]
      properties:
        status: { type: string, enum: [ok] }
        version: { type: string, description: Versão implantada do gateway. }

    Problem:
      type: object
      required: [type, title, status, code, requestId]
      properties:
        type: { type: string, format: uri, examples: ['https://docs.conectzap.app/errors/instance_not_connected'] }
        title: { type: string }
        status: { type: integer }
        code:
          type: string
          description: |
            Código estável legível por máquina. Mapeamento de status:
            `validation_failed` 400 · `unauthenticated` 401 · `forbidden` 403 · `not_found` 404 ·
            `conflict` 409 · `plan_limit_reached` 409 · `instance_not_connected` 409 ·
            `instance_paused` 409 (instância em pausa automática; respeite `Retry-After`) ·
            `instance_busy` 429 (fila de envio da instância cheia, acima de 5.000; respeite `Retry-After`) ·
            `message_not_found` 404 (id de mensagem desconhecido ou expirado) ·
            `idempotency_key_reused` 422 · `rate_limited` 429 · `payload_too_large` 413 ·
            `unsupported_media_type` 415 ·
            `invalid_signature` 403 (assinatura da URL de mídia ausente, inválida ou de outro tenant) ·
            `upload_expired` 410 · `already_uploaded` 409 · `media_type_mismatch` 422 (tipo real ≠ `mimeType`) ·
            `media_not_found` 404 · `media_unavailable` (mídia de envio vencida ou de outro tenant; só em `message.failed`) ·
            `media_fetch_failed` (download de `url` falhou; só em `message.failed`) ·
            `voice_note_requires_ogg` 400 (`voiceNote` exige OGG/Opus) · `method_not_allowed` 405 (método HTTP não suportado pela rota; veja o cabeçalho `Allow`) · `provider_unavailable` 503 · `tenant_migrating` 503 (migração de shard em curso; respeite `Retry-After`) · `service_unavailable` 503 (Control Plane ou banco indisponível; respeite `Retry-After`) · `internal_error` 500.
          enum:
            - validation_failed
            - unauthenticated
            - forbidden
            - not_found
            - method_not_allowed
            - conflict
            - plan_limit_reached
            - instance_not_connected
            - instance_paused
            - instance_busy
            - message_not_found
            - idempotency_key_reused
            - rate_limited
            - payload_too_large
            - unsupported_media_type
            - invalid_signature
            - upload_expired
            - already_uploaded
            - media_type_mismatch
            - media_not_found
            - media_unavailable
            - media_fetch_failed
            - voice_note_requires_ogg
            - provider_unavailable
            - tenant_migrating
            - service_unavailable
            - internal_error
        detail: { type: string }
        requestId: { type: string }
        errors:
          type: array
          items:
            type: object
            properties:
              path: { type: string }
              message: { type: string }

    Page:
      type: object
      properties:
        nextCursor: { type: [string, 'null'] }
        hasMore: { type: boolean }

    PhoneNumber:
      type: string
      description: E.164 sem `+` (somente dígitos).
      pattern: '^[1-9][0-9]{7,14}$'
      examples: ['5511999998888']

    Account:
      type: object
      properties:
        tenantId: { type: string }
        name: { type: string }
        plan:
          type: object
          properties:
            code: { type: string }
            maxInstances: { type: integer }
            rateLimitPerMinute: { type: integer }
        usage:
          type: object
          properties:
            instances: { type: integer }
            messagesSentToday: { type: integer }

    InstanceStatus:
      type: string
      enum: [created, starting, pairing, connected, reconnecting, disconnected, logged_out, banned, failed, deleting]

    Instance:
      type: object
      required: [id, name, status, provider, createdAt]
      properties:
        id: { type: string }
        name: { type: string, maxLength: 80 }
        provider: { type: string, enum: [baileys, cloud_api], default: baileys }
        status: { $ref: '#/components/schemas/InstanceStatus' }
        phoneNumber: { type: [string, 'null'] }
        profileName: { type: [string, 'null'] }
        lastDisconnectReason:
          type: [string, 'null']
          description: >-
            Motivo da última desconexão (inclui `migration` e
            `temporary_restriction`).
        settings: { $ref: '#/components/schemas/InstanceSettings' }
        connectedAt: { type: [string, 'null'], format: date-time }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }

    InstanceSettings:
      type: object
      description: Configurações da instância como a API as devolve (sempre os 4 campos).
      required: [rejectCalls, markMessagesRead, ignoreGroups, storeMedia]
      properties:
        rejectCalls: { type: boolean, default: false }
        markMessagesRead: { type: boolean, default: false }
        ignoreGroups: { type: boolean, default: false }
        storeMedia: { type: boolean, default: true }

    InstanceSettingsInput:
      type: object
      description: >-
        Configurações no pedido de criação ou alteração: todos os campos são opcionais. Na criação, o
        que faltar fica com o padrão; na alteração, o que faltar não muda.
      additionalProperties: false
      properties:
        rejectCalls: { type: boolean, default: false }
        markMessagesRead: { type: boolean, default: false }
        ignoreGroups: { type: boolean, default: false }
        storeMedia: { type: boolean, default: true }

    CreateInstanceRequest:
      type: object
      required: [name]
      additionalProperties: false
      properties:
        name: { type: string, minLength: 1, maxLength: 80 }
        provider: { type: string, enum: [baileys], default: baileys }
        settings: { $ref: '#/components/schemas/InstanceSettingsInput' }

    UpdateInstanceRequest:
      type: object
      additionalProperties: false
      properties:
        name: { type: string, minLength: 1, maxLength: 80 }
        settings: { $ref: '#/components/schemas/InstanceSettingsInput' }

    ConnectRequest:
      type: object
      additionalProperties: false
      required: [method]
      properties:
        method: { type: string, enum: [qr_code, pairing_code] }
        phoneNumber:
          $ref: '#/components/schemas/PhoneNumber'
          description: Obrigatório quando `method = pairing_code`.

    ConnectResponse:
      type: object
      properties:
        status: { $ref: '#/components/schemas/InstanceStatus' }
        method: { type: string, enum: [qr_code, pairing_code] }
        pairingCode: { type: [string, 'null'], description: 'Código de 8 caracteres a digitar no aparelho.' }
        expiresAt: { type: [string, 'null'], format: date-time }

    QrCode:
      type: object
      properties:
        qr: { type: string, description: 'Conteúdo do QR (raw) ou PNG base64.' }
        format: { type: string, enum: [raw, png_base64] }
        expiresAt: { type: string, format: date-time }
        attempt: { type: integer }

    InstanceStatusDetail:
      type: object
      properties:
        status: { $ref: '#/components/schemas/InstanceStatus' }
        lastDisconnectReason:
          type: [string, 'null']
          description: >-
            Motivo da última desconexão. Valores adicionados no Sprint 5:
            `migration` (a sessão foi movida para outro pool; a reconexão é
            automática e sem QR) e `temporary_restriction` (o WhatsApp aplicou
            uma restrição temporária; a instância fica em pausa até
            `pausedUntil`).
        lastSeenAt: { type: [string, 'null'], format: date-time }
        pausedUntil:
          type: [string, 'null']
          format: date-time
          description: >-
            Enquanto no futuro, a instância está em pausa por restrição
            temporária (mínimo de 30 min, ESTIMADO) e não reconecta nem envia.
            `null` quando não há pausa.
        restrictions:
          type: object
          description: >-
            Contagem desde a criação da instância; sem dados do aparelho.
          required: [logout, temporaryRestriction, ban, technicalFailure, lastAt]
          properties:
            logout: { type: integer, minimum: 0, description: 'Desconexões por logout (401).' }
            temporaryRestriction: { type: integer, minimum: 0, description: 'Restrições temporárias (1º 403).' }
            ban: { type: integer, minimum: 0, description: 'Banimentos (403 que leva a `banned`).' }
            technicalFailure: { type: integer, minimum: 0, description: 'Falhas técnicas (500, 411 ou reconexões esgotadas).' }
            lastAt:
              type: [string, 'null']
              format: date-time
              description: Momento da última ocorrência de qualquer categoria.
        runtime:
          type: object
          description: Informação operacional sem dados sensíveis.
          properties:
            version: { type: string }
            uptimeSeconds: { type: integer }
            reconnectAttempts: { type: integer }

    InstanceMetrics:
      type: object
      required: [granularity, series]
      properties:
        granularity: { type: string, enum: [hour, day] }
        series:
          type: array
          items:
            type: object
            required: [bucket, sent, received, failed, connectedSeconds]
            properties:
              bucket: { type: string, format: date-time }
              sent: { type: integer }
              received: { type: integer }
              failed: { type: integer }
              connectedSeconds: { type: integer }

    MessageStatus:
      type: string
      enum: [queued, sending, sent, delivered, read, played, failed, received, deleted]

    MessageType:
      type: string
      enum: [text, image, video, audio, document, sticker, location, contact, poll, reaction, unsupported]

    SendMessageRequest:
      description: Corpo discriminado por `type`.
      oneOf:
        - $ref: '#/components/schemas/SendTextMessage'
        - $ref: '#/components/schemas/SendMediaMessage'
        - $ref: '#/components/schemas/SendLocationMessage'
        - $ref: '#/components/schemas/SendContactMessage'
        - $ref: '#/components/schemas/SendPollMessage'
        - $ref: '#/components/schemas/SendReactionMessage'
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/SendTextMessage'
          image: '#/components/schemas/SendMediaMessage'
          video: '#/components/schemas/SendMediaMessage'
          audio: '#/components/schemas/SendMediaMessage'
          document: '#/components/schemas/SendMediaMessage'
          location: '#/components/schemas/SendLocationMessage'
          contact: '#/components/schemas/SendContactMessage'
          poll: '#/components/schemas/SendPollMessage'
          reaction: '#/components/schemas/SendReactionMessage'

    SendMessageAccepted:
      type: object
      required: [id, status]
      properties:
        id: { type: string, description: 'msg_… (estável; também retornado nos webhooks).' }
        status: { type: string, const: queued }
        instanceId: { type: string }
        to: { type: string }
        queuedAt: { type: string, format: date-time }

    SendMessageCommon:
      type: object
      required: [to, type]
      properties:
        delaySeconds:
          type: integer
          minimum: 0
          maximum: 15
          description: Espera adicional antes deste envio, além do intervalo do plano.
        typingSeconds:
          type: integer
          minimum: 0
          maximum: 15
          description: Mostra "digitando…" (ou "gravando" para áudio) por N segundos antes de enviar.
        to:
          type: string
          description: |
            Número em E.164 **somente dígitos, sem `+`** (ex.: `5511999998888`) ou chatId de grupo (`...@g.us`).
            A plataforma resolve o JID real no WhatsApp (inclui números brasileiros com/sem 9º dígito) antes do primeiro envio.
          maxLength: 128
        replyTo:
          type: string
          pattern: '^msg_[0-9A-Za-z]{20,32}$'
          description: |
            messageId a citar. Precisa ser do mesmo chat de `to`; de outro chat →
            `400 validation_failed` (citar levaria o id e o autor de outra conversa).
        metadata:
          type: object
          maxProperties: 10
          additionalProperties: { type: string, maxLength: 256 }
          description: Devolvido em webhooks; não é enviado ao WhatsApp.

    SendTextMessage:
      allOf:
        - $ref: '#/components/schemas/SendMessageCommon'
        - type: object
          required: [type, text]
          properties:
            type: { type: string, const: text }
            text:
              type: object
              additionalProperties: false
              required: [body]
              properties:
                body: { type: string, minLength: 1, maxLength: 4096 }
                previewUrl: { type: boolean, default: false }
      unevaluatedProperties: false

    SendMediaMessage:
      allOf:
        - $ref: '#/components/schemas/SendMessageCommon'
        - type: object
          required: [type, media]
          properties:
            type: { type: string, enum: [image, video, audio, document] }
            media:
              type: object
              additionalProperties: false
              description: Exatamente um entre `mediaId` (upload prévio) e `url`.
              oneOf:
                - required: [mediaId]
                - required: [url]
              properties:
                mediaId: { type: string, pattern: '^med_[0-9A-Za-z]{20,32}$' }
                url:
                  type: string
                  format: uri
                  pattern: '^https://'
                  maxLength: 2048
                  description: |
                    Baixada pela plataforma com as mesmas proteções SSRF dos webhooks: HTTPS na porta 443,
                    IPs privados/loopback/link-local/metadados bloqueados após resolução DNS, sem seguir
                    redirects, timeout 30 s, tamanho ≤ limite do plano, tipo validado por *magic bytes*.
                caption: { type: string, maxLength: 1024 }
                fileName: { type: string, maxLength: 255 }
                voiceNote: { type: boolean, default: false, description: 'Áudio como PTT (exige OGG/Opus no MVP).' }
      unevaluatedProperties: false

    SendLocationMessage:
      x-conectzap-tier: optional
      allOf:
        - $ref: '#/components/schemas/SendMessageCommon'
        - type: object
          required: [type, location]
          properties:
            type: { type: string, const: location }
            location:
              type: object
              additionalProperties: false
              required: [latitude, longitude]
              properties:
                latitude: { type: number, minimum: -90, maximum: 90 }
                longitude: { type: number, minimum: -180, maximum: 180 }
                name: { type: string, maxLength: 100 }
      unevaluatedProperties: false

    SendContactMessage:
      description: Cartão de contato, enviado como vCard mínimo (nome e telefone).
      allOf:
        - $ref: '#/components/schemas/SendMessageCommon'
        - type: object
          required: [type, contact]
          properties:
            type: { type: string, const: contact }
            contact:
              type: object
              additionalProperties: false
              required: [name, phoneNumber]
              properties:
                name: { type: string, minLength: 1, maxLength: 100 }
                phoneNumber: { $ref: '#/components/schemas/PhoneNumber' }
      unevaluatedProperties: false

    SendPollMessage:
      description: Enquete com 2 a 12 opções distintas.
      allOf:
        - $ref: '#/components/schemas/SendMessageCommon'
        - type: object
          required: [type, poll]
          properties:
            type: { type: string, const: poll }
            poll:
              type: object
              additionalProperties: false
              required: [name, options, selectableCount]
              properties:
                name: { type: string, minLength: 1, maxLength: 255 }
                options:
                  type: array
                  minItems: 2
                  maxItems: 12
                  uniqueItems: true
                  items: { type: string, minLength: 1, maxLength: 100 }
                selectableCount:
                  type: integer
                  minimum: 1
                  maximum: 12
                  description: Quantas opções cada pessoa pode marcar. Deve ser menor ou igual ao número de `options`; caso contrário `400 validation_failed`.
      unevaluatedProperties: false

    EditMessageRequest:
      type: object
      additionalProperties: false
      required: [text]
      properties:
        text:
          type: object
          additionalProperties: false
          required: [body]
          properties:
            body: { type: string, minLength: 1, maxLength: 4096 }

    MessageActionAccepted:
      type: object
      required: [id, status]
      properties:
        id: { type: string, description: 'msg_… da mensagem afetada.' }
        status: { type: string, const: queued }

    SendReactionMessage:
      x-conectzap-tier: optional
      allOf:
        - $ref: '#/components/schemas/SendMessageCommon'
        - type: object
          required: [type, reaction]
          properties:
            type: { type: string, const: reaction }
            reaction:
              type: object
              additionalProperties: false
              required: [messageId, emoji]
              properties:
                messageId: { type: string, pattern: '^msg_[0-9A-Za-z]{20,32}$' }
                emoji: { type: string, maxLength: 16, description: 'Vazio remove a reação.' }
      unevaluatedProperties: false

    Message:
      type: object
      description: Mensagem normalizada, entregue **somente** em eventos (webhook/realtime); não é armazenada nem consultável depois.
      properties:
        id: { type: string }
        instanceId: { type: string }
        chatId: { type: string }
        direction: { type: string, enum: [inbound, outbound] }
        type: { $ref: '#/components/schemas/MessageType' }
        status: { $ref: '#/components/schemas/MessageStatus' }
        from: { type: string }
        to: { type: string }
        text:
          type: [string, 'null']
          description: |
            Texto ou legenda. Em mensagem recebida, pode vir **cortado** para o evento caber no limite de
            tamanho da entrega (o WhatsApp aceita textos maiores).
        media:
          description: |
            Arquivo da mensagem recebida (imagem, vídeo, áudio, documento, figurinha). Sai em duas etapas: `message.received`
            com `status` = `processing` e o `id` (`med_…`), e depois `message.updated` com o mesmo `id` e `ready` ou `failed`
            (acima do teto do plano, tipo fora da lista aceita, download interrompido ou incompleto, ou nenhum desfecho em
            1 h). Só um download confirmado como completo fica `ready`. O arquivo fica 24 h; a URL de download vem só de
            `getMedia`.
          oneOf: [{ $ref: '#/components/schemas/Media' }, { type: 'null' }]
        location:
          type: [object, 'null']
          description: Localização recebida (`type` = `location`); `null` nos outros tipos.
          required: [latitude, longitude, name]
          properties:
            latitude: { type: number }
            longitude: { type: number }
            name: { type: [string, 'null'] }
        contact:
          type: [object, 'null']
          description: Cartão de contato recebido (o primeiro, quando vierem vários); `null` nos outros tipos.
          required: [name, phoneNumber]
          properties:
            name: { type: string }
            phoneNumber:
              type: [string, 'null']
              description: E.164 só com dígitos, lido do vCard; `null` quando o vCard não traz um válido.
        poll:
          type: [object, 'null']
          description: Enquete recebida; `null` nos outros tipos.
          required: [name, options, selectableCount]
          properties:
            name: { type: string }
            options:
              type: array
              items: { type: string }
            selectableCount: { type: integer, minimum: 1 }
        reaction:
          type: [object, 'null']
          description: Reação recebida (`type` = `reaction`); `null` nos outros tipos.
          required: [messageId, emoji]
          properties:
            messageId:
              type: [string, 'null']
              description: '`msg_…` da mensagem reagida, quando ela ainda está no mapa de ids (7 dias); senão `null`.'
            emoji: { type: string, description: 'Vazio = reação removida.' }
        providerMessageId: { type: [string, 'null'] }
        error:
          type: [object, 'null']
          properties:
            code: { type: string }
            message: { type: string }
        metadata: { type: object, additionalProperties: { type: string } }
        timestamp: { type: string, format: date-time }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }

    Scope:
      type: string
      description: >-
        Escopo de uma chave de API. No tempo real, `realtime:subscribe` só abre o canal: cada tipo de
        evento exige também o escopo de leitura dele (`message.*` → `messages:read`;
        `instance.qr.updated` → `instances:connect`; demais `instance.*` → `instances:read`;
        `webhook.failed` → `webhooks:read`; ver `createRealtimeTicket`).
      enum: [account:read, api_keys:read, api_keys:write, instances:read, instances:write, instances:delete, instances:connect, messages:send, messages:read, contacts:read, groups:read, webhooks:read, webhooks:write, realtime:subscribe]

    ApiKey:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        prefix: { type: string, description: 'czk_live_<keyId> — identifica a chave sem revelar o segredo.' }
        scopes:
          type: array
          items: { $ref: '#/components/schemas/Scope' }
        instanceIds:
          type: [array, 'null']
          items: { type: string }
        lastUsedAt: { type: [string, 'null'], format: date-time }
        expiresAt: { type: [string, 'null'], format: date-time }
        createdAt: { type: string, format: date-time }

    Media:
      type: object
      properties:
        id: { type: string }
        status:
          type: string
          enum: [pending_upload, processing, ready, failed, deleted]
          description: '`processing` = mídia recebida ainda sendo gravada; em mídia recebida, `message.received` sai com `processing` e `message.updated` é emitido ao ficar `ready` ou `failed` (acima do teto, download incompleto ou sem desfecho em 1 h → `failed`).'
        mimeType: { type: string }
        sizeBytes:
          type: integer
          description: Tamanho em bytes. Ausente quando ainda não é conhecido (mídia recebida sem tamanho declarado pelo WhatsApp, antes de ficar `ready`).
        sha256: { type: string }
        fileName:
          type: [string, 'null']
          description: Nome do documento recebido, só em trânsito no `message.received`; `null` no `getMedia` e no `message.updated`. Vai no evento, inclusive nas filas de entrega e retentativa (retenção curta); nunca no banco nem em log.
        downloadUrl:
          type: [string, 'null']
          format: uri
          description: URL temporária (≤ 15 min). Só `getMedia` a devolve; nos eventos (`message.received`/`message.updated`) é sempre `null`.
        expiresAt: { type: [string, 'null'], format: date-time }

    Group:
      type: object
      properties:
        id: { type: string }
        subject: { type: string }
        description: { type: [string, 'null'] }
        ownerChatId: { type: [string, 'null'] }
        participants:
          type: array
          items:
            type: object
            properties:
              chatId: { type: string }
              role: { type: string, enum: [member, admin, superadmin] }
        createdAt: { type: [string, 'null'], format: date-time }

    EventType:
      type: string
      enum:
        - instance.connected
        - instance.disconnected
        - instance.qr.updated
        - instance.logged_out
        - instance.banned
        - instance.failed
        - message.received
        - message.sent
        - message.updated
        - message.failed
        - webhook.failed
        - webhook.test

    CreateRealtimeTicketRequest:
      type: object
      additionalProperties: false
      properties:
        instanceIds:
          type: array
          maxItems: 50
          uniqueItems: true
          items: { type: string }
          description: Vazio ou ausente = todas as instâncias do tenant permitidas à chave.
        events:
          type: array
          maxItems: 11
          uniqueItems: true
          description: Vazio ou ausente = todos os tipos. `webhook.test` não existe em tempo real.
          items:
            type: string
            enum:
              - instance.connected
              - instance.disconnected
              - instance.qr.updated
              - instance.logged_out
              - instance.banned
              - instance.failed
              - message.received
              - message.sent
              - message.updated
              - message.failed
              - webhook.failed

    RealtimeTicket:
      type: object
      required: [ticket, url, expiresAt]
      properties:
        ticket: { type: string, description: 'Segredo de uso único (60 s). Não registre em log.' }
        url: { type: string, format: uri, description: 'URL `wss://` já com o ticket.' }
        expiresAt: { type: string, format: date-time }

    RealtimeClientMessage:
      description: Mensagem do cliente no WebSocket, discriminada por `type`.
      oneOf:
        - $ref: '#/components/schemas/RealtimePing'
        - $ref: '#/components/schemas/RealtimeResume'
        - $ref: '#/components/schemas/RealtimeSubscribe'
      discriminator:
        propertyName: type
        mapping:
          ping: '#/components/schemas/RealtimePing'
          resume: '#/components/schemas/RealtimeResume'
          subscribe: '#/components/schemas/RealtimeSubscribe'

    RealtimePing:
      type: object
      required: [type]
      properties:
        type: { type: string, const: ping }

    RealtimeResume:
      type: object
      required: [type, cursor]
      properties:
        type: { type: string, const: resume }
        cursor: { type: string, description: 'Cursor do último item recebido (opaco).' }

    RealtimeSubscribe:
      type: object
      required: [type]
      properties:
        type: { type: string, const: subscribe }
        instanceIds: { type: array, maxItems: 50, uniqueItems: true, items: { type: string } }
        events:
          type: array
          maxItems: 11
          uniqueItems: true
          items: { $ref: '#/components/schemas/EventType' }

    RealtimeServerMessage:
      description: Mensagem do servidor no WebSocket, discriminada por `type`.
      oneOf:
        - $ref: '#/components/schemas/RealtimeReady'
        - $ref: '#/components/schemas/RealtimeEvents'
        - $ref: '#/components/schemas/RealtimeResumed'
        - $ref: '#/components/schemas/RealtimeResyncRequired'
        - $ref: '#/components/schemas/RealtimePong'
        - $ref: '#/components/schemas/RealtimeError'
      discriminator:
        propertyName: type
        mapping:
          ready: '#/components/schemas/RealtimeReady'
          events: '#/components/schemas/RealtimeEvents'
          resumed: '#/components/schemas/RealtimeResumed'
          resync_required: '#/components/schemas/RealtimeResyncRequired'
          pong: '#/components/schemas/RealtimePong'
          error: '#/components/schemas/RealtimeError'

    RealtimeReady:
      type: object
      required: [type, cursor, reauthAt]
      properties:
        type: { type: string, const: ready }
        cursor: { type: string, description: 'Cursor atual do hub; guarde-o para o `resume`.' }
        reauthAt: { type: string, format: date-time, description: 'Fechamento com 4001 a partir deste instante.' }

    RealtimeEvents:
      type: object
      required: [type, items]
      properties:
        type: { type: string, const: events }
        items:
          type: array
          maxItems: 100
          items:
            type: object
            required: [cursor, event]
            properties:
              cursor: { type: string }
              event: { $ref: '#/components/schemas/Event' }

    RealtimeResumed:
      type: object
      required: [type, cursor]
      properties:
        type: { type: string, const: resumed }
        cursor: { type: string }

    RealtimeResyncRequired:
      type: object
      required: [type]
      description: O cursor não serve; reconcilie pela API REST.
      properties:
        type: { type: string, const: resync_required }

    RealtimePong:
      type: object
      required: [type]
      properties:
        type: { type: string, const: pong }

    RealtimeError:
      type: object
      required: [type, code]
      properties:
        type: { type: string, const: error }
        code:
          type: string
          description: >-
            Código do erro. O conjunto é aberto: novos códigos podem surgir, então trate os
            desconhecidos como erro genérico. Conhecidos: `invalid_message` (mensagem inválida),
            `rate_limited` (ritmo excedido) e `forbidden` (filtro fora do escopo do ticket).

    InstanceLogEntry:
      type: object
      required: [id, type, instanceId, from, to, reason, occurredAt]
      description: Transição de status da instância (auditoria operacional; 30 dias).
      properties:
        id: { type: string, description: 'iev_…' }
        type: { type: string, const: status }
        instanceId: { type: string }
        from: { $ref: '#/components/schemas/InstanceStatus' }
        to: { $ref: '#/components/schemas/InstanceStatus' }
        reason: { type: [string, 'null'], description: 'Motivo normalizado.' }
        occurredAt: { type: string, format: date-time }

    Event:
      type: object
      required: [id, type, tenantId, occurredAt, data]
      properties:
        id: { type: string, description: 'evt_… — chave de deduplicação.' }
        type: { $ref: '#/components/schemas/EventType' }
        tenantId: { type: string }
        instanceId: { type: [string, 'null'] }
        sequence:
          type: integer
          description: |
            Ordem **indicativa** por instância: ajuda a reordenar e a notar lacunas, mas pode repetir
            ou pular depois de falhas (webhooks entregam pelo menos uma vez; o tempo real é de melhor
            esforço). Deduplique sempre pelo `id` (`evt_…`).
        occurredAt: { type: string, format: date-time }
        data:
          description: |
            Payload normalizado. O esquema depende de `type` (amarrado abaixo por `allOf` + `if`/`then`):
            `instance.*` usa `InstanceEventData`, `message.*` usa `Message`, `webhook.failed` usa
            `WebhookFailedData` e `webhook.test` usa `WebhookTestData`.
          anyOf:
            - $ref: '#/components/schemas/InstanceEventData'
            - $ref: '#/components/schemas/Message'
            - $ref: '#/components/schemas/WebhookFailedData'
            - $ref: '#/components/schemas/WebhookTestData'
      allOf:
        - if:
            required: [type]
            properties: { type: { enum: [instance.connected, instance.disconnected, instance.qr.updated, instance.logged_out, instance.banned, instance.failed] } }
          then:
            properties: { data: { $ref: '#/components/schemas/InstanceEventData' } }
        - if:
            required: [type]
            properties: { type: { enum: [message.received, message.sent, message.updated, message.failed] } }
          then:
            properties: { data: { $ref: '#/components/schemas/Message' } }
        - if:
            required: [type]
            properties: { type: { const: webhook.failed } }
          then:
            properties: { data: { $ref: '#/components/schemas/WebhookFailedData' } }
        - if:
            required: [type]
            properties: { type: { const: webhook.test } }
          then:
            properties: { data: { $ref: '#/components/schemas/WebhookTestData' } }

    InstanceEventData:
      type: object
      description: Para `instance.*`.
      required: [instance, reason, qr, revision]
      properties:
        instance: { $ref: '#/components/schemas/Instance' }
        reason: { type: [string, 'null'], description: 'Motivo normalizado (ex.: connection_replaced, logged_out, forbidden).' }
        qr: { oneOf: [{ $ref: '#/components/schemas/QrCode' }, { type: 'null' }], description: 'Somente em instance.qr.updated.' }
        revision:
          type: integer
          description: >-
            Revisão da instância: cresce a cada transição de status. Use para descartar eventos
            fora de ordem (um evento com `revision` menor que a do último aplicado é antigo). Em
            caso de dúvida, reconcilie com `GET /instances/{instanceId}`.

    WebhookFailedData:
      type: object
      description: >-
        Para `webhook.failed` (nunca entregue ao próprio endpoint que falhou). O `instanceId` do evento é o
        escopo do webhook que falhou: de um webhook de uma instância, a instância do evento original (vai
        para os webhooks dessa instância e para os do tenant inteiro); de um webhook do tenant inteiro,
        `null` (vai só para os outros webhooks do tenant inteiro).
      required: [webhookId, deliveryId, eventId, attempts, lastResponseStatus, lastError]
      properties:
        webhookId: { type: string }
        deliveryId: { type: string }
        eventId: { type: string }
        attempts: { type: integer }
        lastResponseStatus: { type: [integer, 'null'] }
        lastError:
          enum: [timeout, connection_error, http_status, redirect, url_blocked, dns_blocked, endpoint_busy, secret_unavailable, null]
          description: Código do último erro (sem corpo de resposta).

    WebhookTestData:
      type: object
      description: Para `webhook.test`.
      required: [webhookId, test]
      properties:
        webhookId: { type: string }
        test: { const: true }

    Webhook:
      type: object
      required: [id, url, instanceId, events, enabled, disabledReason, createdAt, updatedAt]
      properties:
        id: { type: string }
        url: { type: string, format: uri }
        instanceId: { type: [string, 'null'], description: 'null = todas as instâncias do tenant.' }
        events:
          type: array
          items: { $ref: '#/components/schemas/EventType' }
        enabled: { type: boolean }
        disabledReason:
          enum: [consecutive_failures, null]
          description: >-
            Preenchido quando o ConectZap desativa o webhook (falhas sem sucesso há mais de 3 dias); `null`
            caso contrário. Ao desativar, as entregas pendentes viram `dead` sem novas tentativas e sem
            `webhook.failed`.
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }

    WebhookTestResult:
      type: object
      description: Resultado do teste síncrono de um webhook (`testWebhook`).
      required: [ok, responseStatus, durationMs, error]
      properties:
        ok: { type: boolean, description: '`true` quando o endpoint respondeu `2xx`.' }
        responseStatus: { type: [integer, 'null'], description: 'Status HTTP da resposta; `null` se não houve resposta.' }
        durationMs: { type: integer }
        error:
          enum: [timeout, connection_error, http_status, redirect, url_blocked, dns_blocked, secret_unavailable, null]
          description: >-
            Motivo da falha; `null` quando `ok` é `true`. `dns_blocked` também cobre o DNS que não pôde ser
            conferido na hora (o teste não envia sem a conferência).

    CreateWebhookRequest:
      type: object
      required: [url, events]
      additionalProperties: false
      properties:
        url: { type: string, format: uri, pattern: '^https://', maxLength: 2048 }
        instanceId: { type: [string, 'null'], pattern: '^inst_[0-9A-Za-z]{20,32}$' }
        events:
          type: array
          minItems: 1
          maxItems: 12
          uniqueItems: true
          items: { $ref: '#/components/schemas/EventType' }

    UpdateWebhookRequest:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        url: { type: string, format: uri, pattern: '^https://', maxLength: 2048 }
        events:
          type: array
          minItems: 1
          maxItems: 12
          uniqueItems: true
          items: { $ref: '#/components/schemas/EventType' }
        enabled: { type: boolean }

    WebhookDelivery:
      type: object
      description: Registro de falha de entrega (sem payload).
      properties:
        id: { type: string }
        webhookId: { type: string }
        eventId: { type: string }
        eventType: { $ref: '#/components/schemas/EventType' }
        status: { type: string, enum: [retrying, dead] }
        attempts: { type: integer }
        lastResponseStatus: { type: [integer, 'null'] }
        lastError:
          enum: [timeout, connection_error, http_status, redirect, url_blocked, dns_blocked, endpoint_busy, secret_unavailable, null]
          description: 'Código do último erro (nunca o corpo da resposta do cliente).'
        lastDurationMs: { type: [integer, 'null'] }
        nextAttemptAt: { type: [string, 'null'], format: date-time }
        createdAt: { type: string, format: date-time }
