Công thức tích hợp

Bốn mẫu bao phủ gần như mọi tích hợp chúng tôi gặp. Mỗi mẫu chỉ vài lệnh gọi, và chúng ghép được với nhau.

Đổi đích một mã đã in

Lý do khiến phần lớn các nhóm tìm đến API. Một mã trên bao bì, nhãn dán hay áp phích vẫn chạy trong khi chiến dịch phía sau nó đổi chỗ.

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

Trên mã đã xuất bản, thay đổi có hiệu lực ngay — không có bước xuất bản lại — và phản hồi cho biết mã đang live hay vẫn là bản nháp.

Đính QR vào bản ghi CRM

Tạo mã với chính URL của bản ghi, xuất bản nó, rồi kéo ảnh thẳng vào một trường tệp. Endpoint ảnh trả về byte dạng inline, nên phần lớn CRM nhận nó như tệp đính kèm mà không cần bước tải lên trung gian.

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

Hãy lưu qrId trên bản ghi của bạn. Đó là tay cầm cho mọi việc về sau — đổi đích, lưu trữ, số liệu.

Phát hành mã hàng loạt

Một mã cho mỗi sản phẩm, mỗi bàn, mỗi thiết bị. Gửi một tệp CSV, hỏi trạng thái tác vụ, rồi ánh xạ kết quả về các dòng của bạn — mỗi dòng mang theo qrId mà nó tạo ra.

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"

Hãy gửi "dryRun": true trước để kiểm tra từng dòng mà không ghi gì cả.

Nhúng ảnh bằng URL

Airtable, Notion và Sheets hiển thị ảnh từ một liên kết mà chính chúng đi lấy, nên chúng không bao giờ gửi header Authorization của bạn và không dùng được endpoint ở trên. Hãy xin một liên kết có chữ ký thay thế:

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

Chỉ mã đã xuất bản mới đủ điều kiện — mã đã xuất bản thì đã in ra và ở ngoài đời, còn bản nháp có thể là chiến dịch chưa công bố. Hãy đặt url trả về thẳng vào trường đính kèm hoặc trường ảnh. Lưu trữ hoặc xóa mã sẽ ngắt liên kết ngay lập tức: đó là cách bạn thu hồi một liên kết đã lan xa hơn dự tính.

Phản ứng với lượt quét

Lượt quét không bao giờ được đẩy ra ngoài: không có webhook cho từng lượt quét, và chúng tôi không gửi số liệu ở mức lượt quét tới endpoint của bên thứ ba. Hãy đăng ký scan.aggregate_ready nếu bản tổng hợp là đủ, hoặc tự lấy từng lượt quét theo lịch:

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

Giữ lại pagination.nextCursor được trả về và gửi lại ở lần sau. Thứ tự ổn định, nên trình lấy dữ liệu không bao giờ đọc lại hay bỏ sót một lượt quét. Những trường nào xuất hiện là tùy thiết lập riêng tư về số liệu của không gian làm việc — phản hồi liệt kê allowedDimensions để bạn biết cần chờ đợi gì.

Nếu việc hỏi định kỳ thực sự không phù hợp và bạn cần lượt quét ngay lúc chúng xảy ra, điều đó có thể thu xếp theo yêu cầu, chứ không mặc định.

Nền tảng no-code

Make, Zapier, n8n và Pipedream hôm nay đã nói chuyện được với Mosaqo qua một module HTTP thông thường, và những mảnh chúng cần đều đã có: GET /me làm phép thử kết nối, phân trang theo con trỏ cho vòng lặp, và các đăng ký webhook mà trigger tự tạo rồi tự gỡ.

Cùng tài liệu OpenAPI đó nhập được vào Postman và Insomnia, và sinh ra client có kiểu bằng openapi-typescript hay bất kỳ bộ sinh OpenAPI nào.

Hai nguyên tắc đáng theo

• Hãy lưu `qrId`, đừng lưu URL công khai. URL thì ổn định, nhưng id mới là thứ mọi lệnh gọi về sau cần đến.
• Hãy lưu trữ thay vì xóa. Xóa là vĩnh viễn và làm hỏng mọi bản in; lưu trữ chỉ đưa mã ra khỏi hoạt động và có thể hoàn tác.

Chi tiết đầy đủ về endpoint nằm trong tài liệu API.