Resep integrasi

Empat pola mencakup hampir setiap integrasi yang kami temui. Masing-masing hanya beberapa panggilan, dan bisa digabungkan.

Mengalihkan kode yang sudah dicetak

Alasan utama kebanyakan tim menggunakan API ini. Kode di kemasan, stiker, atau poster tetap bekerja sementara kampanye di baliknya berpindah.

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

Pada kode yang sudah terbit, efeknya langsung — tidak ada langkah terbit ulang — dan respons memberi tahu apakah kode sudah live atau masih draf.

Melampirkan QR ke catatan CRM

Buat kode dengan URL catatan itu sendiri, terbitkan, lalu tarik gambarnya langsung ke bidang berkas. Endpoint gambar mengembalikan byte secara inline, sehingga sebagian besar CRM menerimanya sebagai lampiran tanpa unggahan perantara.

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

Simpan qrId pada catatan Anda. Itulah pegangan untuk semua langkah berikutnya — pengalihan, pengarsipan, analitik.

Menerbitkan kode secara massal

Satu kode per produk, per meja, per peralatan. Kirim CSV, tanyakan status pekerjaannya, lalu petakan hasilnya kembali ke baris Anda sendiri — setiap baris membawa qrId yang dihasilkannya.

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"

Kirim "dryRun": true lebih dulu untuk memvalidasi setiap baris tanpa menulis apa pun.

Menyematkan gambar lewat URL

Airtable, Notion, dan Sheets menampilkan gambar dari tautan yang mereka ambil sendiri, jadi mereka tidak pernah mengirim header Authorization Anda dan tidak bisa memakai endpoint di atas. Mintalah tautan bertanda tangan sebagai gantinya:

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

Hanya kode yang sudah terbit yang memenuhi syarat — kode terbit sudah dicetak dan beredar, sedangkan draf bisa jadi kampanye yang belum diumumkan. Taruh url yang dikembalikan langsung ke bidang lampiran atau gambar. Mengarsipkan atau menghapus kode langsung mematikan tautan itu: begitulah Anda mencabut tautan yang tersebar lebih jauh dari yang Anda maksudkan.

Menanggapi pemindaian

Pemindaian tidak pernah dikirim keluar: tidak ada webhook per pemindaian, dan kami tidak mengirim analitik tingkat pemindaian ke endpoint pihak ketiga. Langgan scan.aggregate_ready bila agregat sudah cukup, atau ambil sendiri pemindaian individual sesuai jadwal:

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

Simpan pagination.nextCursor yang dikembalikan dan kirim lagi berikutnya. Urutannya stabil, sehingga penarik data tidak pernah membaca ulang atau melewati sebuah pemindaian. Bidang mana yang muncul bergantung pada pengaturan privasi analitik ruang kerja Anda — respons memuat allowedDimensions agar Anda tahu apa yang harus diharapkan.

Jika penarikan berkala memang tidak cocok bagi Anda dan Anda butuh pemindaian saat kejadian berlangsung, hal itu tersedia atas permintaan, bukan secara bawaan.

Platform no-code

Make, Zapier, n8n, dan Pipedream sudah bisa berbicara dengan Mosaqo lewat modul HTTP umum, dan potongan yang mereka butuhkan sudah tersedia: GET /me sebagai uji koneksi, paginasi kursor untuk iterator, serta langganan webhook yang dibuat dan dihapus sendiri oleh pemicu.

Dokumen OpenAPI yang sama bisa diimpor ke Postman dan Insomnia, dan menghasilkan klien bertipe dengan openapi-typescript atau generator OpenAPI mana pun.

Dua aturan yang layak diikuti

• Simpan `qrId`, bukan URL publiknya. URL-nya stabil, tetapi id itulah yang dibutuhkan setiap panggilan berikutnya.
• Arsipkan alih-alih menghapus. Menghapus bersifat permanen dan merusak setiap salinan cetak; mengarsipkan menarik kode dari peredaran dan bisa dibatalkan.

Rincian lengkap endpoint ada di referensi API.