openapi: 3.1.0
info:
  title: YNIX AI API
  version: 0.4.7
  summary: Gateway brasileiro multi-provedor de IA com créditos, pagamentos e administração centralizada.
  description: Documentação completa da plataforma para autenticação, consumo de IA, créditos, pagamentos, consultas brasileiras,
    webhooks e administração.
  contact:
    name: YNIX AI API
servers:
- url: http://127.0.0.1:8000/api/v1
  description: Ambiente local
- url: https://api.seudominio.com.br/api/v1
  description: Produção — substitua pelo domínio real
security:
- bearerAuth: []
tags:
- name: Sistema
  description: Verificações de disponibilidade, recursos habilitados e informações gerais da aplicação.
- name: Autenticação
  description: Criação de conta, login, recuperação de senha, confirmação de e-mail e encerramento de sessões.
- name: Conta
  description: Dados do usuário, tokens de acesso, preferências e segurança da conta.
- name: IA
  description: Modelos disponíveis, conversas, streaming e recursos de inteligência artificial.
- name: Créditos
  description: Saldo, histórico, reservas e consumo da carteira da plataforma.
- name: Pagamentos
  description: Pacotes, recargas, PIX, cartão e acompanhamento das cobranças.
- name: BrasilAPI
  description: Consultas auxiliares de CEP, CNPJ e outros dados brasileiros.
- name: Webhooks
  description: Recebimento e processamento de eventos enviados pelos serviços integrados.
- name: Administração
  description: Gestão de usuários, provedores, credenciais, modelos, preços e configurações da plataforma.
- name: Consumo
  description: Estimativas prévias, gastos, uso por período, projeto, modelo e token.
- name: Projetos
  description: Organização de aplicações, ambientes, tokens, orçamentos e consumo.
paths:
  /health:
    get:
      tags:
      - Sistema
      summary: Verifica aplicação e banco
      operationId: systemHealth
      security: []
      responses:
        '200':
          description: Status atual
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
      description: Verifica aplicação e banco. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /capabilities:
    get:
      tags:
      - Sistema
      summary: Lista capacidades ativas e preparadas
      operationId: systemCapabilities
      security: []
      responses:
        '200':
          description: Capacidades
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
      description: Lista capacidades ativas e preparadas. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /auth/register:
    post:
      tags:
      - Autenticação
      summary: Cria uma conta e emite o primeiro token
      operationId: authRegister
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
            example:
              name: Carlos André
              email: carlos@example.com
              password: Senha@12345
              password_confirmation: Senha@12345
              document: '52998224725'
              phone: '11999999999'
              timezone: America/Sao_Paulo
              device_name: Meu computador
      responses:
        '201':
          description: Conta criada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
      description: Cria uma conta e emite o primeiro token. Consulte os parâmetros, exemplos e respostas disponíveis nesta
        seção.
  /auth/login:
    post:
      tags:
      - Autenticação
      summary: Autentica e emite um token
      operationId: authLogin
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            example:
              email: admin@ynix.com.br
              password: '123456'
              device_name: Painel local
      responses:
        '200':
          description: Login realizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
      description: Autentica e emite um token. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /auth/logout:
    post:
      tags:
      - Autenticação
      summary: Revoga o token atual
      operationId: authLogout
      responses:
        '200':
          description: Sessão encerrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
      description: Revoga o token atual. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /auth/logout-all:
    post:
      tags:
      - Autenticação
      summary: Revoga todos os tokens da conta
      operationId: authLogoutAll
      description: Requer a ability `tokens:manage`.
      responses:
        '200':
          description: Tokens revogados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /auth/forgot-password:
    post:
      tags:
      - Autenticação
      summary: Solicita recuperação de senha
      operationId: authForgotPassword
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForgotPasswordRequest'
            example:
              email: carlos@example.com
      responses:
        '200':
          description: Solicitação aceita
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
      description: Solicita recuperação de senha. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /auth/reset-password:
    post:
      tags:
      - Autenticação
      summary: Redefine a senha
      operationId: authResetPassword
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPasswordRequest'
            example:
              token: TOKEN_RECEBIDO
              email: carlos@example.com
              password: NovaSenha@12345
              password_confirmation: NovaSenha@12345
      responses:
        '200':
          description: Senha redefinida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
      description: Redefine a senha. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /auth/verify-email/{id}/{hash}:
    get:
      tags:
      - Autenticação
      summary: Confirma o e-mail pelo link assinado
      operationId: authVerifyEmail
      security: []
      parameters:
      - $ref: '#/components/parameters/UserId'
      - $ref: '#/components/parameters/VerificationHash'
      - in: query
        name: expires
        schema:
          type: integer
      - in: query
        name: signature
        schema:
          type: string
      responses:
        '200':
          description: E-mail confirmado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      description: Confirma o e-mail pelo link assinado. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /auth/verify-email/resend:
    post:
      tags:
      - Autenticação
      summary: Reenvia o link de confirmação
      operationId: authResendVerification
      description: Requer `account:security`.
      responses:
        '200':
          description: Solicitação aceita
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /auth/password:
    put:
      tags:
      - Autenticação
      summary: Altera a senha e revoga outras sessões
      operationId: authUpdatePassword
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePasswordRequest'
      responses:
        '200':
          description: Senha atualizada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      description: Altera a senha e revoga outras sessões. Consulte os parâmetros, exemplos e respostas disponíveis nesta
        seção.
  /auth/confirm-password:
    post:
      tags:
      - Autenticação
      summary: Confirma a senha por três horas
      operationId: authConfirmPassword
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - password
              properties:
                password:
                  type: string
                  format: password
      responses:
        '200':
          description: Senha confirmada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      description: Confirma a senha por três horas. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /me:
    get:
      tags:
      - Conta
      summary: Retorna o perfil autenticado
      operationId: profileShow
      responses:
        '200':
          description: Perfil
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      description: Retorna o perfil autenticado. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    put:
      tags:
      - Conta
      summary: Atualiza o perfil
      operationId: profileUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProfileRequest'
      responses:
        '200':
          description: Perfil atualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
      description: Atualiza o perfil. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /api-tokens:
    get:
      tags:
      - Conta
      summary: Lista tokens da conta
      operationId: apiTokenIndex
      responses:
        '200':
          description: Tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      description: Lista tokens da conta. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    post:
      tags:
      - Conta
      summary: Cria um token de integração
      operationId: apiTokenStore
      description: O token em texto puro é retornado somente nesta resposta.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiTokenCreateRequest'
            example:
              name: Produção
              abilities:
              - chat:create
              - models:read
              - credits:read
              expires_at: null
      responses:
        '201':
          description: Token criado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api-tokens/{apiToken}:
    delete:
      tags:
      - Conta
      summary: Revoga um token da própria conta
      operationId: apiTokenDestroy
      parameters:
      - $ref: '#/components/parameters/ApiTokenId'
      responses:
        '200':
          description: Token revogado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      description: Revoga um token da própria conta. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /models:
    get:
      tags:
      - IA
      summary: Lista modelos ativos com credencial utilizável
      operationId: modelIndex
      responses:
        '200':
          description: Modelos disponíveis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelListEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      description: Lista modelos ativos com credencial utilizável. Consulte os parâmetros, exemplos e respostas disponíveis
        nesta seção.
  /chat/completions:
    post:
      tags:
      - IA
      summary: Executa chat padronizado
      operationId: chatCompletion
      description: Formato compatível com OpenAI. Suporta JSON ou streaming SSE conforme `stream`.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            example:
              model: auto
              messages:
              - role: user
                content: Explique filas no Laravel.
              stream: false
              reasoning_effort: medium
      responses:
        '200':
          description: Chat completion JSON ou stream SSE
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            text/event-stream:
              schema:
                type: string
              example: 'data: {"choices":[{"delta":{"content":"Olá"}}]}


                data: [DONE]


                '
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '503':
          $ref: '#/components/responses/Unavailable'
  /cost-estimates:
    post:
      tags:
      - Consumo
      summary: Calcula uma faixa de créditos antes da execução
      operationId: costEstimate
      description: Estima entrada, saída, reserva máxima e saldo provável sem executar o modelo. O valor final pode variar
        conforme a resposta e o uso de ferramentas.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            example:
              model: auto
              messages:
              - role: user
                content: Explique filas no Laravel.
              max_tokens: 1200
              max_credits: 150
              project_id: 1
      responses:
        '200':
          description: Faixa estimada de consumo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostEstimateEnvelope'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '401': &id001
          $ref: '#/components/responses/Unauthorized'
        '403': &id002
          $ref: '#/components/responses/Forbidden'
        '422': &id003
          $ref: '#/components/responses/ValidationError'
  /usage:
    get:
      tags:
      - Consumo
      summary: Consulta gastos e consumo da conta
      operationId: usageSummary
      description: Retorna totais, média, variação entre estimado e realizado e agrupamentos por modelo, projeto, token e
        ambiente.
      parameters:
      - in: query
        name: period
        schema:
          type: string
          enum:
          - today
          - week
          - month
          - year
          default: month
      - in: query
        name: project_id
        schema:
          type: integer
      - in: query
        name: ai_model_id
        schema:
          type: integer
      - in: query
        name: api_token_id
        schema:
          type: string
          format: uuid
      - in: query
        name: environment
        schema:
          type: string
          enum:
          - test
          - production
      - in: query
        name: status
        schema:
          type: string
      responses:
        '200':
          description: Resumo de consumo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401': *id001
        '403': *id002
  /projects:
    get:
      tags:
      - Projetos
      summary: Lista projetos da conta
      operationId: projectIndex
      parameters:
      - $ref: '#/components/parameters/Page'
      - in: query
        name: environment
        schema:
          type: string
          enum:
          - test
          - production
      - in: query
        name: status
        schema:
          type: string
          enum:
          - active
          - paused
          - archived
      responses:
        '200':
          description: Projetos paginados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectListEnvelope'
        '401': *id001
        '403': *id002
        '422': *id003
    post:
      tags:
      - Projetos
      summary: Cria um projeto
      operationId: projectStore
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectRequest'
      responses:
        '201':
          description: Projeto criado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectEnvelope'
        '401': *id001
        '403': *id002
        '422': *id003
  /projects/{project}:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    get:
      tags:
      - Projetos
      summary: Exibe um projeto
      operationId: projectShow
      responses:
        '200':
          description: Projeto
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectEnvelope'
        '401': *id001
        '403': *id002
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Projetos
      summary: Atualiza um projeto
      operationId: projectUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectRequest'
      responses:
        '200':
          description: Projeto atualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectEnvelope'
        '401': *id001
        '403': *id002
        '422': *id003
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Projetos
      summary: Remove ou arquiva um projeto
      operationId: projectDestroy
      description: Projetos sem histórico podem ser removidos. Projetos já utilizados são arquivados para preservar a auditoria.
      responses:
        '200':
          description: Projeto removido ou arquivado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401': *id001
        '403': *id002
        '404':
          $ref: '#/components/responses/NotFound'
  /credits:
    get:
      tags:
      - Créditos
      summary: Consulta a carteira
      operationId: creditShow
      responses:
        '200':
          description: Carteira
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      description: Consulta a carteira. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /credits/transactions:
    get:
      tags:
      - Créditos
      summary: Lista o livro-caixa
      operationId: creditTransactions
      parameters:
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: Transações
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      description: Lista o livro-caixa. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /credit-packages:
    get:
      tags:
      - Pagamentos
      summary: Lista pacotes de recarga ativos
      operationId: creditPackagePublicIndex
      responses:
        '200':
          description: Pacotes ativos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditPackageListEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      description: Lista pacotes de recarga ativos. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /recharges:
    get:
      tags:
      - Pagamentos
      summary: Lista recargas da conta
      operationId: rechargeIndex
      parameters:
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: Recargas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      description: Lista recargas da conta. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    post:
      tags:
      - Pagamentos
      summary: Cria recarga Pix ou cartão via Asaas
      operationId: rechargeStore
      description: Use uma chave de idempotência única por tentativa lógica. Para cartão, informe os dados completos ou um
        `saved_payment_method_id`.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RechargeRequest'
            example:
              credit_package_id: 1
              billing_type: PIX
      responses:
        '201':
          description: Cobrança criada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '503':
          $ref: '#/components/responses/Unavailable'
  /recharges/{payment}:
    get:
      tags:
      - Pagamentos
      summary: Consulta uma recarga
      operationId: rechargeShow
      parameters:
      - $ref: '#/components/parameters/PaymentId'
      responses:
        '200':
          description: Recarga
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      description: Consulta uma recarga. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    delete:
      tags:
      - Pagamentos
      summary: Cancela uma cobrança elegível
      operationId: rechargeCancel
      parameters:
      - $ref: '#/components/parameters/PaymentId'
      responses:
        '200':
          description: Cobrança cancelada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '503':
          $ref: '#/components/responses/Unavailable'
      description: Cancela uma cobrança elegível. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /recharges/{payment}/refresh:
    post:
      tags:
      - Pagamentos
      summary: Sincroniza uma cobrança com o Asaas
      operationId: rechargeRefresh
      parameters:
      - $ref: '#/components/parameters/PaymentId'
      responses:
        '200':
          description: Cobrança sincronizada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '503':
          $ref: '#/components/responses/Unavailable'
      description: Sincroniza uma cobrança com o Asaas. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /payment-methods:
    get:
      tags:
      - Pagamentos
      summary: Lista cartões tokenizados
      operationId: paymentMethodIndex
      responses:
        '200':
          description: Formas de pagamento
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethodListEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      description: Lista cartões tokenizados. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    post:
      tags:
      - Pagamentos
      summary: Tokeniza um cartão no Asaas
      operationId: paymentMethodStore
      description: O número e o CCV são encaminhados ao Asaas durante a requisição e não são persistidos pela aplicação.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenizeCardRequest'
            example:
              credit_card:
                holderName: Cliente Sandbox
                number: '{{card_number}}'
                expiryMonth: 12
                expiryYear: 2030
                ccv: '123'
              holder_info:
                name: Cliente Sandbox
                email: cliente@example.com
                cpf_cnpj: '52998224725'
                postal_code: '01001000'
                address_number: '100'
                address_complement: Sala 1
                phone: '11999999999'
      responses:
        '201':
          description: Cartão tokenizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethodEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '503':
          $ref: '#/components/responses/Unavailable'
  /payment-methods/{paymentMethod}/default:
    patch:
      tags:
      - Pagamentos
      summary: Define o cartão principal
      operationId: paymentMethodDefault
      parameters:
      - $ref: '#/components/parameters/PaymentMethodId'
      responses:
        '200':
          description: Forma principal atualizada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethodEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      description: Define o cartão principal. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /payment-methods/{paymentMethod}:
    delete:
      tags:
      - Pagamentos
      summary: Remove o cartão salvo
      operationId: paymentMethodDestroy
      parameters:
      - $ref: '#/components/parameters/PaymentMethodId'
      responses:
        '200':
          description: Forma removida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      description: Remove o cartão salvo. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /brazil/postal-codes/{postalCode}:
    get:
      tags:
      - BrasilAPI
      summary: Consulta CEP
      operationId: brasilCep
      parameters:
      - $ref: '#/components/parameters/Cep'
      responses:
        '200':
          description: Endereço
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '503':
          $ref: '#/components/responses/Unavailable'
      description: Consulta CEP. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /brazil/companies/{cnpj}:
    get:
      tags:
      - BrasilAPI
      summary: Consulta CNPJ
      operationId: brasilCnpj
      parameters:
      - $ref: '#/components/parameters/Cnpj'
      responses:
        '200':
          description: Empresa
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '503':
          $ref: '#/components/responses/Unavailable'
      description: Consulta CNPJ. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /webhooks/asaas:
    post:
      tags:
      - Webhooks
      summary: Recebe eventos do Asaas
      operationId: asaasWebhookReceive
      description: Valida o header `asaas-access-token`, persiste o evento com idempotência e envia o processamento para a
        fila.
      security: []
      parameters:
      - $ref: '#/components/parameters/AsaasWebhookToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AsaasWebhookPayload'
      responses:
        '202':
          description: Evento aceito
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
  /admin/audit-logs:
    get:
      tags:
      - Administração
      summary: Lista auditoria administrativa
      operationId: adminAuditIndex
      parameters:
      - $ref: '#/components/parameters/Page'
      - in: query
        name: action
        schema:
          type: string
      - in: query
        name: user_id
        schema:
          type: integer
      - in: query
        name: per_page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      responses:
        '200':
          description: Logs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      description: Lista auditoria administrativa. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /admin/integrations/asaas:
    get:
      tags:
      - Administração
      summary: Exibe status e configuração não sensível do Asaas
      operationId: adminAsaasShow
      responses:
        '200':
          description: Status Asaas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '503':
          $ref: '#/components/responses/Unavailable'
      description: Exibe status e configuração não sensível do Asaas. Consulte os parâmetros, exemplos e respostas disponíveis
        nesta seção.
  /admin/integrations/asaas/test:
    post:
      tags:
      - Administração
      summary: Testa a conexão Asaas
      operationId: adminAsaasTest
      description: Requer confirmação recente da senha. A operação é auditada.
      responses:
        '200':
          description: Integração validada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '503':
          $ref: '#/components/responses/Unavailable'
  /admin/integrations/asaas/webhook/sync:
    post:
      tags:
      - Administração
      summary: Cria ou atualiza o webhook Asaas
      operationId: adminAsaasWebhookSync
      description: Requer confirmação recente da senha. A operação é auditada.
      responses:
        '200':
          description: Webhook sincronizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '503':
          $ref: '#/components/responses/Unavailable'
  /admin/providers:
    get:
      tags:
      - Administração
      summary: Lista provedores
      operationId: adminProviderIndex
      parameters:
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: Provedores
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      description: Lista provedores. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    post:
      tags:
      - Administração
      summary: Cria um provedor
      operationId: adminProviderStore
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProviderRequest'
      responses:
        '201':
          description: Provedor criado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
      description: Cria um provedor. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /admin/providers/{provider}:
    get:
      tags:
      - Administração
      summary: Consulta um provedor
      operationId: adminProviderShow
      parameters:
      - $ref: '#/components/parameters/ProviderId'
      responses:
        '200':
          description: Provedor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      description: Consulta um provedor. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    put:
      tags:
      - Administração
      summary: Atualiza um provedor
      operationId: adminProviderUpdate
      parameters:
      - $ref: '#/components/parameters/ProviderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProviderRequest'
      responses:
        '200':
          description: Provedor atualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
      description: Atualiza um provedor. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    patch:
      tags:
      - Administração
      summary: Atualiza parcialmente um provedor
      operationId: adminProviderPatch
      parameters:
      - $ref: '#/components/parameters/ProviderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProviderRequest'
      responses:
        '200':
          description: Provedor atualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
      description: Atualiza parcialmente um provedor. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    delete:
      tags:
      - Administração
      summary: Remove um provedor
      operationId: adminProviderDestroy
      parameters:
      - $ref: '#/components/parameters/ProviderId'
      responses:
        '200':
          description: Provedor removido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
      description: Remove um provedor. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /admin/providers/{provider}/credentials:
    get:
      tags:
      - Administração
      summary: Lista credenciais mascaradas
      operationId: adminCredentialIndex
      parameters:
      - $ref: '#/components/parameters/ProviderId'
      responses:
        '200':
          description: Credenciais
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialListEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      description: Lista credenciais mascaradas. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    post:
      tags:
      - Administração
      summary: Cadastra uma credencial criptografada
      operationId: adminCredentialStore
      parameters:
      - $ref: '#/components/parameters/ProviderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProviderCredentialRequest'
            example:
              name: Chave principal
              environment: production
              secret:
                api_key: CHAVE_DO_PROVEDOR
              status: active
              priority: 100
              settings: {}
      responses:
        '201':
          description: Credencial criada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
      description: Cadastra uma credencial criptografada. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /admin/credentials/{credential}:
    get:
      tags:
      - Administração
      summary: Consulta uma credencial mascarada
      operationId: adminCredentialShow
      parameters:
      - $ref: '#/components/parameters/CredentialId'
      responses:
        '200':
          description: Credencial
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      description: Consulta uma credencial mascarada. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    put:
      tags:
      - Administração
      summary: Atualiza uma credencial
      operationId: adminCredentialUpdate
      parameters:
      - $ref: '#/components/parameters/CredentialId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProviderCredentialUpdateRequest'
      responses:
        '200':
          description: Credencial atualizada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
      description: Atualiza uma credencial. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    patch:
      tags:
      - Administração
      summary: Atualiza parcialmente uma credencial
      operationId: adminCredentialPatch
      parameters:
      - $ref: '#/components/parameters/CredentialId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProviderCredentialUpdateRequest'
      responses:
        '200':
          description: Credencial atualizada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
      description: Atualiza parcialmente uma credencial. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    delete:
      tags:
      - Administração
      summary: Remove uma credencial
      operationId: adminCredentialDestroy
      parameters:
      - $ref: '#/components/parameters/CredentialId'
      responses:
        '200':
          description: Credencial removida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
      description: Remove uma credencial. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /admin/provider-credentials/{credential}/test:
    post:
      tags:
      - Administração
      summary: Testa uma credencial de IA
      operationId: adminCredentialTest
      parameters:
      - $ref: '#/components/parameters/CredentialId'
      responses:
        '200':
          description: Teste concluído
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '503':
          $ref: '#/components/responses/Unavailable'
      description: Testa uma credencial de IA. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /admin/models:
    get:
      tags:
      - Administração
      summary: Lista todos os modelos
      operationId: adminModelIndex
      parameters:
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: Modelos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      description: Lista todos os modelos. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    post:
      tags:
      - Administração
      summary: Cadastra um modelo
      operationId: adminModelStore
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AiModelRequest'
      responses:
        '201':
          description: Modelo criado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
      description: Cadastra um modelo. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /admin/models/{model}:
    get:
      tags:
      - Administração
      summary: Consulta um modelo
      operationId: adminModelShow
      parameters:
      - $ref: '#/components/parameters/ModelId'
      responses:
        '200':
          description: Modelo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      description: Consulta um modelo. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    put:
      tags:
      - Administração
      summary: Atualiza um modelo
      operationId: adminModelUpdate
      parameters:
      - $ref: '#/components/parameters/ModelId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AiModelRequest'
      responses:
        '200':
          description: Modelo atualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
      description: Atualiza um modelo. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    patch:
      tags:
      - Administração
      summary: Atualiza parcialmente um modelo
      operationId: adminModelPatch
      parameters:
      - $ref: '#/components/parameters/ModelId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AiModelRequest'
      responses:
        '200':
          description: Modelo atualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
      description: Atualiza parcialmente um modelo. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    delete:
      tags:
      - Administração
      summary: Remove um modelo
      operationId: adminModelDestroy
      parameters:
      - $ref: '#/components/parameters/ModelId'
      responses:
        '200':
          description: Modelo removido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
      description: Remove um modelo. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /admin/credit-packages:
    get:
      tags:
      - Administração
      summary: Lista todos os pacotes
      operationId: adminCreditPackageIndex
      responses:
        '200':
          description: Pacotes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditPackageListEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      description: Lista todos os pacotes. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    post:
      tags:
      - Administração
      summary: Cria um pacote de créditos
      operationId: adminCreditPackageStore
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditPackageRequest'
      responses:
        '201':
          description: Pacote criado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditPackageEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
      description: Cria um pacote de créditos. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /admin/credit-packages/{creditPackage}:
    get:
      tags:
      - Administração
      summary: Consulta um pacote
      operationId: adminCreditPackageShow
      parameters:
      - $ref: '#/components/parameters/CreditPackageId'
      responses:
        '200':
          description: Pacote
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditPackageEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      description: Consulta um pacote. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    put:
      tags:
      - Administração
      summary: Atualiza um pacote
      operationId: adminCreditPackageUpdate
      parameters:
      - $ref: '#/components/parameters/CreditPackageId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditPackageRequest'
      responses:
        '200':
          description: Pacote atualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditPackageEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
      description: Atualiza um pacote. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    patch:
      tags:
      - Administração
      summary: Atualiza parcialmente um pacote
      operationId: adminCreditPackagePatch
      parameters:
      - $ref: '#/components/parameters/CreditPackageId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditPackageRequest'
      responses:
        '200':
          description: Pacote atualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditPackageEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
      description: Atualiza parcialmente um pacote. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
    delete:
      tags:
      - Administração
      summary: Remove um pacote
      operationId: adminCreditPackageDestroy
      parameters:
      - $ref: '#/components/parameters/CreditPackageId'
      responses:
        '200':
          description: Pacote removido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
      description: Remove um pacote. Consulte os parâmetros, exemplos e respostas disponíveis nesta seção.
  /admin/users/{user}/credits:
    post:
      tags:
      - Administração
      summary: Concede créditos manualmente
      operationId: adminUserCreditGrant
      description: Registra a operação no livro-caixa e na auditoria.
      parameters:
      - $ref: '#/components/parameters/UserRouteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrantCreditsRequest'
            example:
              amount_units: 10000
              description: Crédito promocional
      responses:
        '200':
          description: Créditos concedidos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '423':
          $ref: '#/components/responses/PasswordConfirmationRequired'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: YNIX
      description: Token emitido no formato `ynix_<ambiente>_...`.
  parameters:
    IdempotencyKey:
      in: header
      name: Idempotency-Key
      required: false
      description: Identificador único da operação lógica. Recomendado para chat e obrigatório operacionalmente para recargas
        seguras.
      schema:
        type: string
        minLength: 8
        maxLength: 120
    AsaasWebhookToken:
      in: header
      name: asaas-access-token
      required: true
      schema:
        type: string
        minLength: 32
        maxLength: 255
    Page:
      in: query
      name: page
      schema:
        type: integer
        minimum: 1
        default: 1
    UserId:
      in: path
      name: id
      required: true
      schema:
        type: integer
    VerificationHash:
      in: path
      name: hash
      required: true
      schema:
        type: string
    ApiTokenId:
      in: path
      name: apiToken
      required: true
      schema:
        type: string
        format: uuid
    PaymentId:
      in: path
      name: payment
      required: true
      schema:
        type: string
        format: uuid
    PaymentMethodId:
      in: path
      name: paymentMethod
      required: true
      schema:
        type: integer
    ProviderId:
      in: path
      name: provider
      required: true
      schema:
        type: integer
    CredentialId:
      in: path
      name: credential
      required: true
      schema:
        type: integer
    ModelId:
      in: path
      name: model
      required: true
      schema:
        type: integer
    CreditPackageId:
      in: path
      name: creditPackage
      required: true
      schema:
        type: integer
    Cep:
      in: path
      name: cep
      required: true
      schema:
        type: string
        pattern: ^\d{8}$
        example: '01001000'
    Cnpj:
      in: path
      name: cnpj
      required: true
      schema:
        type: string
        pattern: ^\d{14}$
        example: '19131243000197'
    UserRouteId:
      in: path
      name: user
      required: true
      schema:
        type: integer
    ProjectId:
      in: path
      name: project
      required: true
      schema:
        type: integer
  schemas:
    SuccessEnvelope:
      type: object
      required:
      - success
      - message
      - data
      - meta
      - request_id
      properties:
        success:
          type: boolean
          const: true
        message:
          type: string
        data: {}
        meta:
          type: object
          additionalProperties: true
        request_id:
          type:
          - string
          - 'null'
    ErrorEnvelope:
      type: object
      required:
      - success
      - error
      - request_id
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          required:
          - code
          - message
          - details
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
              additionalProperties: true
        request_id:
          type:
          - string
          - 'null'
    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
        last_page:
          type: integer
        total:
          type: integer
    PaginatedEnvelope:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            type: array
            items: {}
          meta:
            $ref: '#/components/schemas/PaginationMeta'
    RegisterRequest:
      type: object
      required:
      - name
      - email
      - password
      - password_confirmation
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 120
        email:
          type: string
          format: email
          maxLength: 190
        password:
          type: string
          format: password
          minLength: 10
          description: Deve conter maiúsculas, minúsculas, números e símbolos.
        password_confirmation:
          type: string
          format: password
        document:
          type:
          - string
          - 'null'
          description: CPF ou CNPJ válido.
        phone:
          type:
          - string
          - 'null'
        timezone:
          type:
          - string
          - 'null'
          default: America/Sao_Paulo
        device_name:
          type:
          - string
          - 'null'
          maxLength: 120
    LoginRequest:
      type: object
      required:
      - email
      - password
      - device_name
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          format: password
        device_name:
          type: string
          maxLength: 120
    ForgotPasswordRequest:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
    ResetPasswordRequest:
      type: object
      required:
      - token
      - email
      - password
      - password_confirmation
      properties:
        token:
          type: string
        email:
          type: string
          format: email
        password:
          type: string
          format: password
          minLength: 10
        password_confirmation:
          type: string
          format: password
    UpdatePasswordRequest:
      type: object
      required:
      - current_password
      - password
      - password_confirmation
      properties:
        current_password:
          type: string
          format: password
        password:
          type: string
          format: password
          minLength: 10
        password_confirmation:
          type: string
          format: password
    UpdateProfileRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 120
        email:
          type: string
          format: email
        document:
          type:
          - string
          - 'null'
        phone:
          type:
          - string
          - 'null'
        timezone:
          type: string
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
        email_verified_at:
          type:
          - string
          - 'null'
          format: date-time
        document:
          type:
          - string
          - 'null'
        phone:
          type:
          - string
          - 'null'
        timezone:
          type: string
        locale:
          type: string
        status:
          type: string
        is_admin:
          type: boolean
        last_login_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
    AuthResponse:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            type: object
            properties:
              user:
                $ref: '#/components/schemas/User'
              token:
                type: string
              token_type:
                type: string
                const: Bearer
    UserEnvelope:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/User'
    ApiTokenCreateRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          maxLength: 120
        abilities:
          type:
          - array
          - 'null'
          maxItems: 20
          items:
            type: string
            maxLength: 80
        expires_at:
          type:
          - string
          - 'null'
          format: date-time
    ChatMessage:
      type: object
      required:
      - role
      - content
      properties:
        role:
          type: string
          enum:
          - system
          - user
          - assistant
          - tool
        content:
          oneOf:
          - type: string
          - type: array
            items:
              type: object
              additionalProperties: true
        name:
          type:
          - string
          - 'null'
          maxLength: 100
        tool_call_id:
          type:
          - string
          - 'null'
          maxLength: 190
    ChatCompletionRequest:
      type: object
      required:
      - model
      - messages
      properties:
        model:
          type: string
          maxLength: 190
          example: auto
        messages:
          type: array
          minItems: 1
          maxItems: 200
          items:
            $ref: '#/components/schemas/ChatMessage'
        stream:
          type: boolean
          default: false
        temperature:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 2
        top_p:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 1
        max_tokens:
          type:
          - integer
          - 'null'
          minimum: 1
          maximum: 131072
        reasoning_effort:
          type:
          - string
          - 'null'
          enum:
          - none
          - low
          - medium
          - high
          - null
        tools:
          type:
          - array
          - 'null'
          maxItems: 64
          items:
            type: object
            additionalProperties: true
        tool_choice: {}
        files:
          type:
          - array
          - 'null'
          maxItems: 20
          items:
            type: object
            additionalProperties: true
        response_format:
          type:
          - object
          - 'null'
          additionalProperties: true
        metadata:
          type:
          - object
          - 'null'
          additionalProperties: true
        max_credits:
          type:
          - number
          - 'null'
          minimum: 0.001
          description: Limite máximo em créditos visíveis para esta execução.
        project_id:
          type:
          - integer
          - 'null'
          description: Projeto da própria conta ao qual a solicitação será vinculada.
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: chat.completion
        created:
          type: integer
        model:
          type: string
        provider:
          type: string
        choices:
          type: array
          items:
            type: object
            additionalProperties: true
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
            completion_tokens:
              type: integer
            total_tokens:
              type: integer
            credit_units:
              type: integer
    AiModel:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          const: model
        name:
          type: string
        provider:
          type: string
        external_id:
          type: string
        capabilities:
          type: array
          items:
            type: string
        context_window:
          type:
          - integer
          - 'null'
        max_output_tokens:
          type:
          - integer
          - 'null'
        pricing:
          type: object
          properties:
            input_credit_units_per_million:
              type: integer
            output_credit_units_per_million:
              type: integer
            request_base_credit_units:
              type: integer
    ModelEnvelope:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/AiModel'
    ModelListEnvelope:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/AiModel'
    Wallet:
      type: object
      properties:
        balance_units:
          type: integer
        reserved_units:
          type: integer
        debt_units:
          type: integer
        available_units:
          type: integer
        scale:
          type: integer
    WalletEnvelope:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/Wallet'
    CreditPackage:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
        amount_cents:
          type: integer
        amount_brl:
          type: string
        credit_units:
          type: integer
        bonus_credit_units:
          type: integer
        total_credit_units:
          type: integer
        is_active:
          type: boolean
    CreditPackageEnvelope:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/CreditPackage'
    CreditPackageListEnvelope:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/CreditPackage'
    CreditPackageRequest:
      type: object
      required:
      - name
      - slug
      - amount_cents
      - credit_units
      - bonus_credit_units
      - is_active
      - sort_order
      properties:
        name:
          type: string
          maxLength: 120
        slug:
          type: string
          maxLength: 80
        amount_cents:
          type: integer
          minimum: 100
        credit_units:
          type: integer
          minimum: 1
        bonus_credit_units:
          type: integer
          minimum: 0
        is_active:
          type: boolean
        sort_order:
          type: integer
          minimum: 0
        metadata:
          type:
          - object
          - 'null'
          additionalProperties: true
    CardData:
      type: object
      required:
      - holderName
      - number
      - expiryMonth
      - expiryYear
      - ccv
      properties:
        holderName:
          type: string
          maxLength: 120
        number:
          type: string
          minLength: 13
          maxLength: 19
          writeOnly: true
        expiryMonth:
          type: integer
          minimum: 1
          maximum: 12
        expiryYear:
          type: integer
          minimum: 2026
          maximum: 2100
        ccv:
          type: string
          pattern: ^\d{3,4}$
          writeOnly: true
    CardHolderInfo:
      type: object
      required:
      - name
      - email
      - cpf_cnpj
      - postal_code
      - address_number
      - phone
      properties:
        name:
          type: string
          maxLength: 120
        email:
          type: string
          format: email
          maxLength: 190
        cpf_cnpj:
          type: string
        postal_code:
          type: string
          pattern: ^\d{8}$
        address_number:
          type: string
          maxLength: 20
        address_complement:
          type:
          - string
          - 'null'
          maxLength: 60
        phone:
          type: string
          pattern: ^\d{10,11}$
    RechargeRequest:
      type: object
      required:
      - credit_package_id
      - billing_type
      properties:
        credit_package_id:
          type: integer
        billing_type:
          type: string
          enum:
          - PIX
          - CREDIT_CARD
        saved_payment_method_id:
          type:
          - integer
          - 'null'
        save_card:
          type: boolean
          default: false
        credit_card:
          oneOf:
          - $ref: '#/components/schemas/CardData'
          - type: 'null'
        holder_info:
          oneOf:
          - $ref: '#/components/schemas/CardHolderInfo'
          - type: 'null'
    TokenizeCardRequest:
      type: object
      required:
      - credit_card
      - holder_info
      properties:
        credit_card:
          $ref: '#/components/schemas/CardData'
        holder_info:
          $ref: '#/components/schemas/CardHolderInfo'
    Payment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        external_id:
          type:
          - string
          - 'null'
        external_reference:
          type:
          - string
          - 'null'
        provider:
          type: string
        billing_type:
          type: string
          enum:
          - PIX
          - CREDIT_CARD
        status:
          type: string
          enum:
          - pending
          - awaiting_risk_analysis
          - authorized
          - confirmed
          - received
          - overdue
          - refund_in_progress
          - partially_refunded
          - refunded
          - chargeback
          - cancelled
          - failed
        provider_status:
          type:
          - string
          - 'null'
        amount_cents:
          type: integer
        amount_brl:
          type: string
        credit_units:
          type: integer
        payment_data:
          type:
          - object
          - 'null'
          additionalProperties: true
        failure:
          oneOf:
          - type: object
            properties:
              code:
                type:
                - string
                - 'null'
              message:
                type:
                - string
                - 'null'
          - type: 'null'
        expires_at:
          type:
          - string
          - 'null'
          format: date-time
        paid_at:
          type:
          - string
          - 'null'
          format: date-time
        credited_at:
          type:
          - string
          - 'null'
          format: date-time
        refunded_at:
          type:
          - string
          - 'null'
          format: date-time
        reversed_at:
          type:
          - string
          - 'null'
          format: date-time
        cancelled_at:
          type:
          - string
          - 'null'
          format: date-time
        last_synced_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type:
          - string
          - 'null'
          format: date-time
    PaymentEnvelope:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/Payment'
    PaymentMethod:
      type: object
      properties:
        id:
          type: integer
        provider:
          type: string
        brand:
          type:
          - string
          - 'null'
        last_four:
          type:
          - string
          - 'null'
        expiry_month:
          type:
          - integer
          - 'null'
        expiry_year:
          type:
          - integer
          - 'null'
        holder_name:
          type:
          - string
          - 'null'
        status:
          type: string
        is_default:
          type: boolean
        last_used_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type:
          - string
          - 'null'
          format: date-time
    PaymentMethodEnvelope:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/PaymentMethod'
    PaymentMethodListEnvelope:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/PaymentMethod'
    AsaasWebhookPayload:
      type: object
      required:
      - event
      properties:
        id:
          type:
          - string
          - 'null'
        event:
          type: string
          example: PAYMENT_RECEIVED
        payment:
          type:
          - object
          - 'null'
          additionalProperties: true
      additionalProperties: true
    Provider:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
        driver:
          type: string
        base_url:
          type:
          - string
          - 'null'
          format: uri
        status:
          type: string
        priority:
          type: integer
        timeout_seconds:
          type: integer
        headers:
          type: object
          additionalProperties: true
        settings:
          type: object
          additionalProperties: true
        credentials_count:
          type:
          - integer
          - 'null'
        models_count:
          type:
          - integer
          - 'null'
        created_at:
          type:
          - string
          - 'null'
          format: date-time
    ProviderEnvelope:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/Provider'
    ProviderRequest:
      type: object
      required:
      - name
      - slug
      - driver
      - status
      - priority
      - timeout_seconds
      properties:
        name:
          type: string
          maxLength: 120
        slug:
          type: string
          maxLength: 80
        driver:
          type: string
          enum:
          - openai-compatible
          - gemini
          - ollama
        base_url:
          type:
          - string
          - 'null'
          format: uri
          maxLength: 500
        status:
          type: string
          enum:
          - active
          - disabled
          - maintenance
        priority:
          type: integer
          minimum: 0
          maximum: 10000
        timeout_seconds:
          type: integer
          minimum: 5
          maximum: 600
        headers:
          type:
          - object
          - 'null'
          additionalProperties: true
        settings:
          type:
          - object
          - 'null'
          additionalProperties: true
    ProviderCredential:
      type: object
      properties:
        id:
          type: integer
        provider_id:
          type: integer
        name:
          type: string
        environment:
          type: string
        fingerprint:
          type: string
        status:
          type: string
        priority:
          type: integer
        model_access_mode:
          type: string
          enum: [all, allow_only, block_selected]
        model_ids:
          type: array
          items:
            type: integer
        failure_count:
          type: integer
        last_used_at:
          type:
          - string
          - 'null'
          format: date-time
        last_checked_at:
          type:
          - string
          - 'null'
          format: date-time
        last_failed_at:
          type:
          - string
          - 'null'
          format: date-time
        disabled_until:
          type:
          - string
          - 'null'
          format: date-time
        last_error:
          type:
          - string
          - 'null'
        settings:
          type: object
          additionalProperties: true
        created_at:
          type:
          - string
          - 'null'
          format: date-time
    CredentialEnvelope:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/ProviderCredential'
    CredentialListEnvelope:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/ProviderCredential'
    ProviderCredentialRequest:
      type: object
      required:
      - name
      - environment
      - secret
      - status
      - priority
      - model_access_mode
      properties:
        name:
          type: string
          maxLength: 120
        environment:
          type: string
          enum:
          - sandbox
          - production
        secret:
          type: object
          minProperties: 1
          additionalProperties: true
          writeOnly: true
        status:
          type: string
          enum:
          - active
          - disabled
          - error
        priority:
          type: integer
          minimum: 0
          maximum: 10000
        model_access_mode:
          type: string
          enum: [all, allow_only, block_selected]
        model_ids:
          type: array
          items:
            type: integer
        settings:
          type:
          - object
          - 'null'
          additionalProperties: true
    ProviderCredentialUpdateRequest:
      type: object
      required:
      - name
      - environment
      - status
      - priority
      - model_access_mode
      properties:
        name:
          type: string
          maxLength: 120
        environment:
          type: string
          enum:
          - sandbox
          - production
        secret:
          type: object
          minProperties: 1
          additionalProperties: true
          writeOnly: true
        status:
          type: string
          enum:
          - active
          - disabled
          - error
        priority:
          type: integer
          minimum: 0
          maximum: 10000
        model_access_mode:
          type: string
          enum: [all, allow_only, block_selected]
        model_ids:
          type: array
          items:
            type: integer
        settings:
          type:
          - object
          - 'null'
          additionalProperties: true
    AiModelRequest:
      type: object
      required:
      - provider_id
      - external_id
      - name
      - status
      - priority
      - capabilities
      - input_credit_units_per_million
      - output_credit_units_per_million
      - request_base_credit_units
      properties:
        provider_id:
          type: integer
        external_id:
          type: string
          maxLength: 190
        name:
          type: string
          maxLength: 190
        alias:
          type:
          - string
          - 'null'
          maxLength: 120
        status:
          type: string
          enum:
          - active
          - disabled
        priority:
          type: integer
          minimum: 0
          maximum: 10000
        capabilities:
          type: array
          minItems: 1
          items:
            type: string
        context_window:
          type:
          - integer
          - 'null'
          minimum: 1
        max_output_tokens:
          type:
          - integer
          - 'null'
          minimum: 1
        input_credit_units_per_million:
          type: integer
          minimum: 0
        output_credit_units_per_million:
          type: integer
          minimum: 0
        request_base_credit_units:
          type: integer
          minimum: 0
        settings:
          type:
          - object
          - 'null'
          additionalProperties: true
    GrantCreditsRequest:
      type: object
      required:
      - amount_units
      - description
      properties:
        amount_units:
          type: integer
          minimum: 1
        description:
          type: string
          maxLength: 255
    CostEstimate:
      type: object
      properties:
        model:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string
            alias:
              type:
              - string
              - 'null'
            provider:
              type: string
        estimated_usage:
          type: object
          properties:
            input_tokens:
              type: integer
            minimum_output_tokens:
              type: integer
            expected_output_tokens:
              type: integer
            maximum_output_tokens:
              type: integer
        credits:
          type: object
          properties:
            minimum:
              type: integer
            expected:
              type: integer
            maximum:
              type: integer
            reservation:
              type: integer
            formatted:
              type: object
              additionalProperties:
                type: string
            approximate_brl:
              type: object
              additionalProperties:
                type: number
        affordability:
          type:
          - object
          - 'null'
          additionalProperties: true
    CostEstimateEnvelope:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/CostEstimate'
    ProjectRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 120
        environment:
          type: string
          enum:
          - test
          - production
        status:
          type: string
          enum:
          - active
          - paused
          - archived
        description:
          type:
          - string
          - 'null'
          maxLength: 2000
    Project:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
        environment:
          type: string
          enum:
          - test
          - production
        status:
          type: string
          enum:
          - active
          - paused
          - archived
        description:
          type:
          - string
          - 'null'
        api_tokens_count:
          type:
          - integer
          - 'null'
        requests_count:
          type:
          - integer
          - 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ProjectEnvelope:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/Project'
    ProjectListEnvelope:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/Project'
          meta:
            $ref: '#/components/schemas/PaginationMeta'
  responses:
    BadRequest:
      description: Requisição inválida
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: badrequest
              message: Requisição inválida
              details: {}
            request_id: req_example
    Unauthorized:
      description: Token ausente, inválido ou revogado
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: unauthorized
              message: Token ausente, inválido ou revogado
              details: {}
            request_id: req_example
    InsufficientCredits:
      description: Créditos insuficientes
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: insufficientcredits
              message: Créditos insuficientes
              details: {}
            request_id: req_example
    Forbidden:
      description: Permissão ou ability insuficiente
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: forbidden
              message: Permissão ou ability insuficiente
              details: {}
            request_id: req_example
    NotFound:
      description: Recurso não encontrado
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: notfound
              message: Recurso não encontrado
              details: {}
            request_id: req_example
    Conflict:
      description: Conflito de estado ou idempotência
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: conflict
              message: Conflito de estado ou idempotência
              details: {}
            request_id: req_example
    ValidationError:
      description: Dados inválidos
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: validationerror
              message: Dados inválidos
              details: {}
            request_id: req_example
    PasswordConfirmationRequired:
      description: Confirmação recente da senha necessária
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: passwordconfirmationrequired
              message: Confirmação recente da senha necessária
              details: {}
            request_id: req_example
    RateLimited:
      description: Limite de requisições excedido
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: ratelimited
              message: Limite de requisições excedido
              details: {}
            request_id: req_example
    UpstreamError:
      description: Falha retornada por provedor externo
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: upstreamerror
              message: Falha retornada por provedor externo
              details: {}
            request_id: req_example
    Unavailable:
      description: Serviço ou configuração indisponível
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: unavailable
              message: Serviço ou configuração indisponível
              details: {}
            request_id: req_example
