REST API pubblica

1. Introduzione

L'API REST pubblica di Allega espone le risorse principali del sistema (pratiche, clienti, file) tramite endpoint HTTPS sotto il prefisso /api/v1. È pensata per integrazioni server-to-server: gestionali contabili, CRM, automazioni no-code, script di importazione dati.

Tutti gli endpoint:

• usano HTTPS obbligatorio (le richieste in chiaro sono rifiutate);
• accettano e restituiscono application/json; charset=utf-8;
• sono idempotenti per i metodi GET (safe to retry);
• sono tenant-isolati: ogni chiave appartiene a uno studio e vede solo i dati di quello studio. Non esiste alcuna modalità cross-tenant.

Le risposte includono un campo data per i dataset listati e una metadata di pagination. Gli errori usano l'envelope { error: { code, message } } .

2. Autenticazione

Ogni richiesta deve includere l'header Authorization: Bearer <chiave>. La chiave inizia con il prefisso ak_live_ seguito da 43 caratteri base64url (~256 bit di entropia).

curl -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://app.allega.it/api/v1/me

Generazione e gestione

1. Vai a Impostazioni → API keys nella dashboard.
2. Clicca Nuova chiave: scegli nome, scope e scadenza.
3. La chiave viene mostrata una sola volta. Copiala e archiviala in un password manager o nei segreti del CI. Non c'è recupero.
4. Per revocare una chiave: Impostazioni → API keys → Revoca. La revoca è immediata su tutti i nodi.

Storage server-side

Conserviamo solo l'hash SHA-256 della chiave. Il valore in chiaro non transita mai nei nostri log e non è recuperabile nemmeno dal team interno. La rotazione è raccomandata ogni 90 giorni per chiavi machine-to-machine.

Errori di autenticazione

3. Scope (permessi)

Le chiavi sono scopate: ogni chiave dichiara cosa può fare. Una chiave senza il giusto scope riceve 403 insufficient_scope. Scegli lo scope minimo necessario per la tua integrazione (principio di least-privilege).

4. Rate limiting

Limite per chiave: 120 richieste/minuto (sliding window). Superato il limite ricevi 429 rate_limited. Il limite è applicato server-side via Upstash Redis ed è indipendente dall'IP chiamante.

In caso di errore Redis (infrastruttura) il limite fail-open: l'API risponde comunque, ma scriviamo l'evento nel log interno. Non c'è SLA hard sul rate limiter — è una protezione anti-abuso, non un quality-of-service contract.

Per workload più alti contattaci: possiamo concordare limiti dedicati nel piano Pro o un bucket separato.

5. Versioning & deprecation

La versione è nel path: /api/v1/.... Manteniamo la retrocompatibilità all'interno della stessa versione major. Se introduciamo breaking changes pubblicheremo /api/v2 e manterremo v1 attiva per almeno 12 mesi dalla data di rilascio di v2, con un avviso nella dashboard e via email.

Sono considerate compatibili:

• nuovi campi opzionali nelle risposte;
• nuovi endpoint;
• nuovi valori in enum (i client devono ignorare valori sconosciuti).

Sono considerate breaking:

• rimozione di campi esistenti;
• cambio di tipo di un campo;
• cambio di significato di un campo (anche con stesso nome).

6. Errori

Tutti gli errori usano lo stesso envelope JSON, con codici stabili sotto error.code:

{
  "error": {
    "code": "insufficient_scope",
    "message": "Missing required scope: write:clients"
  }
}

Il campo message è in inglese, sicuro da mostrare per debug interno ma non destinato all'utente finale (può cambiare). Discrimina sempre sul code stabile.

Codici comuni

7. Paginazione

Tutti gli endpoint GET /api/v1/... che restituiscono liste supportano paginazione con offset/limit:

• limit: 1..100 (default 50)
• offset: 0..N (default 0)

La risposta include un blocco pagination con il totale assoluto:

{
  "data": [ ... ],
  "pagination": { "limit": 50, "offset": 0, "total": 287 }
}

Per dataset grandi raccomandiamo di iterare con offset += limitfinché offset < total. L'ordinamento è updated_at DESC stabile.

8. Endpoints

curl -H "Authorization: Bearer $ALLEGA_KEY" https://app.allega.it/api/v1/me

{
  "studio": {
    "id": "f8a1...",
    "name": "Studio Rossi & Associati",
    "slug": "studio-rossi",
    "plan": "studio",
    "timezone": "Europe/Rome",
    "defaultLocale": "it"
  },
  "apiKey": {
    "id": "9d3e...",
    "scopes": ["read:practices", "read:clients"]
  }
}

curl -H "Authorization: Bearer $ALLEGA_KEY" \
  "https://app.allega.it/api/v1/practices?status=active&limit=20"

{
  "data": [
    {
      "id": "7c1e...",
      "name": "Bilancio 2025",
      "description": null,
      "status": "active",
      "client": {
        "id": "a4f2...",
        "name": "Mario Rossi",
        "email": "mario@example.com"
      },
      "shareUrl": "https://app.allega.it/p/AbCdEf1234...",
      "shareExpiresAt": "2026-08-01T00:00:00.000Z",
      "shareOpenedAt": "2026-05-03T14:22:11.000Z",
      "dueDate": "2026-06-30T00:00:00.000Z",
      "completedAt": null,
      "createdAt": "2026-05-01T09:00:00.000Z",
      "updatedAt": "2026-05-03T14:22:11.000Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 87 }
}

curl -H "Authorization: Bearer $ALLEGA_KEY" \
  https://app.allega.it/api/v1/practices/7c1e3a4b-...

{
  "id": "7c1e...",
  "name": "Bilancio 2025",
  "status": "active",
  "client": { "id": "a4f2...", "name": "Mario Rossi", "email": "..." },
  "shareUrl": "https://app.allega.it/p/AbCdEf1234...",
  "shareSubmittedAt": null,
  "items": [
    {
      "id": "1aa2...",
      "name": "CCIAA visura aggiornata",
      "category": "anagrafica",
      "required": true,
      "multiFile": false,
      "acceptedFormats": ["pdf"],
      "maxFileSizeMb": 25,
      "status": "approved",
      "approvedAt": "2026-05-02T10:11:00.000Z",
      "rejectedAt": null,
      "order": 1
    }
  ]
}

curl -X POST \
  -H "Authorization: Bearer $ALLEGA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "a4f2-...",
    "presetId": "55ee-...",
    "name": "Bilancio 2025",
    "dueDate": "2026-06-30T23:59:00.000Z"
  }' \
  https://app.allega.it/api/v1/practices

{
  "id": "7c1e...",
  "name": "Bilancio 2025",
  "status": "draft",
  "clientId": "a4f2-...",
  "shareUrl": "https://app.allega.it/p/AbCdEf1234...",
  "shareExpiresAt": "2026-06-30T23:59:00.000Z",
  "dueDate": "2026-06-30T23:59:00.000Z",
  "createdAt": "2026-05-04T..."
}

curl -X POST \
  -H "Authorization: Bearer $ALLEGA_KEY" \
  https://app.allega.it/api/v1/practices/7c1e.../send

{
  "id": "7c1e...",
  "status": "active",
  "shareUrl": "https://app.allega.it/p/AbCdEf1234..."
}

curl -H "Authorization: Bearer $ALLEGA_KEY" \
  "https://app.allega.it/api/v1/clients?q=rossi"

{
  "data": [
    {
      "id": "a4f2...",
      "name": "Mario Rossi",
      "email": "mario@example.com",
      "phone": "+39 333 1234567",
      "fiscalCode": "RSSMRA80A01H501Z",
      "tags": ["azienda", "iva"],
      "preferredChannel": "email",
      "archived": false,
      "createdAt": "2026-01-15T...",
      "updatedAt": "2026-05-03T..."
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total": 12 }
}

curl -X POST \
  -H "Authorization: Bearer $ALLEGA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Anna Bianchi",
    "email": "anna@example.com",
    "phone": "+39 348 7654321",
    "fiscalCode": "BNCNNA85B41F205X",
    "tags": ["azienda"],
    "preferredChannel": "whatsapp"
  }' \
  https://app.allega.it/api/v1/clients

{
  "id": "f1e2...",
  "name": "Anna Bianchi",
  "email": "anna@example.com",
  "phone": "+39 348 7654321",
  "fiscalCode": "BNCNNA85B41F205X",
  "tags": ["azienda"],
  "preferredChannel": "whatsapp",
  "archived": false,
  "createdAt": "2026-05-04T...",
  "updatedAt": "2026-05-04T..."
}

curl -H "Authorization: Bearer $ALLEGA_KEY" \
  https://app.allega.it/api/v1/clients/a4f2...

curl -X PATCH \
  -H "Authorization: Bearer $ALLEGA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+39 333 9999999", "tags": ["vip", "azienda"] }' \
  https://app.allega.it/api/v1/clients/a4f2...

{
  "id": "a4f2...",
  "name": "Mario Rossi",
  "email": "mario@example.com",
  "phone": "+39 333 9999999",
  "tags": ["vip", "azienda"],
  "preferredChannel": "email",
  "archived": false,
  "updatedAt": "2026-05-04T..."
}

curl -H "Authorization: Bearer $ALLEGA_KEY" \
  https://app.allega.it/api/v1/files/d3c4.../download

{
  "id": "d3c4...",
  "originalName": "F24_2026Q1.pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 245128,
  "sha256": "9f86d081884c7d659a2feaa0...",
  "scanStatus": "clean",
  "uploadedAt": "2026-05-03T...",
  "downloadUrl": "https://r2.allega.it/...?X-Amz-Signature=...",
  "downloadUrlExpiresInSec": 300
}

9. Webhooks (in arrivo)

I webhook in uscita per eventi practice.completed, file.uploaded, file.approved, file.rejected sono in roadmap Q3 2026. Per ora puoi pollare /api/v1/practices con un cursor su updatedAt.

Vuoi accesso anticipato? Scrivi a api@allega.it.

10. Esempi completi

Node.js (fetch nativo)

const KEY = process.env.ALLEGA_API_KEY;
const BASE = 'https://app.allega.it/api/v1';

async function listActivePractices() {
  const res = await fetch(`${BASE}/practices?status=active&limit=100`, {
    headers: { Authorization: `Bearer ${KEY}` },
  });
  if (!res.ok) {
    const err = await res.json();
    throw new Error(`${err.error.code}: ${err.error.message}`);
  }
  const { data, pagination } = await res.json();
  console.log(`Found ${pagination.total} active practices`);
  return data;
}

listActivePractices().then((rows) => console.table(rows));

Python (requests)

import os, requests

KEY = os.environ['ALLEGA_API_KEY']
BASE = 'https://app.allega.it/api/v1'

r = requests.get(
    f'{BASE}/clients',
    headers={'Authorization': f'Bearer {KEY}'},
    params={'q': 'rossi', 'limit': 50},
    timeout=10,
)
r.raise_for_status()
for c in r.json()['data']:
    print(c['name'], c['email'])

Zapier / n8n

Usa il nodo HTTP Request:

• URL: https://app.allega.it/api/v1/...
• Authentication: Header Authorization = Bearer ak_live_xxx
• Response Format: JSON

11. Security best practice

• Genera una chiave per ogni integrazione. Non riusare la stessa chiave per Zapier e per uno script CI: se una è compromessa, le revoche separatamente.
• Usa il minimo scope necessario. Una chiave per export documenti vuole solo read:practices read:files, non write:clients.
• Imposta una expiresAt ≤ 90 giorni e ruota le chiavi periodicamente.
• Conserva le chiavi in un password manager (1Password, Bitwarden) o nei segreti del CI (GitHub Actions secrets, Vercel env). Mai in repository git, anche privati.
• Se sospetti compromissione: revoca immediatamente dalla dashboard, controlla l'Audit log per tracciare le richieste, genera una nuova chiave.
• Implementa retry con backoff esponenziale per 429 e 5xx. Per 4xx diversi da 429 il retry è inutile (è un bug del chiamante).

12. Changelog

• v1.0 (2026-05) — Release iniziale. Endpoints: /me, /practices, /practices/{id}, /clients, /clients/{id}, /files/{id}/download.