Oficjalne SDK

Typowane klienty dla REST API w pięciu najczęściej proszonych językach. Każdy dostarczany z uwierzytelnianiem tokenem Bearer, ponowieniem z wykładniczym cofaniem przy 429 i 5xx oraz pomocnikiem verifyWebhookSignature do weryfikacji HMAC-SHA256 nagłówka X-Abundera-Signature. Licencja MIT.

Źródło prawdy: /docs/openapi.json · Problemy: support@abundera.ai

TS

TypeScript / Node

@abundera/qr-pro

Node 18+. Zero zależności runtime. Kompilacje ESM i CJS.

Instalacja

npm install @abundera/qr-pro

Utwórz kod

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

Zweryfikuj webhook

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

verifyWebhookSignature({
  signature: req.headers["x-abundera-signature"],
  body: rawBody,
  secret: process.env.ABUNDERA_WEBHOOK_SECRET!,
});
// rzuca wyjątek przy złym podpisie / przekroczeniu odchylenia, bezpieczne parsowanie treści po tej linii

Źródło na GitHub →

Py

Python

abundera-qr-pro

Python 3.9+. Jedna zależność (httpx). Klienty synchroniczny i asynchroniczny.

Instalacja

pip install abundera-qr-pro

Utwórz kod

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)

Zweryfikuj 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

Źródło na GitHub →

Go

Go

github.com/abundera/qr-pro-go

Go 1.21+. Tylko biblioteka standardowa. Obsługuje Context wszędzie.

Instalacja

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

Utwórz kod

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)

Zweryfikuj webhook

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

Źródło na GitHub →

Rb

Ruby

abundera-qr-pro

Ruby 3.0+. Zbudowane na Faraday. Dobrze współpracuje z inicjalizatorami Rails.

Instalacja

gem install abundera-qr-pro
# lub w Gemfile
gem "abundera-qr-pro"

Utwórz kod

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

Zweryfikuj 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

Źródło na GitHub →

PHP

PHP

abundera/qr-pro

PHP 8.1+. Działa z dowolnym klientem HTTP PSR-18 (Guzzle domyślnie). Providerzy usług Laravel i Symfony są w tym samym pakiecie.

Instalacja

composer require abundera/qr-pro

Utwórz kod

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;

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

Źródło na GitHub →

Co obejmuje każde SDK

  • Kodylista, pobieranie, tworzenie, aktualizacja, usuwanie, sprawdzanie skrótu, import.
  • Analitykaeksporty JSON i CSV z filtrami dat from/to.
  • Grupylista, tworzenie, usuwanie, przypisywanie kodów.
  • Webhookilista, tworzenie (z sekretem), usuwanie, plus pomocnik weryfikacji podpisu.
  • Użytkownik/me, eksport konta.

Endpointy administratora, webhooka Stripe i infrastruktury są celowo poza zakresem SDK — tylko komunikacja między serwisami. Pełna lista endpointów jest w specyfikacji OpenAPI 3.1.

Kolekcja Postman

Import jednym kliknięciem do Postmana lub Insomnii: /docs/postman.json (regenerowany ze specyfikacji OpenAPI przy każdym wdrożeniu). Każde żądanie jest wstępnie skonfigurowane z szablonem nagłówka uwierzytelniania tokenem Bearer — ustaw klucz API raz na poziomie kolekcji, a każdy endpoint go dziedziczy.

Wolisz surowy OpenAPI? Postman obsługuje OpenAPI 3.1 natywnie: Plik → Importuj → Link, a następnie wklej https://pro.qr.abundera.ai/docs/openapi.json.

Polityka wersjonowania

SDK stosują SemVer i są wersjonowane niezależnie od API. Poprawka SDK (0.1.0 → 0.1.1) nie zmienia wersji API. Addytywna zmiana API (nowy endpoint, nowe opcjonalne pole) nie wymusza głównego bumpa SDK.

  • Patch SDK (0.1.x) — poprawka błędu, dokumentacja, brak zmiany publicznego API. Bezpieczne do automatycznej aktualizacji.
  • Minor SDK (0.x.0) — nowe metody dla nowych endpointów API lub ergonomiczne dodatki. Wstecznie kompatybilne.
  • Major SDK (1.0.0 → 2.0.0) — zmiana nazwy, usunięcie, zmiana kształtu typów. Tylko gdy API ma major lub gdy naprawiamy długo stojący błąd ergonomiczny SDK niemożliwy do wdrożenia w minor.

Wersjonowanie API. Prefiks URL to wersja główna. Dziś: /api/... (v1). Przełomowa zmiana jest dostarczana jako /api/v2/..., z v1 utrzymywanym co najmniej 12 miesięcy i nagłówkami odpowiedzi Deprecation + Sunset przez cały okres wycofywania. Pełna definicja „przełomowy” pod /docs/changelog/.

Okno wsparcia. Najnowszy minor na bieżącym major otrzymuje poprawki bezpieczeństwa. Starsze majory otrzymują łatki bezpieczeństwa na żądanie dla płatnych klientów Pro.

Przykładowe aplikacje

Minimalne uruchamialne aplikacje pokazujące tworzenie kodu, aktualizację celu, odczyt analityki i weryfikację podpisu webhooka:

  • node-express — TypeScript + Express, endpoint webhooka z ochroną przed odtwarzaniem.
  • fastapi — Python 3.11 + FastAPI, pomocnik weryfikacji podpisu podłączony.
  • gin — Go 1.21 + Gin, idiomatyczny wzorzec handlera.
  • rails — Rails 7 + Sidekiq, handler webhooka jako job.
  • laravel — Laravel 11, kontroler webhooka z podpisaną trasą.

Każdy przykład jest testowany CI względem makowanego API. Klonuj, ustaw ABUNDERA_API_KEY i ABUNDERA_WEBHOOK_SECRET, uruchom.

Nie widzisz swojego języka?

Specyfikacja OpenAPI 3.1 jest źródłem prawdy. Wygeneruj klienta w dowolnym języku za pomocą openapi-generator lub napisz cienką nakładkę sam — API jest małe (sześć głównych zasobów, uwierzytelnianie tokenem Bearer). Jeśli chcesz oficjalnego SDK dla języka, którego nie obsługujemy, napisz na support@abundera.ai.