批量操作

使用 CodeBox API 和 SDK 进行批量二维码生成，了解限制、错误处理和最佳实践

概述

CodeBox 支持通过单次 API 调用批量生成最多 20 个二维码。批量操作采用 partial failure 模式——每个 item 独立处理，部分失败不影响其他 item 的生成。

使用方式

SDK

import { CodeBox } from '@codebox.club/sdk';

const client = new CodeBox({ apiKey: 'cb_sk_xxx' });

const batch = await client.qrcodes.batchCreate([
  { content: 'https://page1.com', name: '活动页面 1' },
  { content: 'https://page2.com', name: '活动页面 2', templateId: 'tech-modern-01' },
  { content: 'https://page3.com', name: '活动页面 3', mode: 'STATIC' },
]);

console.log(`成功: ${batch.succeeded} / ${batch.total}`);

REST API

curl -X POST https://www.codebox.club/api/v1/plugin/batch-generate \
  -H "Authorization: Bearer cb_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "content": "https://page1.com", "name": "活动页面 1" },
      { "content": "https://page2.com", "name": "活动页面 2", "templateId": "tech-modern-01" },
      { "content": "https://page3.com", "name": "活动页面 3", "mode": "STATIC" }
    ]
  }'

MCP Tool

在 AI Agent 中使用 batch_generate 工具：

{
  "name": "batch_generate",
  "arguments": {
    "items": [
      { "content": "https://page1.com", "name": "页面 1" },
      { "content": "https://page2.com", "name": "页面 2" }
    ]
  }
}

限制

限制项	值	说明
单次最大数量	20	超过 20 个将返回 400 错误
每日配额	共享	批量中每个成功的非静态 item 消耗 1 次额度，静态码不消耗
超时	无特殊限制	逐个串行处理，总时间与数量成正比

响应格式

{
  total: number;      // 提交的总数
  succeeded: number;  // 成功生成的数量
  failed: number;     // 失败的数量
  results: Array<{
    index: number;      // 在原始数组中的位置
    success: boolean;
    data?: {
      id: string;           // 二维码 ID
      shortLink?: string;   // 追踪短链（DYNAMIC 模式）
      templateUsed: string; // 使用的模板
    };
    error?: string;     // 失败原因
  }>;
}

错误处理

Partial Failure

批量操作中，每个 item 独立处理。即使某些 item 失败，其他 item 仍然会正常生成：

const batch = await client.qrcodes.batchCreate([
  { content: 'https://valid.com', name: '有效' },
  { content: 'https://valid2.com', templateId: 'invalid-template' }, // 模板不存在
  { content: 'https://valid3.com', name: '也有效' },
]);

// batch.succeeded === 2, batch.failed === 1
// results[1].success === false, results[1].error === 'Template "invalid-template" not found'

常见错误

错误	原因	解决方案
`items array is required`	未提供 items 或非数组	确保传入有效的数组
`Maximum 20 items per batch`	超过 20 个上限	拆分为多次调用
`content is required`	item 缺少 content 字段	确保每个 item 都有 content
`Template "xxx" not found`	指定的模板 ID 不存在	用 `list_templates` 查询有效模板
`额度不足，请充值`	额度余额为 0	在 Dashboard → 充值额度购买额度包

使用场景

营销活动批量生成

为营销活动的多个落地页批量生成追踪二维码：

const pages = ['landing-a', 'landing-b', 'landing-c', 'landing-d'];

const batch = await client.qrcodes.batchCreate(
  pages.map(page => ({
    content: `https://campaign.example.com/${page}`,
    name: `营销活动 - ${page}`,
    mode: 'DYNAMIC' as const,
    keywords: ['营销', '现代'],
  }))
);

产品目录二维码

为产品目录中的每个产品生成二维码：

const products = [
  { id: 'SKU001', name: '产品 A', url: 'https://shop.com/sku001' },
  { id: 'SKU002', name: '产品 B', url: 'https://shop.com/sku002' },
];

const batch = await client.qrcodes.batchCreate(
  products.map(p => ({
    content: p.url,
    name: `产品码 - ${p.name}`,
  }))
);

最佳实践

控制批量大小：虽然上限是 20，但建议每批 10 个以内以获得最佳响应速度
检查部分失败：始终检查 results 中每个 item 的 success 状态
额度管理：每个非静态 item 消耗 1 次额度（静态码不消耗），额度不足的 item 会失败但不影响其他 item
重试策略：仅重试失败的 item，不要重复提交成功的 item

On this page