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 consegnano gli eventi in modo asincrono, mentre le API ti permettono di leggere e scrivere on-demand.

Cosa puoi fare

Versione attuale: v1.

Risorsa	Operazioni
Contatti	Lista paginata, dettaglio, creazione e modifica; un'email duplicata restituisce 409
Invii email (sends)	Stato corrente degli invii, in ordine di creazione, con cursore since
Campagne	Dettaglio singola campagna con statistiche

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; le risposte riuscite e il 429 riportano gli header x-ratelimit-*.
• Paginazione — basata su created_at per lista contatti e invii email.
• Duplicati — POST /contacts non sovrascrive il contatto esistente: restituisce 409 con il suo identificativo.
• Errori — corpo JSON standard { error: { code, message } }.

Quando usare le API e quando i webhook

Scenario	Strumento giusto
Il sistema esterno sa già quando deve agire, per esempio con un processo notturno	API
Il sistema esterno vuole ricevere una notifica asincrona senza interrogare continuamente SmartCQ	Webhook
Caricamento iniziale di un CRM esterno con tutti i contatti SmartCQ	API con paginazione
Sincronizzazione periodica dello stato email	Webhook più API per la riconciliazione

Spesso si usano insieme: i webhook notificano gli eventi nella finestra giornaliera di elaborazione, mentre le API servono per il caricamento iniziale e la riconciliazione periodica.