API REST pubblica

Reference dell'API REST di SmartCQ per leggere e scrivere dati del proprio tenant da un sistema esterno.

L'API REST pubblica di SmartCQ ti permette di leggere e scrivere i dati del tuo tenant (contatti, eventi email, campagne) da un sistema esterno: un CRM, un gestionale custom, uno script di import notturno, una dashboard di reportistica.

È il complemento naturale dei webhook: i webhook spingono fuori gli eventi appena succedono, le API ti permettono di leggere e scrivere on-demand.

Cosa puoi fare

Versione attuale: v1.

Risorsa	Operazioni
Contatti	Lista paginata, dettaglio, creazione (idempotente per email), modifica
Eventi email (`sends`)	Lista paginata in ordine cronologico ascendente con cursor `since`
Campagne	Dettaglio singola campagna con statistiche

CRM, Pratica, Documenti — i moduli arriveranno in versioni future con scope dedicati.

Base URL

https://app.smartcq.it/api/v1

Nota — Tutte le richieste vanno verso app.smartcq.it, non smartcq.it (che è solo la landing pubblica).

Quick start

# 1. Genera una API key da Impostazioni → API Keys nel pannello SmartCQ
#    (la chiave inizia con `scq_` ed è mostrata UNA SOLA VOLTA)

# 2. Esporta la chiave nel tuo shell
export SMARTCQ_KEY="scq_a1b2c3..."

# 3. Lista i tuoi contatti
curl -s -H "Authorization: Bearer $SMARTCQ_KEY" \
  "https://app.smartcq.it/api/v1/contacts?limit=10" | jq

# 4. Crea un nuovo contatto
curl -s -X POST \
  -H "Authorization: Bearer $SMARTCQ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"mario.rossi@example.com","firstName":"Mario","lastName":"Rossi"}' \
  "https://app.smartcq.it/api/v1/contacts"

Spec OpenAPI

La specifica completa in formato OpenAPI 3.1 è servita all'endpoint:

GET https://app.smartcq.it/api/v1/openapi.json

Puoi importarla direttamente in Postman, Insomnia, oppure usarla per generare un client TypeScript / Python / Go automaticamente.

Concetti chiave

Autenticazione — header Authorization: Bearer scq_<chiave>, scope per limitare i permessi.
Rate limit — 60 richieste/minuto per chiave (header x-ratelimit-* su ogni risposta).
Pagination — cursor-based su created_at (lista contatti, eventi email).
Idempotency — POST /contacts è idempotente per email: stesso payload → stesso contatto, mai duplicati.
Errori — corpo JSON standard { error: { code, message } }.

Quando usare le API e quando i webhook

Scenario	Strumento giusto
Il consumer sa già "quando" deve agire (job notturno, polling cron)	API
Il consumer deve reagire in tempo reale a eventi imprevedibili (bounce, unsubscribe)	Webhook
Backfill iniziale di un CRM esterno con tutti i contatti SmartCQ	API (cursor pagination)
Sincronizzazione continua dello stato email	Webhook + API per riconciliazione periodica

Spesso si usano insieme: i webhook per la reattività, le API per backfill e auditing.