# FineProxy Agent Pack

Versione: 2026-09-22

Utilizzate questo file per valutare se un’integrazione proxy esistente può migrare a FineProxy. Non contiene chiavi API, dati dell’account o endpoint privati.

## Fonti ufficiali

- Documentazione API client interattiva: `https://fineproxy.org/account_new/docs`
- Configurazione MCP: `https://fineproxy.org/account_new/mcp`
- Specifica OpenAPI client corrente: scaricatela dalla documentazione API nella dashboard cliente.
- Creazione e gestione delle chiavi API: `https://fineproxy.org/account_new/settings`
- Endpoint MCP: `https://fineproxy.org/account_new/api/v1/mcp`

Non inventate mai un endpoint sulla base di questa panoramica. Utilizzate la specifica OpenAPI corrente per percorsi delle richieste, schemi, parametri e risposte.

## Panoramica della piattaforma

- REST API: OpenAPI 3.1, 49 operazioni cliente documentate.
- MCP: 49 strumenti tramite JSON-RPC 2.0 senza stato e Streamable HTTP.
- Autenticazione: chiavi API bearer create nella dashboard cliente.
- API e MCP utilizzano le stesse autorizzazioni con ambiti.
- La documentazione API partner è visibile soltanto agli account con stato di partner attivo.

## Workflow supportati

### Acquisto e provisioning

- Elencare i Paesi e l’inventario IP disponibile.
- Calcolare il preventivo di un pacchetto multi-Paese esatto senza acquistarlo.
- Acquistare dal portafoglio della dashboard con un limite di prezzo e una chiave di idempotenza.

La sequenza di acquisto MCP standard è:

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

### Gestione dei servizi

- Leggere e gestire i servizi.
- Rinnovare, sospendere, ripristinare o annullare, se supportato.
- Abilitare o disabilitare il rinnovo automatico.
- Sostituire o aggiungere indirizzi IP.
- Modificare le credenziali del servizio.
- Leggere e gestire i limiti dell’allowlist.
- Elencare, acquistare e annullare componenti aggiuntivi compatibili.

### Analisi e diagnostica

- Panoramica e serie temporali sull’utilizzo.
- Principali destinazioni.
- Categorie di errore.
- Raccomandazioni operative.

### Fatturazione e assistenza

- Leggere le fatture e scaricarle in PDF.
- Elencare i gateway di pagamento.
- Avviare un deposito nel portafoglio e leggerne lo stato.
- Creare, leggere, rispondere e chiudere ticket di assistenza.

### Accesso proxy e account

- Leggere la configurazione di connessione dei proxy a rotazione.
- Modificare login e password del servizio.
- Gestire i limiti di connessione per IP nell’allowlist.
- Leggere informazioni del profilo, IP del chiamante e cronologia degli accessi.
- Configurare i webhook.

## Ambiti di autorizzazione

- `customer:read` — leggere le informazioni del cliente e dell’account.
- `customer:write` — aggiornare le informazioni del cliente.
- `wallet:read` — leggere le informazioni del portafoglio.
- `wallet:deposit` — creare e monitorare depositi.
- `wallet:spend` — spendere i fondi del portafoglio. Consideratelo un’autorizzazione finanziaria.
- `services:read` — leggere servizi e impostazioni proxy.
- `services:write` — creare o modificare servizi e componenti aggiuntivi.
- `tickets:read` — leggere i ticket di assistenza.
- `tickets:write` — creare, aggiornare, rispondere o chiudere ticket.
- `catalog:read` — leggere prodotti, opzioni, Paesi e inventario.
- `usage:read` — leggere dati sull’utilizzo e diagnostica.
- `webhooks` — gestire le sottoscrizioni webhook.

Iniziate un audit di migrazione con autorizzazioni di sola lettura. Aggiungete autorizzazioni in scrittura o finanziarie soltanto dopo aver esaminato le modifiche proposte.

## Comportamento di sicurezza

- Gli strumenti finanziari richiedono `wallet:spend`.
- Gli acquisti includono il totale previsto indicato nel preventivo. Se il prezzo non corrisponde, l’operazione viene rifiutata.
- Le operazioni irreversibili richiedono una conferma esplicita.
- I nuovi tentativi di operazioni finanziarie utilizzano una chiave di idempotenza, affinché la stessa operazione non venga addebitata due volte.
- L’inventario corrente, l’idoneità del piano e le autorizzazioni dell’account possono impedire un’operazione altrimenti valida.
- FineProxy MCP opera sull’account cliente. Non ottiene accesso al codice sorgente, a meno che l’utente non conceda separatamente all’agente di programmazione l’accesso a un repository.

## Modello di configurazione MCP

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

Conservate la chiave reale in una variabile d’ambiente o in un gestore di secret. Non sottoponetela a commit insieme alla configurazione MCP.

## Checklist di compatibilità per la migrazione

Esaminate l’integrazione esistente per individuare:

1. Inizializzazione del client del provider e tutte le importazioni specifiche del provider.
2. Header di autenticazione, credenziali, variabili d’ambiente e archiviazione dei secret.
3. Workflow di acquisto, rinnovo, annullamento e sostituzione degli IP.
4. Identificatori dei Paesi e presupposti sull’inventario.
5. Formati degli elenchi proxy, protocolli, porte, nomi utente, password e allowlist IP.
6. Paginazione e filtri.
7. Gestione di nuovi tentativi, timeout e idempotenza.
8. Modelli di errore e gestione dei limiti di frequenza.
9. Analisi dell’utilizzo e diagnostica.
10. Fatturazione, fatture e depositi.
11. Integrazione con i ticket di assistenza.
12. Webhook e presupposti sui payload degli eventi.
13. Test, fixture, mock e secret CI legati al provider corrente.

Classificate ogni workflow come:

- Compatibile senza modifiche.
- Compatibile tramite una modifica della configurazione.
- Richiede un adattatore o una trasformazione dei dati.
- Richiede un workflow operativo diverso.
- Non supportato o non confermato dalla documentazione corrente.

## Output richiesto per l’audit

L’audit deve includere:

1. Un inventario di tutte le dipendenze dal provider corrente.
2. Una valutazione della compatibilità workflow per workflow.
3. Gli ambiti FineProxy necessari.
4. I file e i percorsi del codice esatti da modificare.
5. Le modifiche all’autenticazione e alla gestione dei secret.
6. Le questioni aperte che richiedono la specifica OpenAPI corrente o una conferma dell’assistenza.
7. Un piano di migrazione per fasi con rollback.
8. I test di integrazione necessari prima del passaggio definitivo.

Non modificate il codice durante la prima fase dell’audit.