공식 SDK

가장 많이 요청된 5개 언어용 REST API 타입 클라이언트. 각각 Bearer 토큰 인증, 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);

웹훅 검증

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)

웹훅 검증

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+. 표준 라이브러리만 사용. 전체적으로 컨텍스트 인식.

설치

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)

웹훅 검증

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
}

GitHub에서 소스 보기 →

Rb

Ruby

abundera-qr-pro

Ruby 3.0+. Faraday 기반. Rails 이니셜라이저와 잘 작동합니다.

설치

gem install abundera-qr-pro
# or in 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

웹훅 검증

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;

웹훅 검증

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

Source on GitHub →

모든 SDK가 다루는 것

  • 코드나열, 가져오기, 생성, 업데이트, 삭제, 슬러그 확인, 임포트.
  • 분석from/to 날짜 필터가 있는 JSON 및 CSV 내보내기.
  • 그룹나열, 생성, 삭제, 코드 할당.
  • 웹훅나열, 생성 (시크릿 포함), 삭제, 서명 검증 헬퍼.
  • 사용자/me, 계정 내보내기.

관리자, Stripe 웹훅, 인프라 엔드포인트는 의도적으로 SDK 범위 외입니다, 서비스 간 전용. 전체 엔드포인트 목록은 OpenAPI 3.1 스펙에 있습니다.

Postman 컬렉션

Postman 또는 Insomnia에 원클릭 임포트: /docs/postman.json (배포마다 OpenAPI 스펙에서 재생성). 모든 요청은 Bearer 토큰 인증 헤더 템플릿으로 사전 설정 — 컬렉션 수준에서 API 키를 한 번 설정하면 모든 엔드포인트가 상속합니다.

원본 OpenAPI를 선호하시나요? Postman은 OpenAPI 3.1을 기본 지원합니다: File → Import → Link 후 https://pro.qr.abundera.ai/docs/openapi.json를 붙여넣으세요.

버전 관리 정책

SDK는 SemVer을 따르며 API와 독립적으로 버전이 관리됩니다. SDK 버그픽스 (0.1.0 → 0.1.1)는 API 버전을 변경하지 않습니다. 추가적인 API 변경 (새 엔드포인트, 새 선택 필드)은 SDK 메이저 버전 증가를 강제하지 않습니다.

  • SDK 패치 (0.1.x) — 버그픽스, 문서, 공개 API 변경 없음. 자동 업데이트 안전.
  • SDK 마이너 (0.x.0) — 새 API 엔드포인트 커버를 위한 새 메서드 또는 사용성 개선. 하위 호환.
  • SDK 메이저 (1.0.0 → 2.0.0) — 이름 변경, 제거, 타입 형태 변경. API 메이저 버전 변경 시, 또는 마이너로 출시할 수 없는 오래된 SDK 사용성 버그 수정 시만.

API 버전 관리. URL 접두사가 메이저 버전입니다. 현재: /api/... (v1). 호환성 깨는 변경은 /api/v2/...로 출시되며, v1은 최소 12개월 유지되고 지원 중단 기간 동안 Deprecation + Sunset 응답 헤더가 포함됩니다. "호환성 깨는"의 전체 정의는 /docs/changelog/에.

지원 기간. 현재 메이저의 최신 마이너가 보안 수정을 받습니다. 이전 메이저는 유료 Pro 고객 요청 시 보안 패치를 받습니다.

예제 앱

코드 생성, 대상 업데이트, 분석 읽기, 웹훅 서명 검증을 보여주는 최소 실행 가능 앱:

  • node-express — TypeScript + Express, 재전송 방지 웹훅 엔드포인트.
  • fastapi — Python 3.11 + FastAPI, 서명 검증 헬퍼 연결됨.
  • gin — Go 1.21 + Gin, 관용적 핸들러 패턴.
  • rails — Rails 7 + Sidekiq, 작업으로서의 웹훅 핸들러.
  • laravel — Laravel 11, 서명된 라우트 웹훅 컨트롤러.

각 예제는 모의 API에 대해 CI 테스트됩니다. 클론하고 ABUNDERA_API_KEY와 ABUNDERA_WEBHOOK_SECRET을 설정하고 실행하세요.

원하는 언어가 없나요?

OpenAPI 3.1 스펙이 진실의 원천입니다. openapi-generator로 어떤 언어로든 클라이언트를 생성하거나, 직접 얇은 래퍼를 작성하세요 — API는 작습니다 (6개 핵심 리소스, Bearer 토큰 인증). 미지원 언어의 공식 SDK가 필요하면 support@abundera.ai로 이메일을 보내세요.