Integratierecepten

Vier patronen dekken bijna elke integratie die we zien. Elk is een handvol aanroepen, en ze laten zich combineren.

Een gedrukte code verleggen

De reden waarom de meeste teams überhaupt naar de API grijpen. Een code op verpakking, een sticker of een poster blijft werken terwijl de campagne erachter verhuist.

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

Bij een gepubliceerde code werkt het meteen — er is geen herpublicatiestap — en het antwoord vertelt of de code live is of nog een concept.

Een QR aan een CRM-record hangen

Maak de code met de URL van het record zelf, publiceer hem en trek de afbeelding rechtstreeks in een bestandsveld. Het afbeeldingsendpoint geeft de bytes inline terug, dus de meeste CRM’s accepteren ze als bijlage zonder tussentijdse upload.

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());

Bewaar qrId bij je record. Dat is het handvat voor al het latere werk — verleggen, archiveren, analytics.

Codes in bulk uitgeven

Eén code per product, per tafel, per apparaat. Stuur een CSV, poll de opdracht en koppel de resultaten daarna terug aan je eigen rijen — elke rij draagt de qrId die zij heeft opgeleverd.

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"

Stuur eerst "dryRun": true om elke rij te valideren zonder iets weg te schrijven.

De afbeelding via URL insluiten

Airtable, Notion en Sheets tonen een afbeelding via een link die ze zelf ophalen; ze sturen dus nooit je Authorization-header en kunnen het endpoint hierboven niet gebruiken. Vraag in plaats daarvan een ondertekende link:

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

Alleen gepubliceerde codes komen in aanmerking — een gepubliceerde code is al gedrukt en in de wereld, terwijl een concept een onaangekondigde campagne kan zijn. Zet de teruggegeven url rechtstreeks in een bijlage- of afbeeldingsveld. De code archiveren of verwijderen laat de link direct doodlopen: zo trek je er een in die verder is verspreid dan bedoeld.

Reageren op scans

Scans worden nooit gepusht: er is geen webhook per scan, en we sturen geen analytics op scanniveau naar endpoints van derden. Abonneer je op scan.aggregate_ready als een aggregatie genoeg is, of haal losse scans zelf volgens een schema op:

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

Bewaar de teruggegeven pagination.nextCursor en geef hem de volgende keer mee. De volgorde is stabiel, dus een poller leest nooit dubbel en slaat nooit een scan over. Welke velden verschijnen hangt af van de analytics-privacyinstellingen van je werkruimte — het antwoord toont allowedDimensions zodat je weet wat je kunt verwachten.

Is pollen voor jou echt niet werkbaar en heb je scans nodig op het moment dat ze gebeuren, dan kan dat op aanvraag, niet standaard.

No-codeplatforms

Make, Zapier, n8n en Pipedream kunnen vandaag al met Mosaqo praten via een generieke HTTP-module, en de onderdelen die ze nodig hebben liggen klaar: GET /me als verbindingstest, cursorpaginering voor iterators, en webhook-abonnementen die een trigger zelf aanmaakt en opruimt.

Hetzelfde OpenAPI-document importeert in Postman en Insomnia, en genereert met openapi-typescript of een willekeurige OpenAPI-generator een getypeerde client.

Twee regels die de moeite waard zijn

• Bewaar `qrId`, niet de publieke URL. De URL is stabiel, maar het is de id die elke latere aanroep nodig heeft.
• Archiveer in plaats van verwijderen. Verwijderen is definitief en maakt elke gedrukte kopie onbruikbaar; archiveren haalt een code uit de lucht en is terug te draaien.

Alle details over de endpoints staan in de API-referentie.