Referência da API

{
  "tags": [
    "health"
  ],
  "summary": "Disponibilidade do serviço e do banco",
  "security": [],
  "responses": {
    "200": {
      "description": "Serviço no ar.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Health"
          },
          "example": {
            "status": "ok",
            "mode": "local",
            "payments_enabled": false,
            "provider": "simulation",
            "origin": "http://localhost:3000"
          }
        }
      }
    }
  },
  "operationId": "healthCheck"
}

{
  "tags": [
    "auth"
  ],
  "summary": "Criar conta",
  "description": "Responde sempre a mesma mensagem, exista ou não a conta, para não revelar cadastros. Quando o e-mail é novo, enfileira o link de confirmação na caixa local.",
  "security": [],
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/RegisterInput"
        }
      }
    }
  },
  "responses": {
    "202": {
      "$ref": "#/components/responses/Accepted"
    },
    "403": {
      "$ref": "#/components/responses/OriginInvalid"
    },
    "413": {
      "$ref": "#/components/responses/TooLarge"
    },
    "415": {
      "$ref": "#/components/responses/UnsupportedMedia"
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "operationId": "registerAccount"
}

{
  "tags": [
    "auth"
  ],
  "summary": "Entrar",
  "description": "Cria sessão opaca no servidor e devolve o cookie movvi_session (HttpOnly, SameSite=Lax, Secure quando a origem é HTTPS). O csrf_token da resposta deve acompanhar as alterações autenticadas no cabeçalho X-CSRF-Token. Quando a conta tem segundo fator confirmado, responde 200 com second_factor_required e um desafio, sem criar sessao; a entrada termina em POST /auth/second-factor.",
  "security": [],
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/LoginInput"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Sessão criada.",
      "headers": {
        "Set-Cookie": {
          "description": "movvi_session=<64 hex>; Path=/; HttpOnly; SameSite=Lax; Max-Age=43200",
          "schema": {
            "type": "string"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SessionUser"
          }
        }
      }
    },
    "401": {
      "description": "Credenciais inválidas ou conta desativada. A mesma resposta é usada nos três casos.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "$ref": "#/components/responses/OriginInvalid"
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "operationId": "login"
}

{
  "tags": [
    "auth"
  ],
  "summary": "Sair",
  "description": "Revoga a sessão atual e limpa o cookie. Não tem corpo, mas ainda assim exige Content-Type: application/json.",
  "parameters": [
    {
      "$ref": "#/components/parameters/ContentType"
    },
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ],
  "responses": {
    "204": {
      "description": "Sessão revogada. Sem corpo."
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenMutation"
    },
    "415": {
      "$ref": "#/components/responses/UnsupportedMedia"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "operationId": "logout"
}

{
  "tags": [
    "auth"
  ],
  "summary": "Sessão atual e vínculos",
  "description": "Renova o carimbo de atividade da sessão. A sessão expira em 12 horas de duração máxima ou 30 minutos sem atividade.",
  "responses": {
    "200": {
      "description": "Sessão válida.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SessionState"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "operationId": "getSession"
}

{
  "tags": [
    "auth"
  ],
  "summary": "Confirmar e-mail",
  "description": "Consome o token do link de confirmação. Tokens são de uso único e expiram em 24 horas. O código demonstrativo 123456 não é aceito.",
  "security": [],
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TokenInput"
        }
      }
    }
  },
  "responses": {
    "200": {
      "$ref": "#/components/responses/Message"
    },
    "403": {
      "$ref": "#/components/responses/OriginInvalid"
    },
    "422": {
      "description": "Token inválido, já usado ou expirado (TOKEN_INVALID), ou campos fora do formato (VALIDATION_ERROR).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "operationId": "verifyEmail"
}

{
  "tags": [
    "auth"
  ],
  "summary": "Reenviar confirmação de e-mail",
  "description": "Exige sessão. Não faz nada quando o e-mail já está confirmado, mas responde igual. Não tem corpo, mas ainda assim exige Content-Type: application/json.",
  "parameters": [
    {
      "$ref": "#/components/parameters/ContentType"
    },
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ],
  "responses": {
    "202": {
      "$ref": "#/components/responses/Accepted"
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenMutation"
    },
    "415": {
      "$ref": "#/components/responses/UnsupportedMedia"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "operationId": "resendVerification"
}

{
  "tags": [
    "auth"
  ],
  "summary": "Pedir link de recuperação",
  "description": "Responde sempre a mesma mensagem, exista ou não a conta. O token de redefinição expira em 30 minutos.",
  "security": [],
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "email"
          ],
          "properties": {
            "email": {
              "$ref": "#/components/schemas/Email"
            }
          }
        }
      }
    }
  },
  "responses": {
    "202": {
      "$ref": "#/components/responses/Accepted"
    },
    "403": {
      "$ref": "#/components/responses/OriginInvalid"
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "operationId": "requestPasswordRecovery"
}

{
  "tags": [
    "auth"
  ],
  "summary": "Redefinir senha",
  "description": "Consome o token de recuperação e revoga todas as sessões do usuário.",
  "security": [],
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PasswordResetInput"
        }
      }
    }
  },
  "responses": {
    "200": {
      "$ref": "#/components/responses/Message"
    },
    "403": {
      "$ref": "#/components/responses/OriginInvalid"
    },
    "422": {
      "description": "Token inválido, já usado ou expirado (TOKEN_INVALID), ou campos fora do formato (VALIDATION_ERROR).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "operationId": "resetPassword"
}

{
  "tags": [
    "sellers"
  ],
  "summary": "Listar os negócios do usuário",
  "description": "Retorna apenas os vendedores em que o usuário tem vínculo. Exige e-mail confirmado.",
  "responses": {
    "200": {
      "description": "Lista de vínculos.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "items"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/SellerListItem"
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/EmailNotVerified"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "operationId": "listSellers"
}

{
  "tags": [
    "sellers"
  ],
  "summary": "Cadastrar negócio",
  "description": "Cria o vendedor e o vínculo owner do usuário autenticado. O documento é guardado cifrado; a unicidade usa impressão HMAC, então documentos repetidos respondem 409 sem revelar de quem é o cadastro existente.",
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/SellerInput"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Negócio cadastrado.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SellerCreated"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/EmailNotVerified"
    },
    "409": {
      "description": "Documento já cadastrado (SELLER_CONFLICT).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "operationId": "createSeller"
}

{
  "tags": [
    "sellers"
  ],
  "summary": "Detalhe do negócio",
  "description": "Responde 404, e não 403, quando não há vínculo, para não revelar a existência do registro.",
  "responses": {
    "200": {
      "description": "Dados do vendedor.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Seller"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/EmailNotVerified"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "operationId": "getSeller"
}

{
  "tags": [
    "sellers"
  ],
  "summary": "Alterar o nome da loja",
  "description": "Único campo alterável nesta etapa. Exige vínculo owner e expected_version igual à versão atual; divergência responde 409.",
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/SellerPatchInput"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Alteração aplicada.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SellerPatched"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/VersionConflict"
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "operationId": "updateSeller"
}

{
  "tags": [
    "verification"
  ],
  "summary": "Histórico de envios de verificação",
  "description": "Até 20 registros, da versão mais recente para a mais antiga. Exige vínculo owner. provider_connected é sempre false nesta etapa: não existe análise externa.",
  "responses": {
    "200": {
      "description": "Envios registrados.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "items",
              "provider_connected"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/VerificationCase"
                }
              },
              "provider_connected": {
                "type": "boolean",
                "enum": [
                  false
                ]
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "operationId": "listVerificationCases"
}

{
  "tags": [
    "verification"
  ],
  "summary": "Enviar dados para verificação",
  "description": "Aceito somente quando o vendedor está em draft ou needs_changes. Muda a situação para verification_pending e incrementa a versão. NÃO representa aprovação financeira: nenhum arquivo é transmitido e não há análise externa.",
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VerificationSubmissionInput"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Envio registrado localmente.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/VerificationSubmitted"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "Versão divergente (VERSION_CONFLICT) ou situação que não permite novo envio (INVALID_STATE).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "operationId": "submitVerification"
}

{
  "tags": [
    "audit"
  ],
  "summary": "Eventos de auditoria do vendedor",
  "description": "50 registros por página, do mais recente para o mais antigo. Exige vínculo owner. A tabela bloqueia UPDATE, DELETE e TRUNCATE por gatilhos. A paginação por offset é do protótipo local; trocar por cursor antes de expor a API externamente.",
  "parameters": [
    {
      "$ref": "#/components/parameters/Offset"
    }
  ],
  "responses": {
    "200": {
      "description": "Página de eventos.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "items",
              "next_offset"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AuditEvent"
                }
              },
              "next_offset": {
                "type": "integer",
                "nullable": true,
                "description": "Próximo offset, ou null quando a página não encheu."
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "operationId": "listAuditEvents"
}

{
  "operationId": "listCharges",
  "tags": [
    "charges"
  ],
  "summary": "Listar cobranças do vendedor",
  "description": "50 por página, da mais recente para a mais antiga.",
  "parameters": [
    {
      "$ref": "#/components/parameters/ChargeStatusFilter"
    },
    {
      "$ref": "#/components/parameters/Offset"
    }
  ],
  "responses": {
    "200": {
      "description": "Página de cobranças.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "items",
              "next_offset"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Charge"
                }
              },
              "next_offset": {
                "type": "integer",
                "nullable": true
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/EmailNotVerified"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "createCharge",
  "tags": [
    "charges"
  ],
  "summary": "Criar cobrança",
  "description": "Copia a tarifa vigente para a cobrança, pede o código ao adaptador de provedor e devolve a URL do checkout. Enquanto o adaptador for o de simulação, nada é pagável.",
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    },
    {
      "$ref": "#/components/parameters/IdempotencyKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ChargeInput"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Cobrança criada, ou a primeira resposta repetida pela chave de idempotência.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ChargeCreated"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "Chave de idempotência reutilizada com outros dados (IDEMPOTENCY_MISMATCH).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "422": {
      "description": "Campos fora do formato (VALIDATION_ERROR), valor que não cobre a tarifa (AMOUNT_BELOW_FEE) ou chave de idempotência mal formada (IDEMPOTENCY_KEY_INVALID).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "getCharge",
  "tags": [
    "charges"
  ],
  "summary": "Detalhe da cobrança",
  "description": "Responde 404 quando a cobrança é de outro vendedor, sem revelar que ela existe.",
  "responses": {
    "200": {
      "description": "Cobrança.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Charge"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/EmailNotVerified"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "getPublicCheckout",
  "tags": [
    "checkout"
  ],
  "summary": "Dados públicos do checkout",
  "description": "Sem sessão: é a tela que o comprador abre. Entrega o código apenas enquanto a cobrança está pendente e dentro do prazo.",
  "security": [],
  "responses": {
    "200": {
      "description": "Dados suficientes para pagar.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PublicCheckout"
          }
        }
      }
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "receiveProviderEvent",
  "tags": [
    "providers"
  ],
  "summary": "Receber aviso do provedor",
  "description": "Confere a assinatura antes de olhar o conteúdo e grava o aviso num livro somente-adição. A chave (provedor, event_id) é o que impede aplicar duas vezes quando o mesmo aviso é reenviado. Cobrança só sai de \"pending\", saque só sai de \"processing\" e devolução só sai de \"requested\": aviso fora de ordem não reabre nem re-liquida. `payout.unknown` NÃO devolve o dinheiro reservado — liberar seria arriscar pagar duas vezes; o valor fica reservado e a conciliação passa a apontar.",
  "security": [],
  "x-authentication": "provider-signature",
  "parameters": [
    {
      "$ref": "#/components/parameters/ProviderSignature"
    },
    {
      "$ref": "#/components/parameters/ContentType"
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Corpo assinado pelo provedor. É lido como texto e verificado byte a byte antes de qualquer interpretação.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "event_id",
            "kind",
            "provider_reference",
            "occurred_at"
          ],
          "properties": {
            "event_id": {
              "type": "string",
              "maxLength": 200
            },
            "kind": {
              "type": "string",
              "enum": [
                "charge.paid",
                "charge.expired",
                "charge.canceled",
                "payout.completed",
                "payout.failed",
                "payout.unknown",
                "refund.completed",
                "refund.failed"
              ]
            },
            "amount_cents": {
              "type": "integer",
              "nullable": true
            },
            "occurred_at": {
              "type": "string",
              "format": "date-time"
            },
            "provider_reference": {
              "type": "string",
              "description": "Identificador do recurso no provedor: cobrança, repasse ou devolução."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Aviso recebido. O campo outcome diz o que foi feito; 200 significa registrado, não necessariamente aplicado.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ProviderEventReceipt"
          }
        }
      }
    },
    "401": {
      "description": "Assinatura ausente, inválida ou corpo alterado depois de assinado (EVENT_UNVERIFIED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "Provedor diferente do adaptador configurado (NOT_FOUND).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "413": {
      "$ref": "#/components/responses/TooLarge"
    },
    "415": {
      "$ref": "#/components/responses/UnsupportedMedia"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "getCurrentFees",
  "tags": [
    "money"
  ],
  "summary": "Versão de tarifa vigente",
  "description": "Versões de tarifa são imutáveis e nunca apagadas; mudar tarifa é publicar a próxima. Não há endpoint para publicar: isso é da área administrativa, na etapa 6.",
  "responses": {
    "200": {
      "description": "Tarifas em vigor.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/FeeVersion"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/EmailNotVerified"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "getBalance",
  "tags": [
    "money"
  ],
  "summary": "Saldo do vendedor",
  "description": "Somado a partir do livro de lançamentos a cada consulta. Não existe coluna de saldo que possa divergir do livro.",
  "responses": {
    "200": {
      "description": "Saldo derivado dos lançamentos.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Balance"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "listLedgerEntries",
  "tags": [
    "money"
  ],
  "summary": "Extrato do vendedor",
  "description": "Lançamentos das contas do vendedor, 50 por página, do mais recente para o mais antigo. Lançamentos das contas da plataforma não aparecem aqui.",
  "parameters": [
    {
      "$ref": "#/components/parameters/Offset"
    }
  ],
  "responses": {
    "200": {
      "description": "Página de lançamentos.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "items",
              "next_offset"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/LedgerEntry"
                }
              },
              "next_offset": {
                "type": "integer",
                "nullable": true
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "listWithdrawals",
  "tags": [
    "withdrawals"
  ],
  "summary": "Listar saques do vendedor",
  "responses": {
    "200": {
      "description": "Últimos 50 saques.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "items"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Withdrawal"
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "requestWithdrawal",
  "tags": [
    "withdrawals"
  ],
  "summary": "Pedir saque",
  "description": "Reserva valor e tarifa no mesmo instante em que grava o pedido: a conferência de saldo e o lançamento acontecem sob trava do vendedor, para que dois pedidos simultâneos não gastem o mesmo dinheiro. O saque entra na fila de revisão. Até withdrawal_review_above_cents o saque segue direto ao provedor e volta como processing; acima disso, ou sem valor de revisão definido, volta como requested e aguarda a fila.",
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/WithdrawalInput"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Saque pedido, valor reservado.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Withdrawal"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "422": {
      "description": "Campos fora do formato (VALIDATION_ERROR), abaixo do saque mínimo (WITHDRAWAL_BELOW_MINIMUM), saldo insuficiente para valor e tarifa (INSUFFICIENT_FUNDS) ou limite de 24 horas ultrapassado (DAILY_LIMIT_EXCEEDED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "getWithdrawal",
  "tags": [
    "withdrawals"
  ],
  "summary": "Detalhe do saque",
  "responses": {
    "200": {
      "description": "Saque.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Withdrawal"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "getWithdrawalReceipt",
  "tags": [
    "withdrawals"
  ],
  "summary": "Comprovante do saque",
  "description": "Só existe para saque concluído. Emitir comprovante de operação não concluída é o tipo de documento que confunde quem recebe.",
  "responses": {
    "200": {
      "description": "Comprovante.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/WithdrawalReceipt"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "Saque ainda não concluído (RECEIPT_UNAVAILABLE).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "listRefunds",
  "tags": [
    "refunds"
  ],
  "summary": "Listar devoluções do vendedor",
  "responses": {
    "200": {
      "description": "Últimas 50 devoluções.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "items"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Refund"
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "requestRefund",
  "tags": [
    "refunds"
  ],
  "summary": "Pedir devolução",
  "description": "Reserva o valor e entrega o pedido ao provedor. Uma devolução em aberto por cobrança, garantido por índice do banco: dois pedidos simultâneos não passam os dois. A tarifa da cobrança não é devolvida.",
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/RefundInput"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Devolução pedida, valor reservado.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Refund"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "description": "Cobrança inexistente ou de outro vendedor (NOT_FOUND). Responde igual nos dois casos.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "Cobrança não paga (CHARGE_NOT_REFUNDABLE) ou já com devolução em análise (REFUND_IN_PROGRESS).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "422": {
      "description": "Campos fora do formato (VALIDATION_ERROR), valor acima do restante devolvível (AMOUNT_ABOVE_REMAINING) ou saldo insuficiente (INSUFFICIENT_FUNDS).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "listWithdrawalQueue",
  "tags": [
    "admin"
  ],
  "summary": "Fila de revisão de saques",
  "description": "Exige papel de operador da plataforma, concedido fora da API por linha de comando. Para quem não é operador a rota responde 404, sem revelar que existe.",
  "parameters": [
    {
      "$ref": "#/components/parameters/WithdrawalStatusFilter"
    }
  ],
  "responses": {
    "200": {
      "description": "Saques mais antigos primeiro.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "items"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AdminWithdrawal"
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "decideWithdrawal",
  "tags": [
    "admin"
  ],
  "summary": "Decidir um saque",
  "description": "Recusar devolve valor e tarifa ao disponível e exige motivo. Aprovar apenas entrega o pedido ao provedor: o dinheiro segue reservado até o aviso de resultado chegar. Decidir duas vezes responde 409.",
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/DecisionInput"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Saque depois da decisão.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Withdrawal"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "O saque já saiu da fila de revisão (ALREADY_DECIDED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "422": {
      "description": "Campos fora do formato (VALIDATION_ERROR) ou recusa sem motivo (REASON_REQUIRED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    },
    "502": {
      "description": "O provedor não aceitou o repasse (PROVIDER_REFUSED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

{
  "operationId": "listApiKeys",
  "tags": [
    "keys"
  ],
  "summary": "Listar chaves de acesso",
  "responses": {
    "200": {
      "description": "Chaves do vendedor, sem segredo.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "items"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ApiKey"
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "createApiKey",
  "tags": [
    "keys"
  ],
  "summary": "Criar chave de acesso",
  "description": "O segredo é devolvido apenas nesta resposta. O servidor guarda só o digest. A chave autentica em Authorization: Bearer e alcanca apenas cobrancas e saldo do proprio vendedor.",
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "name"
          ],
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 60
            },
            "scopes": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "charges:read",
                  "charges:write",
                  "balance:read"
                ]
              },
              "minItems": 1,
              "maxItems": 3,
              "description": "Sem escopo declarado a chave nasce so de leitura. Saque, devolucao e gestao de credenciais nao tem escopo: exigem entrada com senha e segundo fator."
            }
          }
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Chave criada.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiKeyCreated"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "revokeApiKey",
  "tags": [
    "keys"
  ],
  "summary": "Revogar chave",
  "description": "Revogar é definitivo. Revogar de novo responde 404.",
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ],
  "responses": {
    "204": {
      "description": "Chave revogada."
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "getWebhook",
  "tags": [
    "webhooks"
  ],
  "summary": "Destino dos avisos",
  "responses": {
    "200": {
      "description": "Configuração atual e eventos disponíveis.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "endpoint",
              "available_events"
            ],
            "properties": {
              "endpoint": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEndpoint"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "available_events": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "saveWebhook",
  "tags": [
    "webhooks"
  ],
  "summary": "Definir destino dos avisos",
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/WebhookInput"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Destino salvo.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/WebhookEndpoint"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "422": {
      "description": "Campos fora do formato (VALIDATION_ERROR) ou destino apontando para rede interna (DESTINATION_REFUSED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "listWebhookDeliveries",
  "tags": [
    "webhooks"
  ],
  "summary": "Histórico de entregas",
  "description": "Últimas 50 tentativas, com situação, número de tentativas e o erro da última.",
  "responses": {
    "200": {
      "description": "Entregas.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "items"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/WebhookDelivery"
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "listNotifications",
  "tags": [
    "notifications"
  ],
  "summary": "Novidades da conta",
  "parameters": [
    {
      "$ref": "#/components/parameters/UnreadOnly"
    }
  ],
  "responses": {
    "200": {
      "description": "Até 50 novidades, da mais recente para a mais antiga.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "items",
              "unread"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Notification"
                }
              },
              "unread": {
                "type": "integer"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "markNotificationsRead",
  "tags": [
    "notifications"
  ],
  "summary": "Marcar como lidas",
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ReadInput"
        }
      }
    }
  },
  "responses": {
    "204": {
      "description": "Marcadas."
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "listTickets",
  "tags": [
    "support"
  ],
  "summary": "Listar solicitações",
  "responses": {
    "200": {
      "description": "Solicitações do vendedor.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "items"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Ticket"
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "openTicket",
  "tags": [
    "support"
  ],
  "summary": "Abrir solicitação",
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TicketInput"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Solicitação aberta com a primeira mensagem.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Ticket"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "getTicket",
  "tags": [
    "support"
  ],
  "summary": "Conversa da solicitação",
  "responses": {
    "200": {
      "description": "Solicitação com as mensagens em ordem.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TicketDetail"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "replyTicket",
  "tags": [
    "support"
  ],
  "summary": "Responder na conversa",
  "description": "Mensagens são somente-adição: corrigir é escrever de novo, não reescrever.",
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MessageInput"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Mensagem adicionada.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok"
            ],
            "properties": {
              "ok": {
                "type": "boolean"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "A solicitação já foi encerrada (TICKET_RESOLVED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "operationalMetrics",
  "tags": [
    "admin"
  ],
  "summary": "Estado operacional das filas e do dinheiro em andamento",
  "description": "Exige papel de operador da plataforma. Para quem não é operador a rota responde 404, sem revelar que existe. Os números contam quanto dinheiro está parado e onde, por isso não são públicos.",
  "responses": {
    "200": {
      "description": "Contagens no instante da consulta e o que passou do limite.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "collected_at",
              "counters",
              "queues",
              "money",
              "alerts"
            ],
            "properties": {
              "collected_at": {
                "type": "string",
                "format": "date-time"
              },
              "counters": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                },
                "description": "Acumulados desde que o processo subiu; zeram no reinício."
              },
              "queues": {
                "type": "object",
                "required": [
                  "webhooks_pending",
                  "webhooks_failed",
                  "webhooks_dropped",
                  "webhooks_overdue",
                  "email_pending"
                ],
                "properties": {
                  "webhooks_pending": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Avisos aguardando entrega."
                  },
                  "webhooks_failed": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Avisos que falharam e ainda serão tentados."
                  },
                  "webhooks_dropped": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Avisos que esgotaram as tentativas. O lojista não vai receber."
                  },
                  "webhooks_overdue": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Entregas marcadas para o passado e paradas."
                  },
                  "email_pending": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Mensagens ainda não entregues."
                  }
                }
              },
              "money": {
                "type": "object",
                "required": [
                  "charges_pending",
                  "withdrawals_awaiting_review",
                  "withdrawals_at_provider",
                  "withdrawals_unknown",
                  "refunds_open"
                ],
                "properties": {
                  "charges_pending": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Cobranças aguardando pagamento."
                  },
                  "withdrawals_awaiting_review": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Saques esperando decisão."
                  },
                  "withdrawals_at_provider": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Saques entregues ao provedor."
                  },
                  "withdrawals_unknown": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Saques sem resultado conhecido. Valor segue reservado."
                  },
                  "refunds_open": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Devoluções em andamento."
                  }
                }
              },
              "alerts": {
                "type": "array",
                "description": "Vazio quando nenhum limite foi ultrapassado.",
                "items": {
                  "type": "object",
                  "required": [
                    "metric",
                    "value",
                    "threshold"
                  ],
                  "properties": {
                    "metric": {
                      "type": "string"
                    },
                    "value": {
                      "type": "integer"
                    },
                    "threshold": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    }
  }
}

{
  "operationId": "secondFactorState",
  "tags": [
    "auth"
  ],
  "summary": "Situacao do segundo fator da conta",
  "responses": {
    "200": {
      "description": "Estado atual.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "enabled",
              "pending",
              "required",
              "recovery_codes_left",
              "verified_in_session"
            ],
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "pending": {
                "type": "boolean",
                "description": "Comecou o cadastro e nao confirmou. Nao vale nada ate confirmar."
              },
              "required": {
                "type": "boolean",
                "description": "Verdadeiro para operador da plataforma."
              },
              "recovery_codes_left": {
                "type": "integer",
                "minimum": 0
              },
              "verified_in_session": {
                "type": "boolean",
                "description": "Esta sessao provou o segundo fator."
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    }
  }
}

{
  "operationId": "completeSecondFactor",
  "tags": [
    "auth"
  ],
  "summary": "Segunda etapa da entrada",
  "description": "Recebe o desafio devolvido pelo login e o codigo. A sessao so nasce aqui. O desafio e de uso unico, vale cinco minutos e fecha depois de cinco tentativas.",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "challenge",
            "code"
          ],
          "properties": {
            "challenge": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            },
            "code": {
              "type": "string",
              "minLength": 6,
              "maxLength": 11,
              "description": "Seis digitos do aplicativo, ou um codigo de recuperacao."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Sessao criada; o cookie vem em Set-Cookie.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "user_id",
              "name",
              "email",
              "email_verified",
              "csrf_token"
            ],
            "properties": {
              "user_id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "email": {
                "type": "string",
                "format": "email"
              },
              "email_verified": {
                "type": "boolean"
              },
              "csrf_token": {
                "type": "string"
              },
              "used_recovery_code": {
                "type": "boolean"
              },
              "recovery_codes_left": {
                "type": "integer",
                "minimum": 0
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/OriginInvalid"
    },
    "415": {
      "$ref": "#/components/responses/UnsupportedMedia"
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    }
  ],
  "security": []
}

{
  "operationId": "disableSecondFactor",
  "tags": [
    "auth"
  ],
  "summary": "Remover o segundo fator",
  "description": "Exige senha e codigo, porque desligar a protecao e o que alguem faria com uma sessao sua aberta. Operador da plataforma nao pode remover.",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "password",
            "code"
          ],
          "properties": {
            "password": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "code": {
              "type": "string",
              "minLength": 6,
              "maxLength": 11
            }
          }
        }
      }
    }
  },
  "responses": {
    "204": {
      "description": "Removido."
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/ForbiddenRole"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "415": {
      "$ref": "#/components/responses/UnsupportedMedia"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ]
}

{
  "operationId": "startSecondFactor",
  "tags": [
    "auth"
  ],
  "summary": "Gerar o segredo do segundo fator",
  "description": "O segredo aparece uma vez. Enquanto nao for confirmado, o segundo fator nao vale e a senha continua entrando sozinha.",
  "responses": {
    "200": {
      "description": "Segredo gerado.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "secret",
              "otpauth_url",
              "notice"
            ],
            "properties": {
              "secret": {
                "type": "string"
              },
              "otpauth_url": {
                "type": "string"
              },
              "notice": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/OriginInvalid"
    },
    "409": {
      "$ref": "#/components/responses/VersionConflict"
    },
    "415": {
      "$ref": "#/components/responses/UnsupportedMedia"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ]
}

{
  "operationId": "confirmSecondFactor",
  "tags": [
    "auth"
  ],
  "summary": "Confirmar o segundo fator e receber os codigos de recuperacao",
  "description": "Pede um codigo gerado pelo aplicativo: sem essa prova alguem ativaria a protecao com um segredo que nunca funcionou e se trancaria fora. Os codigos de recuperacao aparecem so aqui.",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "code"
          ],
          "properties": {
            "code": {
              "type": "string",
              "minLength": 6,
              "maxLength": 6
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Ativado.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "recovery_codes",
              "notice"
            ],
            "properties": {
              "recovery_codes": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "notice": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/OriginInvalid"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/VersionConflict"
    },
    "415": {
      "$ref": "#/components/responses/UnsupportedMedia"
    },
    "422": {
      "description": "Código do segundo fator inválido (SECOND_FACTOR_INVALID). Não é erro de forma do pedido, então não traz field_errors.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ]
}

{
  "operationId": "adminOverview",
  "tags": [
    "admin"
  ],
  "summary": "Visão da operação",
  "description": "Contagens e receita no instante da consulta. Exige papel de operador e segundo fator verificado na sessão. Para quem não é operador responde 404.",
  "responses": {
    "200": {
      "description": "Resposta.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AdminOverview"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "description": "Operador sem segundo fator verificado nesta sessão (SECOND_FACTOR_REQUIRED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "adminListSellers",
  "tags": [
    "admin"
  ],
  "summary": "Vendedores da plataforma",
  "description": "Cadastros aguardando análise primeiro. Exige papel de operador e segundo fator verificado na sessão. Para quem não é operador responde 404.",
  "responses": {
    "200": {
      "description": "Resposta.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "items",
              "next_offset"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AdminSeller"
                }
              },
              "next_offset": {
                "type": "integer",
                "nullable": true
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "description": "Operador sem segundo fator verificado nesta sessão (SECOND_FACTOR_REQUIRED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "parameters": [
    {
      "name": "status",
      "in": "query",
      "required": false,
      "schema": {
        "$ref": "#/components/schemas/SellerStatus"
      }
    },
    {
      "name": "q",
      "in": "query",
      "required": false,
      "description": "Busca parcial, sem diferenciar maiúsculas. Curingas são tratados como texto.",
      "schema": {
        "type": "string",
        "maxLength": 120
      }
    },
    {
      "$ref": "#/components/parameters/Offset"
    }
  ]
}

{
  "operationId": "adminGetSeller",
  "tags": [
    "admin"
  ],
  "summary": "Cadastro de um vendedor",
  "description": "Responsáveis, envios de verificação e saldo. Exige papel de operador e segundo fator verificado na sessão. Para quem não é operador responde 404.",
  "responses": {
    "200": {
      "description": "Resposta.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AdminSellerDetail"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "description": "Operador sem segundo fator verificado nesta sessão (SECOND_FACTOR_REQUIRED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "adminDecideSeller",
  "tags": [
    "admin"
  ],
  "summary": "Decidir cadastro de vendedor",
  "description": "Só vale para cadastro em verification_pending. Aprovar é decisão da plataforma e não substitui o cadastro no provedor. Pedir ajuste permite reenvio; recusar encerra. Exige papel de operador e segundo fator verificado na sessão. Para quem não é operador responde 404.",
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/SellerDecisionInput"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Cadastro depois da decisão.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SellerDecided"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "description": "Operador sem segundo fator verificado nesta sessão (SECOND_FACTOR_REQUIRED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "Versão diferente da lida (VERSION_CONFLICT), cadastro fora de análise (ALREADY_DECIDED) ou sem envio (NO_SUBMISSION).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "422": {
      "description": "Campos fora do formato (VALIDATION_ERROR) ou motivo ausente (REASON_REQUIRED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "adminListCharges",
  "tags": [
    "admin"
  ],
  "summary": "Cobranças de todos os vendedores",
  "description": "Exige papel de operador e segundo fator verificado na sessão. Para quem não é operador responde 404.",
  "responses": {
    "200": {
      "description": "Resposta.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "items",
              "next_offset"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AdminCharge"
                }
              },
              "next_offset": {
                "type": "integer",
                "nullable": true
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "description": "Operador sem segundo fator verificado nesta sessão (SECOND_FACTOR_REQUIRED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "parameters": [
    {
      "$ref": "#/components/parameters/ChargeStatusFilter"
    },
    {
      "name": "q",
      "in": "query",
      "required": false,
      "description": "Busca parcial, sem diferenciar maiúsculas. Curingas são tratados como texto.",
      "schema": {
        "type": "string",
        "maxLength": 120
      }
    },
    {
      "$ref": "#/components/parameters/Offset"
    }
  ]
}

{
  "operationId": "adminListFees",
  "tags": [
    "admin"
  ],
  "summary": "Versões de tarifa",
  "description": "Exige papel de operador e segundo fator verificado na sessão. Para quem não é operador responde 404.",
  "responses": {
    "200": {
      "description": "Resposta.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "current",
              "versions"
            ],
            "properties": {
              "current": {
                "type": "object",
                "required": [
                  "version",
                  "payment_fee_cents",
                  "payment_fee_bps",
                  "withdrawal_fee_cents",
                  "withdrawal_min_cents",
                  "withdrawal_daily_limit_cents",
                  "withdrawal_daily_limit_new_cents",
                  "new_account_days",
                  "withdrawal_review_above_cents"
                ],
                "properties": {
                  "version": {
                    "type": "integer"
                  },
                  "payment_fee_cents": {
                    "type": "integer",
                    "description": "Parte fixa da tarifa por venda, em centavos."
                  },
                  "payment_fee_bps": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 1000,
                    "description": "Parte percentual por venda, em pontos-base (99 = 0,99%). Tarifa = fixa + round_half_up(valor × bps / 10000), em centavos."
                  },
                  "withdrawal_fee_cents": {
                    "type": "integer"
                  },
                  "withdrawal_min_cents": {
                    "type": "integer",
                    "description": "Menor saque aceito."
                  },
                  "withdrawal_daily_limit_cents": {
                    "type": "integer",
                    "nullable": true,
                    "description": "Soma de saques numa janela de 24 horas. Nulo é sem limite. Saques recusados ou que falharam não contam."
                  },
                  "withdrawal_daily_limit_new_cents": {
                    "type": "integer",
                    "nullable": true,
                    "description": "Limite em 24 horas enquanto a conta tiver menos de new_account_days dias. Nulo: vale o limite geral."
                  },
                  "new_account_days": {
                    "type": "integer"
                  },
                  "withdrawal_review_above_cents": {
                    "type": "integer",
                    "nullable": true,
                    "description": "Saque até este valor segue direto ao provedor; acima, vai para a fila de revisão. Nulo: todo saque é revisado."
                  }
                }
              },
              "versions": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/FeeVersionRecord"
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "description": "Operador sem segundo fator verificado nesta sessão (SECOND_FACTOR_REQUIRED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "adminPublishFees",
  "tags": [
    "admin"
  ],
  "summary": "Publicar nova versão de tarifa",
  "description": "Cria a próxima versão, em vigor imediatamente. Cobranças e saques existentes mantêm a tarifa copiada. Exige papel de operador e segundo fator verificado na sessão. Para quem não é operador responde 404.",
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/FeePublishInput"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Versão publicada.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/FeeVersionRecord"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "description": "Operador sem segundo fator verificado nesta sessão (SECOND_FACTOR_REQUIRED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "Outra versão foi publicada depois da lida (VERSION_CONFLICT).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "422": {
      "description": "Campos fora do formato (VALIDATION_ERROR), limites contraditórios (LIMITS_INCONSISTENT) ou tarifa abaixo do custo informado (FEE_BELOW_COST).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "adminListTickets",
  "tags": [
    "admin"
  ],
  "summary": "Solicitações de suporte",
  "description": "Resolvidas por último. Exige papel de operador e segundo fator verificado na sessão. Para quem não é operador responde 404.",
  "responses": {
    "200": {
      "description": "Resposta.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "items"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AdminTicket"
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "description": "Operador sem segundo fator verificado nesta sessão (SECOND_FACTOR_REQUIRED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "parameters": [
    {
      "name": "status",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "open",
          "in_progress",
          "resolved"
        ]
      }
    }
  ]
}

{
  "operationId": "adminGetTicket",
  "tags": [
    "admin"
  ],
  "summary": "Conversa de suporte",
  "description": "Exige papel de operador e segundo fator verificado na sessão. Para quem não é operador responde 404.",
  "responses": {
    "200": {
      "description": "Resposta.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AdminTicketDetail"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "description": "Operador sem segundo fator verificado nesta sessão (SECOND_FACTOR_REQUIRED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "adminAnswerTicket",
  "tags": [
    "admin"
  ],
  "summary": "Responder solicitação",
  "description": "Grava a mensagem como da plataforma e atualiza a situação. Exige papel de operador e segundo fator verificado na sessão. Para quem não é operador responde 404.",
  "parameters": [
    {
      "$ref": "#/components/parameters/Origin"
    },
    {
      "$ref": "#/components/parameters/CsrfToken"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PlatformReplyInput"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Resposta gravada.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok",
              "status"
            ],
            "properties": {
              "ok": {
                "type": "boolean"
              },
              "status": {
                "type": "string",
                "enum": [
                  "in_progress",
                  "resolved"
                ]
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "description": "Operador sem segundo fator verificado nesta sessão (SECOND_FACTOR_REQUIRED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "Solicitação já encerrada (TICKET_RESOLVED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}

{
  "operationId": "adminListAuditEvents",
  "tags": [
    "admin"
  ],
  "summary": "Auditoria da plataforma",
  "description": "Exige papel de operador e segundo fator verificado na sessão. Para quem não é operador responde 404.",
  "responses": {
    "200": {
      "description": "Resposta.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "items",
              "next_offset"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AdminAuditEvent"
                }
              },
              "next_offset": {
                "type": "integer",
                "nullable": true
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "description": "Operador sem segundo fator verificado nesta sessão (SECOND_FACTOR_REQUIRED).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "422": {
      "$ref": "#/components/responses/ValidationError"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "parameters": [
    {
      "name": "scope",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "all",
          "operator"
        ],
        "default": "all"
      }
    },
    {
      "$ref": "#/components/parameters/Offset"
    }
  ]
}

{
  "operationId": "getPublicPricing",
  "tags": [
    "checkout"
  ],
  "summary": "Tabela de tarifas pública",
  "description": "Política comercial em vigor, sem sessão, para a página inicial. Não inclui o custo do provedor.",
  "security": [],
  "responses": {
    "200": {
      "description": "Versão em vigor.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PublicPricing"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  }
}