Integrations-Rezepte

Vier Muster decken fast jede Integration ab, die uns begegnet. Jedes besteht aus einer Handvoll Aufrufe, und sie lassen sich kombinieren.

Einen gedruckten Code umlenken

Der Grund, aus dem die meisten Teams überhaupt zur API greifen. Ein Code auf Verpackung, Aufkleber oder Plakat funktioniert weiter, während die Kampagne dahinter umzieht.

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

Bei einem veröffentlichten Code wirkt es sofort — es gibt keinen erneuten Veröffentlichungsschritt — und die Antwort sagt Ihnen, ob der Code live oder noch Entwurf ist.

Einen QR an einen CRM-Datensatz hängen

Erstellen Sie den Code mit der URL des Datensatzes, veröffentlichen Sie ihn und ziehen Sie das Bild direkt in ein Dateifeld. Der Bild-Endpunkt liefert die Bytes inline, deshalb nehmen die meisten CRMs sie ohne Zwischen-Upload als Anhang an.

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

Speichern Sie qrId am Datensatz. Sie ist der Griff für alles Spätere — Umlenken, Archivieren, Analytics.

Codes in Serie ausgeben

Ein Code pro Produkt, pro Tisch, pro Anlage. Senden Sie eine CSV, pollen Sie den Job und ordnen Sie die Ergebnisse Ihren Zeilen zu — jede Zeile trägt die qrId, die sie erzeugt hat.

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"

Senden Sie zuerst "dryRun": true, um jede Zeile zu prüfen, ohne etwas zu schreiben.

Das Bild per URL einbinden

Airtable, Notion und Sheets zeigen ein Bild über einen Link, den sie selbst abrufen; sie senden also nie Ihren Authorization-Header und können den Endpunkt oben nicht nutzen. Fordern Sie stattdessen einen signierten Link an:

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

Nur veröffentlichte Codes kommen infrage — ein veröffentlichter Code ist bereits gedruckt und in der Welt, ein Entwurf kann eine unangekündigte Kampagne sein. Legen Sie die zurückgegebene url direkt in ein Anhang- oder Bildfeld. Archivieren oder Löschen des Codes lässt den Link sofort ins Leere laufen — so widerrufen Sie einen, der weiter gestreut wurde als beabsichtigt.

Auf Scans reagieren

Scans werden nie gepusht: Es gibt keinen Webhook pro Scan, und Analytics auf Scan-Ebene senden wir nicht an fremde Endpunkte. Abonnieren Sie scan.aggregate_ready, wenn eine Aggregation reicht, oder holen Sie einzelne Scans nach Zeitplan selbst ab:

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

Behalten Sie den zurückgegebenen pagination.nextCursor und geben Sie ihn beim nächsten Mal mit. Die Reihenfolge ist stabil, ein Poller liest also nie doppelt und überspringt nie einen Scan. Welche Felder erscheinen, hängt von den Analytics-Datenschutzeinstellungen Ihres Workspace ab — die Antwort listet allowedDimensions, damit Sie wissen, was zu erwarten ist.

Wenn Pollen für Sie wirklich nicht praktikabel ist und Sie Scans in dem Moment brauchen, in dem sie passieren, ist das auf Anfrage möglich, nicht standardmäßig.

No-Code-Plattformen

Make, Zapier, n8n und Pipedream können heute schon über ein generisches HTTP-Modul mit Mosaqo sprechen, und die nötigen Teile sind vorhanden: GET /me als Verbindungstest, Cursor-Paginierung für Iteratoren und Webhook-Abonnements, die ein Trigger selbst anlegt und entfernt.

Dasselbe OpenAPI-Dokument lässt sich in Postman und Insomnia importieren und erzeugt mit openapi-typescript oder einem beliebigen OpenAPI-Generator einen typisierten Client.

Zwei Regeln, an die man sich halten sollte

• Speichern Sie `qrId`, nicht die öffentliche URL. Die URL ist stabil, aber die ID braucht jeder spätere Aufruf.
• Archivieren statt löschen. Löschen ist endgültig und macht jede gedruckte Kopie unbrauchbar; Archivieren nimmt einen Code vom Netz und lässt sich rückgängig machen.

Alle Details zu den Endpunkten stehen in der API-Referenz.