Ricette di integrazione

Quattro schemi coprono quasi ogni integrazione che vediamo. Ognuno è una manciata di chiamate, e si combinano tra loro.

Riorientare un codice stampato

Il motivo per cui la maggior parte dei team ricorre all’API. Un codice su una confezione, un adesivo o un manifesto continua a funzionare mentre la campagna dietro di esso cambia.

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" }'

Su un codice pubblicato ha effetto immediato — non c’è un passaggio di ripubblicazione — e la risposta indica se il codice è live o ancora una bozza.

Allegare un QR a una scheda del CRM

Crea il codice con l’URL della scheda stessa, pubblicalo e porta l’immagine direttamente in un campo file. L’endpoint immagine restituisce i byte inline, quindi la maggior parte dei CRM li accetta come allegato senza un caricamento intermedio.

const headers = { Authorization: `Bearer ${process.env.MOSAQO_KEY}` };

const created = await fetch('https://api.mosaqo.app/v1/public-api/qr', {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: `Deal ${deal.id}`,
    mode: 'dynamic',
    contentType: 'url',
    content: { targetUrl: `https://crm.example.com/deals/${deal.id}` },
  }),
}).then((r) => r.json());

const qrId = created.data.id;
await fetch(`https://api.mosaqo.app/v1/public-api/qr/${qrId}/publish`, { method: 'POST', headers });

const png = await fetch(
  `https://api.mosaqo.app/v1/public-api/qr/${qrId}/image?format=png&size=1024`,
  { headers },
).then((r) => r.arrayBuffer());

Salva qrId sulla tua scheda. È la maniglia per tutto il resto: riorientamento, archiviazione, analitiche.

Emettere codici in blocco

Un codice per prodotto, per tavolo, per apparecchiatura. Invia un CSV, interroga il job e poi riporta i risultati sulle tue righe: ogni riga porta il qrId che ha prodotto.

curl -X POST https://api.mosaqo.app/v1/public-api/bulk \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "url",
    "mode": "dynamic",
    "csv": "name,destination\nTable 1,https://example.com/menu?t=1\nTable 2,https://example.com/menu?t=2"
  }'

curl "https://api.mosaqo.app/v1/public-api/bulk/$JOB_ID?limit=500" \
  -H "Authorization: Bearer $MOSAQO_KEY"

Invia prima "dryRun": true per validare ogni riga senza scrivere nulla.

Incorporare l’immagine tramite URL

Airtable, Notion e Sheets mostrano un’immagine a partire da un link che recuperano da soli, quindi non inviano mai la tua intestazione Authorization e non possono usare l’endpoint sopra. Chiedi invece un link firmato:

curl -X POST https://api.mosaqo.app/v1/public-api/qr/$QR_ID/image-url \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "format": "png", "size": 1024 }'

Valgono solo i codici pubblicati: un codice pubblicato è già stampato e nel mondo, mentre una bozza può essere una campagna non annunciata. Metti l’url restituito direttamente in un campo allegato o immagine. Archiviare o eliminare il codice interrompe subito il link: è così che si revoca quello che si è diffuso più del previsto.

Reagire alle scansioni

Le scansioni non vengono mai inviate: non c’è un webhook per singola scansione e non mandiamo analitiche a livello di scansione a endpoint di terze parti. Iscriviti a scan.aggregate_ready se ti basta un aggregato, oppure recupera tu stesso le singole scansioni su base periodica:

curl "https://api.mosaqo.app/v1/public-api/scans?since=$LAST_SEEN&limit=500" \
  -H "Authorization: Bearer $MOSAQO_KEY"

Conserva il pagination.nextCursor restituito e ripassalo la volta successiva. L’ordine è stabile, quindi un poller non rilegge né salta mai una scansione. Quali campi compaiano dipende dalle impostazioni di privacy analitica del tuo spazio: la risposta elenca allowedDimensions così sai cosa aspettarti.

Se il polling davvero non è praticabile e ti servono le scansioni nel momento in cui avvengono, è disponibile su richiesta, non per impostazione predefinita.

Piattaforme no-code

Make, Zapier, n8n e Pipedream possono già parlare con Mosaqo tramite un modulo HTTP generico, e i pezzi che servono ci sono: GET /me come test di connessione, paginazione a cursore per gli iteratori e sottoscrizioni webhook che un trigger crea e rimuove da solo.

Lo stesso documento OpenAPI si importa in Postman e Insomnia e genera un client tipizzato con openapi-typescript o un qualsiasi generatore OpenAPI.

Due regole da seguire

• Salva `qrId`, non l’URL pubblico. L’URL è stabile, ma è l’identificativo che serve a ogni chiamata successiva.
• Archivia invece di eliminare. L’eliminazione è definitiva e rovina ogni copia stampata; l’archiviazione toglie un codice dalla circolazione e si può annullare.

Tutti i dettagli sugli endpoint sono nel riferimento API.