API Mosaqo untuk pengembang

API REST di atas ruang kerja yang sama dengan yang Anda pakai di aplikasi. Semua di bawah ini bekerja dengan satu kunci API dan klien HTTP apa pun.

Apa yang bisa Anda lakukan

Membuat kode QR dari catatan Anda sendiri — satu per satu, atau sepuluh ribu dari sebuah CSV.
Mengubah tujuan kode yang sudah dicetak, dengan satu panggilan dan tanpa mencetak ulang apa pun.
Mengunduh kartu jadi dalam PNG, SVG, atau PDF dan melampirkannya ke catatan CRM.
Membaca pemindaian dan analitik agregat, tersaring oleh aturan privasi ruang kerja Anda.
Menerima webhook bertanda tangan saat kode dibuat, diterbitkan, diubah, atau diarsipkan.

Panduan cepat

Buat kunci di Bulk & API dalam ruang kerja Anda, centang scope qr:write dan qr:read, lalu salin rahasianya — hanya ditampilkan sekali.

Periksa kunci dan cari tahu ruang kerja mana yang dibukanya:

curl https://api.mosaqo.app/v1/public-api/me \
  -H "Authorization: Bearer $MOSAQO_KEY"

Buat kode QR dinamis:

curl -X POST https://api.mosaqo.app/v1/public-api/qr \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Autumn campaign",
    "mode": "dynamic",
    "contentType": "url",
    "content": { "targetUrl": "https://example.com/autumn" }
  }'

Terbitkan — inilah yang membuat pengalihan bekerja — lalu ambil gambar yang siap dicetak:

curl -X POST https://api.mosaqo.app/v1/public-api/qr/$QR_ID/publish \
  -H "Authorization: Bearer $MOSAQO_KEY"

curl https://api.mosaqo.app/v1/public-api/qr/$QR_ID/image?format=png&size=2048 \
  -H "Authorization: Bearer $MOSAQO_KEY" -o campaign.png

Berbulan-bulan kemudian, saat kampanye berpindah, alihkan kode cetak yang sama tanpa mencetak ulang:

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

Autentikasi

Kirim rahasia Anda dengan salah satu cara. Keduanya berlaku sepanjang v1.

Authorization: Bearer mosaqo_xxx
X-Mosaqo-API-Key: mosaqo_xxx

Sebuah kunci hanya milik satu ruang kerja, jadi jalur tidak memerlukan id ruang kerja: /v1/public-api/qr sudah cukup. Bentuk lama /v1/public-api/workspaces/{workspaceId}/qr masih bekerja.

Scope	Memberi hak
`qr:read`	Menampilkan dan membaca kode QR, folder, dan templat
`qr:write`	Membuat, mengubah, mengalihkan, menerbitkan, mengarsipkan, dan menghapus
`exports:read`	Mengunduh kartu yang sudah dirender
`analytics:read`	Analitik agregat dan pemindaian individual
`bulk:write`	Membuat dan membaca pekerjaan massal
`webhooks:write`	Mengelola langganan webhook

Kunci bisa dicabut, diberi tanggal kedaluwarsa, dan dibatasi ke daftar IP yang diizinkan. Jika daftar itulah yang menolak kunci, kami mengatakannya secara eksplisit alih-alih membuatnya tampak tidak valid.

Paginasi

Daftar memakai paginasi berbasis kunci. Kirim kembali pagination.nextCursor tanpa diubah: baris tidak pernah terulang atau hilang karena ada yang disunting di tengah sinkronisasi — hal yang penting untuk sinkronisasi malam hari.

curl "https://api.mosaqo.app/v1/public-api/qr?limit=50&cursor=$CURSOR" \
  -H "Authorization: Bearer $MOSAQO_KEY"

Untuk menanyakan perubahan alih-alih menelusuri semuanya, tambahkan updatedSince=2026-08-05T00:00:00Z.

Kesalahan

Setiap kegagalan membawa code yang stabil untuk percabangan logika, message yang mudah dibaca, dan requestId yang layak disebutkan ke tim dukungan.

{
  "error": "This API key does not have the qr:write scope.",
  "message": "This API key does not have the qr:write scope.",
  "code": "insufficient_scope",
  "details": { "required": "qr:write", "granted": ["qr:read"] },
  "requestId": "req-42"
}

Status	Kode	Apa yang dilakukan
401	`invalid_api_key`	Kunci tidak ada, dicabut, atau kedaluwarsa. Minta pengguna menyambung ulang.
403	`insufficient_scope`, `ip_not_allowed`, `workspace_mismatch`, `quota_exceeded`	Kunci valid tetapi tidak berhak melakukan ini. Menyambung ulang tidak membantu.
404	`not_found`	Tidak ada catatan seperti itu di ruang kerja ini.
409	`idempotency_conflict`, `idempotency_in_progress`	Kunci dipakai ulang dengan data berbeda, atau percobaan pertama masih berjalan.
422	`validation_failed`, `invalid_cursor`, `approval_required`, `contrast_check_failed`	Perbaiki masukan. Jangan pernah mengulang tanpa perubahan.
429	`rate_limited`	Tunggu sejumlah detik yang tertera di `Retry-After`.

Batas permintaan

Setiap respons membawa sisa jatah Anda saat ini, bukan hanya yang ditolak:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 1785942718

Batas ini adalah pengaman terhadap penyalahgunaan, bukan paket: tidak berarti kuota, penagihan, atau peningkatan langganan.

Idempotensi

Idempotency-Key bersifat opsional. Kirimkan satu — string unik apa pun — dan mengulang permintaan yang identik dalam 24 jam akan memutar ulang respons awal alih-alih bertindak dua kali. Kunci yang sama dengan data berbeda mengembalikan 409. Tanpa kunci, permintaan hanya dijalankan, tanpa perlindungan terhadap pengulangan.

Selanjutnya

Webhook — katalog peristiwa dan cara memverifikasi pengiriman.
Resep — pola untuk Make, Zapier, n8n, dan CRM.
Referensi API — setiap endpoint, dengan konsol langsung.