官方 SDK

基于 REST API 的五种最常被要求语言的强类型客户端。每个 SDK 均内置 bearer token 认证、429 和 5xx 的指数退避重试，以及用于验证 X-Abundera-Signature 头 HMAC-SHA256 签名的 verifyWebhookSignature 工具函数。MIT 许可。

权威来源：/docs/openapi.json · 问题反馈：support@abundera.ai

TS

TypeScript / Node

@abundera/qr-pro

Node 18+。零运行时依赖。提供 ESM 和 CJS 构建。

安装

npm install @abundera/qr-pro

创建码

import { AbunderaQRProClient } from "@abundera/qr-pro";

const client = new AbunderaQRProClient({
  apiKey: process.env.ABUNDERA_API_KEY!,
});

const code = await client.createCode({
  destination_url: "https://example.com/launch",
  label: "Spring launch poster",
});

console.log(code.short_url);

验证 Webhook

import { verifyWebhookSignature } from "@abundera/qr-pro";

verifyWebhookSignature({
  signature: req.headers["x-abundera-signature"],
  body: rawBody,
  secret: process.env.ABUNDERA_WEBHOOK_SECRET!,
});
// 签名错误或时间偏差时抛出异常, , 此行后可安全解析请求体

GitHub 源码 →

Py

Python

abundera-qr-pro

Python 3.9+。单一依赖（httpx）。同步和异步客户端均可用。

安装

pip install abundera-qr-pro

创建码

from abundera_qr_pro import Client

with Client(api_key="abnd_qrpro_...") as c:
    code = c.create_code(
        destination_url="https://example.com/launch",
        label="Spring launch poster",
    )
    print(code.short_url)

验证 Webhook

from abundera_qr_pro import verify_webhook_signature
from abundera_qr_pro.webhook import WebhookVerificationError

try:
    verify_webhook_signature(
        signature=request.headers["X-Abundera-Signature"],
        body=request.body,
        secret=os.environ["ABUNDERA_WEBHOOK_SECRET"],
    )
except WebhookVerificationError:
    return "", 400

GitHub 源码 →

Go

Go

github.com/abundera/qr-pro-go

Go 1.21+。仅使用标准库。全程支持 Context。

安装

go get github.com/abundera/qr-pro-go

创建码

import qrpro "github.com/abundera/qr-pro-go"

c, _ := qrpro.New(os.Getenv("ABUNDERA_API_KEY"))
ctx := context.Background()

code, err := c.CreateCode(ctx, qrpro.CodeCreate{
    DestinationURL: "https://example.com/launch",
    Label:          "Spring launch poster",
})
if err != nil { log.Fatal(err) }
fmt.Println(code.ShortURL)

验证 Webhook

if err := qrpro.VerifyWebhookSignature(
    r.Header.Get("X-Abundera-Signature"),
    body,
    os.Getenv("ABUNDERA_WEBHOOK_SECRET"),
    0, // 默认 300 秒容差
); err != nil {
    http.Error(w, "bad signature", http.StatusBadRequest)
    return
}

GitHub 源码 →

Rb

Ruby

abundera-qr-pro

Ruby 3.0+。基于 Faraday。与 Rails initializer 配合良好。

安装

gem install abundera-qr-pro
# 或在 Gemfile 中
gem "abundera-qr-pro"

创建码

require "abundera/qr_pro"

client = Abundera::QRPro::Client.new(api_key: ENV.fetch("ABUNDERA_API_KEY"))

code = client.create_code(
  destination_url: "https://example.com/launch",
  label: "Spring launch poster",
)

puts code.short_url

验证 Webhook

require "abundera/qr_pro/webhook"

begin
  Abundera::QRPro::Webhook.verify!(
    signature: request.headers["X-Abundera-Signature"],
    body: request.raw_post,
    secret: ENV.fetch("ABUNDERA_WEBHOOK_SECRET"),
  )
rescue Abundera::QRPro::Webhook::InvalidSignature
  head :bad_request
end

GitHub 源码 →

PHP

PHP

abundera/qr-pro

PHP 8.1+。支持任何 PSR-18 HTTP 客户端（默认使用 Guzzle）。Laravel 和 Symfony 服务提供商包含在同一包中。

安装

composer require abundera/qr-pro

创建码

use Abundera\QrPro\Client;

$client = new Client(apiKey: getenv('ABUNDERA_API_KEY'));

$code = $client->createCode(
    destinationUrl: 'https://example.com/launch',
    label: 'Spring launch poster',
);

echo $code->shortUrl;

验证 Webhook

use Abundera\QrPro\Webhook;
use Abundera\QrPro\WebhookException;

try {
    Webhook::verify(
        signature: $_SERVER['HTTP_X_ABUNDERA_SIGNATURE'] ?? '',
        body: file_get_contents('php://input'),
        secret: getenv('ABUNDERA_WEBHOOK_SECRET'),
    );
} catch (WebhookException $e) {
    http_response_code(400);
    exit;
}

GitHub 源码 →

每个 SDK 涵盖的内容

  • Codes列表、获取、创建、更新、删除、短码检查、批量导入。
  • AnalyticsJSON 和 CSV 导出，支持 from/to 日期过滤。
  • Groups列表、创建、删除、分配码。
  • Webhooks列表、创建（含密钥）、删除，以及签名验证工具函数。
  • User/me，账户导出。

Admin、Stripe webhook 和基础设施端点有意排除在 SDK 范围外 — 仅用于服务间调用。完整端点列表见 OpenAPI 3.1 规范。

Postman 集合

一键导入 Postman 或 Insomnia：/docs/postman.json（每次部署时从 OpenAPI 规范重新生成）。每个请求均预配置了 bearer token 认证头模板 — 在集合级别设置一次 API 密钥，所有端点自动继承。

更喜欢原始 OpenAPI？Postman 原生支持 OpenAPI 3.1：File → Import → Link，粘贴 https://pro.qr.abundera.ai/docs/openapi.json。

版本控制策略

SDK 遵循 SemVer，独立于 API 版本管理。SDK 的 bug 修复（0.1.0 → 0.1.1）不改变 API 版本。API 的增量变更（新端点、新可选字段）不强制 SDK 主版本升级。

  • SDK patch（0.1.x）— bug 修复、文档更新，无公开 API 变更。可安全自动更新。
  • SDK minor（0.x.0）— 新方法覆盖新 API 端点，或符合人体工程学的增量。向后兼容。
  • SDK major（1.0.0 → 2.0.0）— 重命名、移除、类型结构变更。仅当 API 主版本升级，或修复长期存在的 SDK 人体工程学 bug 但无法在 minor 版本中发布时。

API 版本控制。URL 前缀是主版本号。当前为 /api/...（v1）。破坏性变更将发布为 /api/v2/...，v1 保留至少 12 个月，并在整个弃用窗口期间附带 Deprecation + Sunset 响应头。"破坏性"的完整定义见 /docs/changelog/。

支持窗口。当前主版本的最新 minor 版本接受安全修复。旧主版本可按请求为付费 Pro 客户提供安全补丁。

示例应用

展示码创建、目标更新、分析读取和 Webhook 签名验证的最简可运行应用：

  • node-express — TypeScript + Express，带重放保护的 Webhook 端点。
  • fastapi — Python 3.11 + FastAPI，集成签名验证工具函数。
  • gin — Go 1.21 + Gin，符合习惯的 handler 模式。
  • rails — Rails 7 + Sidekiq，Webhook handler 作为 Job。
  • laravel — Laravel 11，签名路由 Webhook 控制器。

每个示例均经过 CI 测试，针对模拟 API 验证。克隆后，设置 ABUNDERA_API_KEY 和 ABUNDERA_WEBHOOK_SECRET，然后运行。

没有找到你的语言？

OpenAPI 3.1 规范是权威来源。用 openapi-generator 生成任意语言的客户端，或自己封装一个薄包装, , API 很小（六个核心资源，bearer token 认证）。如果你希望我们为某种语言提供官方 SDK，请发邮件至 support@abundera.ai。