# FineProxy Agent Pack

Versão: 2026-09-22

Use este arquivo para avaliar se uma integração de proxy existente pode migrar para a FineProxy. Ele não contém chave de API, dados da conta nem endpoint privado.

## Fontes oficiais

- Documentação interativa da API do cliente: `https://fineproxy.org/account_new/docs`
- Configuração do MCP: `https://fineproxy.org/account_new/mcp`
- Especificação OpenAPI atual do cliente: baixe-a na documentação da API no painel do cliente.
- Criar e gerenciar chaves de API: `https://fineproxy.org/account_new/settings`
- Endpoint MCP: `https://fineproxy.org/account_new/api/v1/mcp`

Nunca invente um endpoint com base nesta visão geral. Use a especificação OpenAPI atual para consultar caminhos de solicitações, esquemas, parâmetros e respostas.

## Resumo da plataforma

- API REST: OpenAPI 3.1, 49 operações de cliente documentadas.
- MCP: 49 ferramentas por JSON-RPC 2.0 sem estado e Streamable HTTP.
- Autenticação: chaves de API bearer criadas no painel do cliente.
- A API e o MCP usam as mesmas permissões com escopo.
- A documentação da API de parceiros é visível somente para contas com status de parceiro ativo.

## Fluxos de trabalho compatíveis

### Compra e provisionamento

- Listar países e o estoque atual de IPs.
- Cotar um pacote exato com vários países sem realizar a compra.
- Comprar usando a carteira do painel, com proteção de preço e chave de idempotência.

A sequência padrão de compra pelo MCP é:

1. `list_countries`
2. `quote_composite`
3. `order_composite`

### Gerenciamento de serviços

- Consultar e gerenciar serviços.
- Renovar, suspender, restaurar ou cancelar quando houver compatibilidade.
- Ativar ou desativar a renovação automática.
- Substituir ou adicionar endereços IP.
- Alterar as credenciais do serviço.
- Consultar e gerenciar limites da lista de permitidos.
- Listar, comprar e cancelar complementos compatíveis.

### Análises e diagnósticos

- Visão geral de uso e séries temporais.
- Principais destinos.
- Categorias de erro.
- Recomendações operacionais.

### Cobrança e suporte

- Consultar faturas e baixar PDFs de faturas.
- Listar gateways de pagamento.
- Iniciar um depósito na carteira e consultar seu status.
- Criar, consultar, responder e encerrar chamados de suporte.

### Acesso ao proxy e à conta

- Consultar a configuração de conexão de proxies rotativos.
- Alterar o login e a senha do serviço.
- Gerenciar limites de conexão por IP na lista de permitidos.
- Consultar informações do perfil, IP do solicitante e histórico de login.
- Configurar webhooks.

## Escopos de permissão

- `customer:read` — consultar informações do cliente e da conta.
- `customer:write` — atualizar informações do cliente.
- `wallet:read` — consultar informações da carteira.
- `wallet:deposit` — criar e monitorar depósitos.
- `wallet:spend` — gastar fundos da carteira. Trate-o como uma permissão financeira.
- `services:read` — consultar serviços e configurações de proxy.
- `services:write` — criar ou modificar serviços e complementos.
- `tickets:read` — consultar chamados de suporte.
- `tickets:write` — criar, responder, atualizar ou encerrar chamados.
- `catalog:read` — consultar produtos, opções, países e estoque.
- `usage:read` — consultar uso e diagnósticos.
- `webhooks` — gerenciar assinaturas de webhook.

Inicie uma auditoria de migração com permissões somente leitura. Adicione permissões de gravação ou financeiras apenas depois que as alterações propostas forem revisadas.

## Comportamento de segurança

- As ferramentas financeiras exigem `wallet:spend`.
- As compras incluem o total esperado da cotação. Uma diferença de preço rejeita a operação.
- Operações irreversíveis exigem confirmação explícita.
- Novas tentativas financeiras usam uma chave de idempotência para que a mesma operação não seja cobrada duas vezes.
- O estoque atual, a elegibilidade do plano e as permissões da conta podem impedir uma operação que, de outra forma, seria válida.
- O MCP da FineProxy opera a conta do cliente. Ele não obtém acesso ao código-fonte, a menos que o usuário conceda separadamente ao agente de programação acesso a um repositório.

## Modelo de configuração do MCP

```json
{
  "mcpServers": {
    "fineproxy": {
      "url": "https://fineproxy.org/account_new/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer fb_YOUR_API_KEY"
      }
    }
  }
}
```

Armazene a chave real em uma variável de ambiente ou em um gerenciador de segredos. Não a inclua em um commit junto com a configuração do MCP.

## Checklist de compatibilidade da migração

Inspecione a integração existente em busca de:

1. Inicialização do cliente do provedor e todas as importações específicas do provedor.
2. Cabeçalhos de autenticação, credenciais, variáveis de ambiente e armazenamento de segredos.
3. Fluxos de compra, renovação, cancelamento e substituição de IP.
4. Identificadores de países e premissas de estoque.
5. Formatos de listas de proxies, protocolos, portas, nomes de usuário, senhas e inclusão de IPs na lista de permitidos.
6. Paginação e filtragem.
7. Comportamento de novas tentativas, tratamento de timeout e idempotência.
8. Modelos de erro e tratamento de limites.
9. Análises de uso e diagnósticos.
10. Cobrança, faturas e depósitos.
11. Integração com chamados de suporte.
12. Webhooks e premissas sobre payloads de eventos.
13. Testes, fixtures, mocks e segredos de CI vinculados ao provedor atual.

Classifique cada fluxo de trabalho como:

- Compatível sem alterações.
- Compatível por meio de uma alteração de configuração.
- Requer um adaptador ou transformação de dados.
- Requer um fluxo operacional diferente.
- Incompatível ou não confirmado pela documentação atual.

## Resultado obrigatório da auditoria

A auditoria deve incluir:

1. Um inventário de todas as dependências do provedor atual.
2. Uma avaliação de compatibilidade de cada fluxo de trabalho.
3. Escopos necessários da FineProxy.
4. Arquivos e caminhos de código exatos que seriam alterados.
5. Alterações de autenticação e gerenciamento de segredos.
6. Dúvidas que exigem a especificação OpenAPI atual ou confirmação do suporte.
7. Um plano de migração em etapas com reversão.
8. Testes de integração necessários antes da transição.

Não modifique o código durante a primeira etapa da auditoria.