Giới thiệu

Tài liệu public API của NiceQR.me cho tích hợp lập trình và server-to-server bằng API Key.

Tổng quan

Bộ tài liệu này chỉ mô tả public API dùng API Key cho các tích hợp server-to-server.

Các flow website và dashboard dùng JWT được cố ý loại khỏi bộ tài liệu này, bao gồm:

đăng ký và đăng nhập người dùng
Google login và refresh token
quản lý QR chỉ dành cho dashboard
quản lý Dynamic QR
analytics, teams và các flow nội bộ khác của ứng dụng

Base URL

https://api.niceqr.me/v1

Phạm vi public hiện tại

Hiện tại public API được tài liệu hóa gồm:

POST /v1/qr/generate

Định dạng response

Request thành công trả về JSON envelope thống nhất:

{
  "success": true,
  "data": { ... }
}

Khi có lỗi:

{
  "success": false,
  "error": {
    "message": "Mô tả lỗi",
    "code": "BAD_REQUEST"
  }
}

Phần lớn lỗi validation và lỗi server cũng dùng cùng envelope:

{
  "success": false,
  "error": {
    "message": "Mô tả lỗi",
    "code": "VALIDATION_ERROR"
  }
}

Mã lỗi thường gặp

Code	Mô tả
`BAD_REQUEST`	Input hoặc tham số không hợp lệ
`PREMIUM_REQUIRED`	Tài khoản chưa có quyền gói cần thiết cho tùy chọn QR đã yêu cầu
`VALIDATION_ERROR`	Dữ liệu không vượt qua validation
`SERVER_ERROR`	Lỗi nội bộ máy chủ

Xác thực

Tất cả endpoint public trong bộ tài liệu này đều dùng API key lấy từ Dashboard > API Keys qua header X-Api-Key:

X-Api-Key: nq_live_your_api_key

Xem Xác thực API Key để biết cách thiết lập và hành vi khi xác thực thất bại.

Với các route được bảo vệ bằng API key, trường hợp thiếu hoặc sai credential có thể cố ý trả về 404 Not Found với body rỗng thay vì JSON error envelope.

Giới hạn tốc độ

POST /v1/qr/generate: 60 req/phút ở lớp bảo vệ route
Mỗi API key cũng áp dụng giới hạn riêng theo cấu hình trên dashboard.

Bắt đầu nhanh

# Tạo QR code qua public API endpoint dùng API key
curl -X POST https://api.niceqr.me/v1/qr/generate \
  -H "X-Api-Key: nq_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "https://example.com",
    "bodyStyle": "square",
    "bodyBrush": { "type": "Solid", "color": "#000000" }
  }'

# Response: { "success": true, "data": { "svg": "<svg>...</svg>" } }