Integrační recepty

Čtyři vzory pokryjí téměř každou integraci, se kterou se potkáváme. Každý je pár volání a dají se skládat.

Přesměrovat vytištěný kód

Důvod, proč většina týmů po API vůbec sáhne. Kód na obalu, samolepce nebo plakátu funguje dál, zatímco kampaň za ním se mění.

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

U publikovaného kódu platí okamžitě — žádný krok opětovné publikace není — a odpověď říká, zda je kód live, nebo pořád koncept.

Připojit QR k záznamu v CRM

Vytvořte kód s adresou samotného záznamu, publikujte ho a obrázek natáhněte rovnou do souborového pole. Endpoint obrázku vrací bajty inline, takže většina CRM je přijme jako přílohu bez mezikroku s nahráváním.

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

Uložte si qrId u svého záznamu. Je to rukojeť pro všechno další — přesměrování, archivaci, analytiku.

Vydat kódy hromadně

Jeden kód na produkt, na stůl, na zařízení. Pošlete CSV, ptejte se na úlohu a pak výsledky přiřaďte ke svým řádkům — každý řádek nese qrId, který vytvořil.

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"

Nejdřív pošlete "dryRun": true, aby se každý řádek ověřil a nic se nezapsalo.

Vložit obrázek přes URL

Airtable, Notion a Sheets zobrazují obrázek z odkazu, pro který si jdou samy, takže nikdy neposílají vaši hlavičku Authorization a endpoint výše použít nemohou. Vyžádejte si místo toho podepsaný odkaz:

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

Nárok mají jen publikované kódy — publikovaný kód je už vytištěný a ve světě, kdežto koncept může být neohlášená kampaň. Vrácenou url vložte rovnou do pole pro přílohu nebo obrázek. Archivace nebo smazání kódu odkaz okamžitě umlčí — přesně tak se odvolává ten, který se rozšířil dál, než jste zamýšleli.

Reagovat na skenování

Skenování nikdy neposíláme sami: webhook na jednotlivé skenování neexistuje a analytiku na úrovni skenování na endpointy třetích stran neposíláme. Odebírejte scan.aggregate_ready, pokud stačí agregát, nebo si jednotlivá skenování stahujte sami podle rozvrhu:

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

Uschovejte vrácený pagination.nextCursor a příště ho pošlete zpět. Pořadí je stabilní, takže dotazovač nikdy nečte dvakrát ani skenování nepřeskočí. Která pole se objeví, závisí na nastavení soukromí analytiky vašeho prostoru — odpověď vypisuje allowedDimensions, abyste věděli, co čekat.

Pokud vám dotazování opravdu nevyhovuje a potřebujete skenování ve chvíli, kdy nastanou, je to dostupné na vyžádání, ne ve výchozím stavu.

No-code platformy

Make, Zapier, n8n i Pipedream si už dnes s Mosaqo poradí přes obecný HTTP modul a díly, které k tomu potřebují, jsou na místě: GET /me jako test spojení, kurzorové stránkování pro iterátory a odběry webhooků, které si spouštěč založí a zruší sám.

Tentýž dokument OpenAPI se importuje do Postmana i Insomnie a přes openapi-typescript nebo libovolný generátor OpenAPI vyrobí typovaného klienta.

Dvě pravidla, kterých se držet

• Ukládejte `qrId`, ne veřejnou adresu. Adresa je stabilní, ale identifikátor je to, co potřebuje každé další volání.
• Archivujte místo mazání. Smazání je nevratné a znehodnotí každou vytištěnou kopii; archivace kód stáhne z provozu a dá se vzít zpět.

Všechny podrobnosti o endpointech jsou v referenci API.