CodeBox相关文档

API接口文档

详细的API接口说明与示例

接口概述

本API文档为二维码平台提供RESTful API接口规范,支持用户通过API Key进行身份验证,并获取二维码相关信息、统计数据等功能。

身份验证

所有API请求都需要在请求头中包含有效的API Key (可以在后台获取个人的APIKEY):

cb-api-key: {your_api_key}

基础信息

  • Base URL: /api/v1
  • Content-Type: application/json
  • 认证方式: API Key Header

接口列表

1. 获取单个二维码详情

根据二维码ID获取详细信息。

HTTP请求

GET /api/v1/qrcode/{id}
cb-api-key: xxxxxxxxxx

响应示例

{
  "success": true,
  "data": {
    "id": "687efd6372eaa51df94bc232",
    "name": "产品宣传二维码",
    "qrType": "URL",
    "targetUrl": "https://example.com/promo",
    "qrImage": "https://cdn.example.com/qrcodes/qr_123.png",
    "createdAt": "2025-07-22T03:09:31.000Z",
  }
}

无权限响应

{
  "error": "QR code not found or access denied"
}

2. 获取二维码统计数据

获取指定二维码的详细统计数据。

HTTP请求

GET /api/v1/qrcode/{id}/stats
cb-api-key: xxxxxxxxxx

响应示例

{
  "success": true,
  "data": {
    "id": "687efd6372eaa51df94bc232",
    "totalScans": 42,
    "uniqueUsers": 35,
    "lastScanAt": "2025-07-22T08:30:15.000Z",
    "topRegions": [
      {
        "country": "CN",
        "region": "北京",
        "city": "北京",
        "scans": 25
      },
      {
        "country": "CN",
        "region": "上海",
        "city": "上海",
        "scans": 12
      },
      {
        "country": "CN",
        "region": "广东",
        "city": "深圳",
        "scans": 5
      }
    ]
  }
}

错误码说明

状态码描述
200请求成功
401未授权,API Key无效或缺失
404资源未找到或访问被拒绝
429超过API调用限制
500服务器内部错误

使用示例

JavaScript (Axios)

import axios from 'axios';
 
const API_KEY = 'xxxxxxxxxx';
const BASE_URL = '/api/v1';
 
// 获取二维码详情
async function getQRCodeDetail(id) {
  const response = await axios.get(`${BASE_URL}/qrcode/${id}`, {
    headers: {
      'cb-api-key': API_KEY
    }
  });
  return response.data;
}

cURL 命令示例

 
# 获取二维码详情
curl -H "cb-api-key: {api_key}" \
     /api/v1/qrcode/687efd6372eaa51df94bc232
 
# 获取二维码统计
curl -H "cb-api-key: {api_key}" \
     /api/v1/qrcode/687efd6372eaa51df94bc232/stats

注意事项

  1. API Key安全: 请勿将API Key暴露在客户端代码中
  2. 频率限制: 每个用户每天最多调用100次API
  3. 分页: 列表接口默认每页20条记录,最大支持100条
  4. 时区: 所有时间均为UTC格式
  5. 错误处理: 建议对所有API调用进行错误处理

后续扩展

  • 支持创建二维码API
  • 支持更新二维码API
  • 支持删除二维码API
  • 支持批量操作API
  • 支持Webhook通知
  • 支持自定义配额设置

On this page