API Mosaqo dành cho lập trình viên

Một API REST trên chính không gian làm việc bạn dùng trong ứng dụng. Mọi thứ bên dưới hoạt động với một khóa API duy nhất và bất kỳ HTTP client nào.

Bạn có thể làm gì

• Tạo mã QR từ bản ghi của bạn — từng cái một, hoặc mười nghìn cái từ một tệp CSV.
• Đổi đích đến của một mã đã in, chỉ bằng một lệnh gọi và không phải in lại gì cả.
• Tải thẻ hoàn chỉnh dưới dạng PNG, SVG hoặc PDF và đính kèm vào bản ghi CRM.
• Đọc lượt quét và số liệu tổng hợp, đã lọc theo quy tắc riêng tư của không gian làm việc.
• Nhận webhook có chữ ký khi mã được tạo, xuất bản, thay đổi hoặc lưu trữ.

Bắt đầu nhanh

Tạo một khóa trong mục Bulk & API của không gian làm việc, chọn phạm vi qr:write và qr:read, rồi sao chép secret — nó chỉ hiện ra một lần.

Kiểm tra khóa và xem nó mở không gian làm việc nào:

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

Tạo một mã QR động:

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

Xuất bản nó — chính bước này làm chuyển hướng hoạt động — rồi lấy ảnh có thể đem in:

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

Nhiều tháng sau, khi chiến dịch thay đổi, hãy đổi đích chính mã đã in đó mà không phải in lại:

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

Xác thực

Gửi secret theo một trong hai cách. Cả hai đều dùng được suốt v1.

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

Một khóa thuộc về đúng một không gian làm việc, nên đường dẫn không cần id không gian: /v1/public-api/qr là đủ. Dạng cũ /v1/public-api/workspaces/{workspaceId}/qr vẫn hoạt động.

Khóa có thể bị thu hồi, đặt ngày hết hạn và giới hạn theo danh sách IP cho phép. Nếu chính danh sách đó từ chối khóa, chúng tôi nói rõ điều ấy thay vì để nó trông như không hợp lệ.

Phân trang

Danh sách dùng phân trang theo khóa. Hãy gửi lại pagination.nextCursor nguyên vẹn: các dòng không bao giờ lặp lại hay biến mất chỉ vì có gì đó được sửa giữa chừng — điều rất quan trọng với một lần đồng bộ ban đêm.

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

Muốn hỏi về thay đổi thay vì duyệt lại tất cả, hãy thêm updatedSince=2026-08-05T00:00:00Z.

Lỗi

Mỗi lỗi mang theo một code ổn định để rẽ nhánh, một message dễ đọc và một requestId đáng nhắc khi liên hệ hỗ trợ.

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

Giới hạn tần suất

Mọi phản hồi đều mang theo hạn mức hiện tại của bạn, không chỉ những phản hồi bị từ chối:

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

Giới hạn này là biện pháp chống lạm dụng, không phải gói dịch vụ: nó không hàm ý hạn mức, hóa đơn hay việc nâng cấp.

Tính bất biến khi lặp lại

Idempotency-Key là tùy chọn. Hãy gửi một khóa — bất kỳ chuỗi duy nhất nào — và việc thử lại y hệt trong vòng 24 giờ sẽ phát lại phản hồi ban đầu thay vì thực hiện hai lần. Cùng một khóa với dữ liệu khác sẽ trả về 409. Không có khóa thì yêu cầu chỉ đơn giản chạy, không có bảo vệ trước việc lặp lại.

Tiếp theo

• Webhook — danh mục sự kiện và cách xác minh một lần gửi.
• Công thức — các mẫu cho Make, Zapier, n8n và CRM.
• Tài liệu API — từng endpoint, kèm bảng điều khiển trực tiếp.