SDK chính thức

Client có kiểu dữ liệu trên REST API cho năm ngôn ngữ được yêu cầu nhiều nhất. Mỗi cái đi kèm xác thực bearer token, thử lại exponential-backoff trên 429 và 5xx, và helper verifyWebhookSignature để xác minh HMAC-SHA256 header X-Abundera-Signature. Giấy phép MIT.

Nguồn sự thật: /docs/openapi.json · Vấn đề: support@abundera.ai

TS

TypeScript / Node

@abundera/qr-pro

Node 18+. Không phụ thuộc runtime. Build ESM và CJS.

Cài đặt

npm install @abundera/qr-pro

Tạo mã

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);

Xác minh webhook

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

verifyWebhookSignature({
  signature: req.headers["x-abundera-signature"],
  body: rawBody,
  secret: process.env.ABUNDERA_WEBHOOK_SECRET!,
});
// throws on bad signature / skew, safe to parse body after this line

Nguồn trên GitHub →

Py

Python

abundera-qr-pro

Python 3.9+. Một phụ thuộc (httpx). Client đồng bộ và bất đồng bộ.

Cài đặt

pip install abundera-qr-pro

Tạo mã

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)

Xác minh 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

Nguồn trên GitHub →

Go

Go

github.com/abundera/qr-pro-go

Go 1.21+. Chỉ thư viện chuẩn. Nhận thức ngữ cảnh xuyên suốt.

Cài đặt

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

Tạo mã

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)

Xác minh webhook

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

Nguồn trên GitHub →

Rb

Ruby

abundera-qr-pro

Ruby 3.0+. Xây dựng trên Faraday. Hoạt động tốt với initialiser Rails.

Cài đặt

gem install abundera-qr-pro
# or in Gemfile
gem "abundera-qr-pro"

Tạo mã

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

Xác minh 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

Nguồn trên GitHub →

PHP

PHP

abundera/qr-pro

PHP 8.1+. Hoạt động với bất kỳ HTTP client PSR-18 nào (Guzzle theo mặc định). Service provider Laravel và Symfony đi kèm trong cùng gói.

Cài đặt

composer require abundera/qr-pro

Tạo mã

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;

Xác minh 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;
}

Nguồn trên GitHub →

Những gì mỗi SDK bao gồm

  • Codesliệt kê, lấy, tạo, cập nhật, xóa, kiểm tra slug, nhập.
  • Analyticsxuất JSON và CSV với bộ lọc ngày from/to.
  • Groupsliệt kê, tạo, xóa, gán mã.
  • Webhooksliệt kê, tạo (với secret), xóa, cộng thêm helper xác minh chữ ký.
  • User/me, xuất tài khoản.

Endpoint Admin, Stripe-webhook và hạ tầng được loại trừ có chủ ý khỏi SDK, chúng chỉ dùng giữa các dịch vụ. Danh sách endpoint đầy đủ trong đặc tả OpenAPI 3.1.

Bộ sưu tập Postman

Nhập một cú nhấp vào Postman hoặc Insomnia: /docs/postman.json (được tạo lại từ đặc tả OpenAPI mỗi lần deploy). Mỗi yêu cầu được cấu hình sẵn với template header xác thực bearer token, đặt khóa API một lần ở cấp bộ sưu tập và mỗi endpoint kế thừa nó.

Thích OpenAPI thô? Postman hỗ trợ OpenAPI 3.1 nguyên gốc: File → Import → Link, sau đó dán https://pro.qr.abundera.ai/docs/openapi.json.

Chính sách phiên bản

SDK tuân theo SemVer và được phiên bản độc lập với API. Sửa lỗi SDK (0.1.0 → 0.1.1) không thay đổi phiên bản API. Thay đổi API bổ sung (endpoint mới, trường tùy chọn mới) không buộc bump major SDK.

  • Patch SDK (0.1.x) — sửa lỗi, tài liệu, không thay đổi public-API. An toàn để tự động cập nhật.
  • Minor SDK (0.x.0) — phương thức mới để bao gồm endpoint API mới hoặc bổ sung tiện dụng. Tương thích ngược.
  • Major SDK (1.0.0 → 2.0.0) — đổi tên, xóa, thay đổi kiểu dữ liệu. Chỉ khi API major, hoặc khi sửa lỗi tiện dụng SDK lâu dài không thể đưa vào minor.

Phiên bản API. Tiền tố URL là phiên bản major. Hiện tại: /api/... (v1). Thay đổi gây hỏng được phát hành là /api/v2/..., với v1 được giữ hoạt động ít nhất 12 tháng và header phản hồi Deprecation + Sunset trong suốt cửa sổ ngừng sử dụng. Định nghĩa đầy đủ về "gây hỏng" tại /docs/changelog/.

Cửa sổ hỗ trợ. Minor mới nhất trên major hiện tại nhận sửa lỗi bảo mật. Major cũ hơn nhận bản vá bảo mật theo yêu cầu cho khách hàng Pro trả phí.

Ứng dụng ví dụ

Ứng dụng chạy được tối thiểu hiển thị tạo mã, cập nhật đích đến, đọc phân tích và xác minh chữ ký webhook:

  • node-express — TypeScript + Express, endpoint webhook với bảo vệ replay.
  • fastapi — Python 3.11 + FastAPI, helper xác minh chữ ký được tích hợp.
  • gin — Go 1.21 + Gin, mẫu handler thành ngữ.
  • rails — Rails 7 + Sidekiq, handler webhook dưới dạng job.
  • laravel — Laravel 11, controller webhook signed-route.

Mỗi ví dụ được kiểm tra CI với API giả. Clone, đặt ABUNDERA_API_KEY và ABUNDERA_WEBHOOK_SECRET, chạy.

Không thấy ngôn ngữ của bạn?

Đặc tả OpenAPI 3.1 là nguồn sự thật. Tạo client bằng bất kỳ ngôn ngữ nào với openapi-generator, hoặc tự viết wrapper mỏng — API nhỏ (sáu tài nguyên cốt lõi, xác thực bearer token). Nếu bạn muốn SDK chính thức cho ngôn ngữ chúng tôi chưa hỗ trợ, email support@abundera.ai.