Sviluppatori
Frihet espone un'API REST completa, un sistema di webhook e un server MCP per integrare il tuo ERP con qualsiasi strumento. Automatizza i flussi di lavoro, sincronizza i dati con i tuoi sistemi esistenti o costruisci integrazioni personalizzate. Consulta tutte le funzionalità di Frihet e le integrazioni disponibili.
Risorse principali
API REST
API RESTful con autenticazione tramite chiave API. Accedi a fatture, spese, clienti, prodotti, preventivi e fornitori in modo programmatico.
- Endpoint CRUD completi per 6 risorse (POST, GET, PUT/PATCH, DELETE)
- Filtraggio per stato, intervallo di date e paginazione
- Dashboard finanziaria (
/summary) con entrate, spese e profitto - Azioni speciali: scaricare PDF, inviare via email, marcare come pagata
- Limite di 100 richieste/minuto per chiave
- Risposte JSON standardizzate con validazione rigorosa (Zod)
Webhooks
Ricevi notifiche in tempo reale quando si verificano eventi nel tuo account Frihet. 14 tipi di evento con firma HMAC-SHA256 per verificare l'autenticità di ogni payload.
- 14 tipi di evento (fatture, spese, preventivi, clienti, prodotti)
- Firma crittografica ad ogni consegna
- Ritentativi automatici con backoff esponenziale
- Log di consegna consultabili dal pannello
Server MCP
Server MCP ufficiale pubblicato su npm come @frihet/mcp-server (v1.5.1), registrato come io.frihet/erp nel MCP Registry. 52 strumenti per integrare Frihet con assistenti AI (Claude, Cursor, Windsurf).
- 52 strumenti, 11 risorse, 10 prompt (fatture, spese, clienti, prodotti, preventivi, fornitori, webhook)
- Trasporto locale (stdio) e remoto (mcp.frihet.io)
- Logging strutturato, metriche per strumento, rate-limit retry automatico
- Autenticazione tramite chiave API o flusso OAuth
- Open source (MIT) su GitHub
Skill per Claude Code
Skill ufficiale che aggiunge intelligenza di business sul server MCP. Comandi conversazionali, contesto fiscale spagnolo, ricette di flussi di lavoro e formattazione di rapporti.
- Comandi:
/frihet invoice,/frihet expense,/frihet report,/frihet clients - Preparazione automatica del Modello 303 (IVA trimestrale)
- Chiusura mensile, monitoraggio dei morosi, conversione preventivo-fattura
- Installazione:
npx skills add Frihet-io/frihet-mcp
Integrazioni supportate
Frihet si connette in modo nativo con i seguenti strumenti. Ogni integrazione può essere integrata con l'API REST e i webhook per coprire casi d'uso avanzati.
| Categoria | Servizio | Descrizione |
|---|---|---|
| Pagamenti | Stripe | Abbonamenti e incassi da clienti tramite Stripe Billing |
| Pagamenti | Stripe Connect | Link di pagamento per fatture con carta, Apple Pay e Google Pay |
| Pagamenti | PayPal | Importazione di transazioni e saldi tramite API REST v2 con OAuth2 |
| Pagamenti | GoCardless | Incassi tramite addebito diretto SEPA, mandati e pagamenti ricorrenti |
| Banca | Revolut Business | Importazione automatica di transazioni tramite chiave API |
| Banca | Plaid | Connessione bancaria diretta tramite Plaid Link SDK per transazioni e saldi |
| Banca | Open Banking | Connessione PSD2 con Salt Edge per la sincronizzazione bancaria |
| E-commerce | Shopify | Importazione di ordini e sincronizzazione di prodotti tramite OAuth |
| E-commerce | WooCommerce | Sincronizzazione bidirezionale di ordini e prodotti tramite webhooks |
| E-commerce | Gumroad | Importazione di vendite di prodotti digitali con prefisso GR- e deduplicazione |
| E-commerce | Lemon Squeezy | Importazione di ordini di software digitale tramite JSON:API |
| Time tracking | Toggl | Importazione di registrazioni di tempo per la fatturazione a ore |
| Time tracking | Clockify | Sincronizzazione di progetti e registrazioni di tempo |
| Time tracking | Harvest | Importazione di ore con Personal Access Token e Account ID |
| Produttività | Asana | Consultazione di progetti e attività con rilevamento automatico del workspace |
| Produttività | Trello | Accesso a bacheche, liste e schede per il contesto del progetto |
| Produttività | Notion | Ricerca di pagine, database e registrazioni del workspace |
| Calendario | Google Calendar | Promemoria di scadenza ed eventi di fatturazione |
| Calendario | Outlook Calendar | Eventi e scadenze tramite Microsoft Graph API con OAuth |
| Archiviazione | Google Drive | Caricare, scaricare e cercare file tramite OAuth |
| Comunicazione | Slack | Notifiche di fatture pagate, spese registrate e avvisi |
| Resend | Invio di fatture via email con modelli transazionali | |
| Automazione | n8n | Connessione tramite webhooks per flussi di automazione personalizzati |
| Automazione | Zapier | Connessione con oltre 6.000 app senza codice tramite webhooks |
| Automazione | Make | Automazione visuale con centinaia di app tramite webhooks |
Sicurezza
La sicurezza è una priorità in tutta la capa di integrazioni di Frihet.
- Crittografia AES-256-GCM per dati sensibili archiviati (token di integrazione, segreti di webhook)
- HMAC-SHA256 ad ogni consegna di webhook per verificare l'autenticità del payload
- Hashing SHA-256 delle chiavi API sul server -- la chiave in testo semplice viene mostrata solo una volta alla creazione
- Validazione del formato delle chiavi API prima di elaborarle (prefisso
fri_, lunghezza 40-60 caratteri, charset ristretto) - Rate limiting di 100 richieste al minuto per chiave API, supportato da Firestore (resiste a cold start)
- Validazione rigorosa dei dati con Zod — i campi sconosciuti vengono rifiutati
- Validazione dell'URL nei webhook: sono consentiti solo endpoint HTTPS (eccetto localhost in sviluppo)
- Blocco di IP privati per evitare SSRF negli URL dei webhook
- Validazione degli ID dei documenti per prevenire path traversal e iniezione
- Token con scadenza configurabile -- puoi creare chiavi con data di scadenza
- Header di sicurezza in tutte le risposte:
X-Content-Type-Options,X-Frame-Options,X-XSS-Protection
SDK e CLI
SDK ufficiali per integrare Frihet nel tuo stack:
| Pacchetto | Installazione | Descrizione |
|---|---|---|
@frihet/sdk | npm i @frihet/sdk | SDK TypeScript — frihet.invoices.create(), tipi completi, retry automatico |
frihet | npm i -g frihet | CLI — frihet invoices list --status overdue |
| Python | Prossimamente | In sviluppo |
import Frihet from '@frihet/sdk';
const frihet = new Frihet({ apiKey: 'fri_...' });
const invoice = await frihet.invoices.create({
clientName: 'Acme Corp',
items: [{ description: 'Consulting', quantity: 10, unitPrice: 150 }],
});
Repository: github.com/Frihet-io/frihet-sdk
Limiti e quote
| Risorsa | Limite |
|---|---|
| Richieste API | 100/minuto per chiave |
| Dimensione della richiesta | 1 MB massimo |
| Offset massimo | 10.000 |
| Dimensione del payload del webhook | 100 KB massimo |
| Webhook per account | 20 massimo |
| Ritentativi del webhook | 3 tentativi per consegna |
| Risultati per pagina | 100 massimo (50 per default) |
| Chiavi API attive per utente | 5 massimo (tramite OAuth) |
Primi passi
- Accedi a Impostazioni > Sviluppatori > API Keys nel tuo account Frihet
- Crea una nuova chiave API e copia la chiave (viene mostrata solo una volta)
- Testa la connessione con una richiesta GET a
/v1/clients - Configura i webhook per ricevere eventi in tempo reale
curl -s https://api.frihet.io/v1/clients \
-H "X-API-Key: fri_tu-clave-aqui" | head -c 200
Se la risposta include i tuoi clienti, l'integrazione sta funzionando. Consulta la documentazione dell'API REST per vedere tutti gli endpoint disponibili.