Oficiální SDK

Typované klienty nad REST API pro pět nejžádanějších jazyků. Každý dodáváme s ověřováním bearer tokenem, exponenciálním opakováním na 429 a 5xx a pomocnou funkcí verifyWebhookSignature pro ověření HMAC-SHA256 hlavičky X-Abundera-Signature. Licence MIT.

Zdroj pravdy: /docs/openapi.json · Problémy: support@abundera.ai

TS

TypeScript / Node

@abundera/qr-pro

Node 18+. Žádné závislosti za běhu. Sestavení ESM a CJS.

Instalace

npm install @abundera/qr-pro

Vytvoření kódu

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

Ověření webhooku

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

verifyWebhookSignature({
  signature: req.headers["x-abundera-signature"],
  body: rawBody,
  secret: process.env.ABUNDERA_WEBHOOK_SECRET!,
});
// vyvolá výjimku při špatném podpisu / skluzu, bezpečné parsovat tělo po tomto řádku

Zdrojový kód na GitHubu →

Py

Python

abundera-qr-pro

Python 3.9+. Jediná závislost (httpx). Synchronní a asynchronní klienti.

Instalace

pip install abundera-qr-pro

Vytvoření kódu

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)

Ověření webhooku

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

Zdrojový kód na GitHubu →

Go

Go

github.com/abundera/qr-pro-go

Go 1.21+. Pouze standardní knihovna. Kontextově uvědomělý po celou dobu.

Instalace

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

Vytvoření kódu

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)

Ověření webhooku

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
}

Zdrojový kód na GitHubu →

Rb

Ruby

abundera-qr-pro

Ruby 3.0+. Postaveno na Faraday. Dobře spolupracuje s Rails initializers.

Instalace

gem install abundera-qr-pro
# nebo v Gemfile
gem "abundera-qr-pro"

Vytvoření kódu

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

Ověření webhooku

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

Zdrojový kód na GitHubu →

PHP

PHP

abundera/qr-pro

PHP 8.1+. Funguje s libovolným PSR-18 HTTP klientem (Guzzle ve výchozím nastavení). Poskytovatele služeb Laravel a Symfony jsou ve stejném balíčku.

Instalace

composer require abundera/qr-pro

Vytvoření kódu

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;

Ověření webhooku

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

Zdrojový kód na GitHubu →

Co každý SDK pokrývá

  • Kódyseznam, načtení, vytvoření, aktualizace, smazání, kontrola slugu, import.
  • Analytikaexport JSON a CSV s filtry data from/to.
  • Skupinyseznam, vytvoření, smazání, přiřazení kódů.
  • Webhookyseznam, vytvoření (s tajemstvím), smazání, plus pomocná funkce pro ověření podpisu.
  • Uživatel/me, export účtu.

Endpointy Admin, Stripe-webhook a infra jsou záměrně mimo rozsah SDK, jsou pouze pro komunikaci mezi službami. Úplný seznam endpointů je ve specifikaci OpenAPI 3.1.

Postman kolekce

Import jedním kliknutím do Postmanu nebo Insomnie: /docs/postman.json (regenerováno ze specifikace OpenAPI při každém nasazení). Každý požadavek je předkonfigurován šablonou hlavičky ověřování bearer tokenem — nastavte API klíč jednou na úrovni kolekce a každý endpoint ho zdědí.

Preferujete surové OpenAPI? Postman podporuje OpenAPI 3.1 nativně: Soubor → Import → Odkaz, pak vložte https://pro.qr.abundera.ai/docs/openapi.json.

Politika verzování

SDK řídí SemVer a jsou verzovány nezávisle na API. Oprava chyby SDK (0.1.0 → 0.1.1) nemění verzi API. Přidávací změna API (nový endpoint, nové volitelné pole) nevynucuje hlavní nárůst verze SDK.

  • SDK patch (0.1.x) — oprava chyby, dokumentace, žádná změna veřejného API. Bezpečné pro automatickou aktualizaci.
  • SDK minor (0.x.0) — nové metody pro nové API endpointy nebo ergonomické přídavky. Zpětně kompatibilní.
  • SDK major (1.0.0 → 2.0.0) — přejmenování, odstranění, změna tvarů typů. Pouze při hlavní verzi API nebo při opravě dlouhotrvající ergonomické chyby SDK, která nelze shippovat v minor verzi.

Verzování API. Prefix URL je hlavní verze. Dnes: /api/... (v1). Narušující změna se dodává jako /api/v2/..., přičemž v1 zůstane naživu alespoň 12 měsíců s hlavičkami odpovědí Deprecation + Sunset po celou dobu odepisování. Úplná definice "narušující" na /docs/changelog/.

Okno podpory. Nejnovější minor na aktuálním major dostává bezpečnostní opravy. Starší major verze dostávají bezpečnostní záplaty na vyžádání pro platící Pro zákazníky.

Ukázkové aplikace

Minimální spustitelné aplikace ukazující vytvoření kódu, aktualizaci cíle, čtení analytiky a ověření podpisu webhooku:

  • node-express — TypeScript + Express, webhook endpoint s ochranou přehrání.
  • fastapi — Python 3.11 + FastAPI, pomocná funkce ověření podpisu zapojena.
  • gin — Go 1.21 + Gin, idiomatický vzor handleru.
  • rails — Rails 7 + Sidekiq, webhook handler jako job.
  • laravel — Laravel 11, webhook kontroler s podepsanou cestou.

Každý příklad je testován CI vůči mockovanému API. Naklonujte, nastavte ABUNDERA_API_KEY a ABUNDERA_WEBHOOK_SECRET, spusťte.

Nevidíte svůj jazyk?

Specifikace OpenAPI 3.1 je zdrojem pravdy. Vygenerujte klienta v libovolném jazyce pomocí openapi-generator nebo napište tenký wrapper sami — API je malé (šest základních zdrojů, ověřování bearer tokenem). Pokud byste chtěli oficiální SDK pro jazyk, který nepokrýváme, napište na support@abundera.ai.