API Mosaqo per sviluppatori

Un’API REST sullo stesso spazio di lavoro che usi nell’app. Tutto quello che segue funziona con una sola chiave API e un qualsiasi client HTTP.

Cosa puoi fare

Creare codici QR dai tuoi record: uno alla volta o diecimila da un CSV.
Cambiare la destinazione di un codice già stampato, con una chiamata e senza ristampare nulla.
Scaricare la card finita in PNG, SVG o PDF e allegarla a una scheda del CRM.
Leggere scansioni e analitiche aggregate, filtrate dalle regole di privacy del tuo spazio.
Ricevere webhook firmati quando un codice viene creato, pubblicato, modificato o archiviato.

Avvio rapido

Crea una chiave in Bulk & API nel tuo spazio, seleziona gli scope qr:write e qr:read e copia il secret: viene mostrato una volta sola.

Verifica la chiave e scopri quale spazio apre:

curl https://api.mosaqo.app/v1/public-api/me \
  -H "Authorization: Bearer $MOSAQO_KEY"

Crea un codice QR dinamico:

curl -X POST https://api.mosaqo.app/v1/public-api/qr \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Autumn campaign",
    "mode": "dynamic",
    "contentType": "url",
    "content": { "targetUrl": "https://example.com/autumn" }
  }'

Pubblicalo — è questo che attiva il reindirizzamento — e poi recupera l’immagine da stampare:

curl -X POST https://api.mosaqo.app/v1/public-api/qr/$QR_ID/publish \
  -H "Authorization: Bearer $MOSAQO_KEY"

curl https://api.mosaqo.app/v1/public-api/qr/$QR_ID/image?format=png&size=2048 \
  -H "Authorization: Bearer $MOSAQO_KEY" -o campaign.png

Mesi dopo, quando la campagna cambia, riorienta lo stesso codice stampato senza ristamparlo:

curl -X POST https://api.mosaqo.app/v1/public-api/qr/$QR_ID/destination \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/winter" }'

Autenticazione

Invia il secret in uno dei due modi. Entrambi valgono per tutta la v1.

Authorization: Bearer mosaqo_xxx
X-Mosaqo-API-Key: mosaqo_xxx

Una chiave appartiene a un solo spazio di lavoro, quindi i percorsi non hanno bisogno dell’identificativo dello spazio: basta /v1/public-api/qr. La forma precedente /v1/public-api/workspaces/{workspaceId}/qr funziona ancora.

Scope	Consente
`qr:read`	Elencare e leggere codici QR, cartelle e modelli
`qr:write`	Creare, modificare, riorientare, pubblicare, archiviare ed eliminare
`exports:read`	Scaricare le card renderizzate
`analytics:read`	Analitiche aggregate e singole scansioni
`bulk:write`	Creare e leggere job in blocco
`webhooks:write`	Gestire le sottoscrizioni ai webhook

Le chiavi si possono revocare, far scadere e limitare a un elenco di IP consentiti. Se è quell’elenco a rifiutare la chiave, lo diciamo esplicitamente invece di farla sembrare non valida.

Paginazione

Gli elenchi usano la paginazione a chiave. Rimanda pagination.nextCursor invariato: le righe non si ripetono e non spariscono perché qualcosa è stato modificato a metà sincronizzazione, cosa che conta per una sincronizzazione notturna.

curl "https://api.mosaqo.app/v1/public-api/qr?limit=50&cursor=$CURSOR" \
  -H "Authorization: Bearer $MOSAQO_KEY"

Per interrogare le modifiche invece di percorrere tutto, aggiungi updatedSince=2026-08-05T00:00:00Z.

Errori

Ogni errore porta un code stabile su cui ramificare, un message leggibile e un requestId da citare al supporto.

{
  "error": "This API key does not have the qr:write scope.",
  "message": "This API key does not have the qr:write scope.",
  "code": "insufficient_scope",
  "details": { "required": "qr:write", "granted": ["qr:read"] },
  "requestId": "req-42"
}

Stato	Codici	Cosa fare
401	`invalid_api_key`	La chiave manca, è stata revocata o è scaduta. Chiedi all’utente di riconnettersi.
403	`insufficient_scope`, `ip_not_allowed`, `workspace_mismatch`, `quota_exceeded`	La chiave è valida ma non ha questo permesso. Riconnettersi non serve.
404	`not_found`	Nessun record del genere in questo spazio.
409	`idempotency_conflict`, `idempotency_in_progress`	Chiave riutilizzata con dati diversi, o primo tentativo ancora in corso.
422	`validation_failed`, `invalid_cursor`, `approval_required`, `contrast_check_failed`	Correggi l’input. Non riprovare mai identico.
429	`rate_limited`	Attendi i secondi indicati da `Retry-After`.

Limiti di frequenza

Ogni risposta porta il tuo budget attuale, non solo quelle rifiutate:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 1785942718

Il limite è una protezione contro gli abusi, non un piano: non implica quota, fatturazione né passaggio a un livello superiore.

Idempotenza

Idempotency-Key è facoltativo. Inviane una — una qualsiasi stringa univoca — e riprovare la stessa richiesta entro 24 ore riproduce la risposta originale invece di agire due volte. La stessa chiave con dati diversi restituisce 409. Senza chiave la richiesta viene semplicemente eseguita, senza protezione dalla ripetizione.

Avanti

Webhook: il catalogo degli eventi e come verificare una consegna.
Ricette: schemi per Make, Zapier, n8n e CRM.
Riferimento API: ogni endpoint, con console dal vivo.