API REST pubblica per integrazioni CRM

API key per-tenant in `Impostazioni → API Keys`: genera chiavi dedicate per ogni integrazione esterna (CRM, gestionale, script). Scope granulari, secret HMAC mostrato solo alla creazione, prefisso pubblico (`scq_a1b2c3…`) per identificare la chiave in lista senza esporre il plaintext.

Endpoint contatti v1: `GET /api/v1/contacts` (lista paginata con cursor, filtri per stato email, stage, archiviati), `GET /:id` (dettaglio), `POST` (creazione idempotente per email), `PATCH /:id` (modifica). Schema completo nei docs.

Endpoint eventi email v1: `GET /api/v1/sends` con cursor `since` per polling incrementale — il consumer salva l'ultimo `next` e riceve solo gli eventi nuovi. Filtri per `campaignId` e `status`. Pensato per backfill iniziale di un CRM esterno o riconciliazione periodica.

Endpoint campagna v1: `GET /api/v1/campaigns/:id` con statistiche cumulate (sent, delivered, opened, clicked, bounced).

Spec OpenAPI 3.1 servita su `/api/v1/openapi.json` (no auth — è documentazione pubblica). Importabile in Postman, Insomnia, oppure usabile per generare client TypeScript / Python / Go automatici.

Documentazione developer dedicata su `smartcq.it/docs/api`: introduzione, autenticazione, endpoint contacts/sends/campaigns con esempi cURL + Node.js + Python, tabella errori e codici HTTP.

Rate limit per chiave: 60 richieste/minuto con header standard `x-ratelimit-limit`/`-remaining`/`-reset` su ogni risposta. Sopra il limite → `429 Too Many Requests` con `Retry-After`.

Audit trail API keys: ogni operazione (creazione, revoca, eliminazione) finisce nel registro attività del tenant. La chiave revocata è rifiutata immediatamente dagli endpoint con `401 invalid_key`.