# API Integration

> Integrazione API REST e webhook per PMI italiane: connessione gestionali (TeamSystem, Zucchetti, Mago4, Fatture in Cloud), automazione flussi con n8n/Make, mappatura endpoint, gestione autenticazione OAuth2/API key.

- Skill: `gigik2a/api-integration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gigik2a/api-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gigik2a/api-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: gigik2a (https://skillmd.com/u/gigik2a)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gigik2a/api-integration

---


# Integrazione API — Gestionali e Servizi Italiani

## Gestionali italiani più diffusi — stato API

| Gestionale | API | Formato | Note |
|------------|-----|---------|------|
| **Fatture in Cloud** | REST (v2) | JSON | OAuth2, sandbox disponibile |
| **TeamSystem** | REST | JSON/XML | Richiede accordo commerciale |
| **Zucchetti** | SOAP/REST | XML/JSON | Legacy SOAP + nuove API REST |
| **Mago4 / Mago Next** | REST | JSON | Micronauta middleware |
| **Danea Easyfatt** | No API native | CSV export | Solo import/export file |
| **QuiCredit / GestPay** | REST | JSON | Solo pagamenti |
| **Aruba Fatturazione** | REST | JSON | Semplice, buona docs |

## Fatture in Cloud — endpoint principali

```
GET    /v2/companies/{company_id}/issued_documents    → fatture emesse
POST   /v2/companies/{company_id}/issued_documents    → crea fattura
GET    /v2/companies/{company_id}/received_documents  → fatture ricevute
GET    /v2/companies/{company_id}/clients             → anagrafica clienti
POST   /v2/companies/{company_id}/clients             → crea cliente
GET    /v2/companies/{company_id}/products            → listino prodotti
```

Auth: Bearer token OAuth2. Scopes: `issued_documents:r`, `issued_documents:e`, `entities.clients:rw`.

## Pattern integrazione standard

### Webhook → azione
```
Evento esterno (fattura pagata, form compilato)
  → webhook POST a endpoint n8n/Make
  → validazione payload (header HMAC sha256)
  → trasformazione dati
  → scrittura su DB / invio email / update CRM
```

### Polling pianificato
```
Cron ogni 15min
  → GET /issued_documents?filter[payment_date]≥{ieri}
  → diff con stato locale
  → elabora nuovi/modificati
  → aggiorna stato interno
```

### Autenticazione OAuth2 flow per app server-side
```
1. Redirect utente a /oauth/authorize?client_id=...&scope=...
2. Callback riceve code
3. POST /oauth/token con code → access_token + refresh_token
4. Salva refresh_token (scade mai), access_token (scade 1h)
5. Prima di ogni call: se access_token scaduto → refresh
```

## n8n — nodi utili per PMI

| Nodo | Use case |
|------|----------|
| HTTP Request | Chiama qualsiasi REST API |
| Webhook | Riceve eventi push |
| Cron | Scheduling automatico |
| Google Sheets | Leggi/scrivi fogli (CRM leggero) |
| Airtable | Sync database operativo |
| Gmail/Resend | Notifiche email |
| Supabase | Query/insert su DB PostgreSQL |
| Code (JS) | Trasformazioni dati custom |
| Split in Batches | Elabora array grandi |
| Error Trigger | Notifica errori workflow |

## Gestione errori API

| Errore HTTP | Significato | Azione |
|-------------|-------------|--------|
| 400 Bad Request | Payload malformato | Logga body inviato, correggi schema |
| 401 Unauthorized | Token scaduto/errato | Refresh token o reinizializza OAuth |
| 403 Forbidden | Scope insufficiente | Richiedi scope corretto |
| 404 Not Found | Risorsa non esiste | Verifica ID, non propagare errore |
| 429 Too Many Requests | Rate limit | Backoff esponenziale: 1s, 2s, 4s... |
| 500 Server Error | Errore lato API | Retry 3x poi alert |

## Mappatura dati — checklist

Prima di ogni integrazione documentare:
- [ ] Endpoint sorgente + autenticazione
- [ ] Schema campo per campo (fonte → destinazione)
- [ ] Trasformazioni (formati data, codifiche moneta, IVA)
- [ ] Gestione valori null/vuoti
- [ ] ID univoci per deduplication
- [ ] Frequenza sync (real-time/polling/batch)
- [ ] Rollback in caso di errore parziale

## Fatturazione elettronica SDI — integrazione

Per inviare/ricevere fatture SDI senza gestionale:
- **Aruba Sign/FatturAziende**: API REST, 0.025€/fattura
- **Fattura24/Invoicex**: API JSON semplice
- Formato: XML FatturaPA, namespace `http://ivaservizi.agenziaentrate.gov.it/docs/xsd/fatture/v1.2`
- Canali: PEC o Codice Destinatario (7 caratteri)
- Conservazione sostitutiva: obbligatoria 10 anni

## Sicurezza API

- Secrets mai in codice: usa env vars o vault (Supabase Vault, Railway env)
- Valida sempre HMAC dei webhook prima di elaborare
- Rate limit su endpoint esposti (max 100 req/min per IP)
- Log tutte le chiamate con timestamp, status, latenza
- Ruota API key ogni 90 giorni per servizi critici