Offizielle SDKs

Typisierte Clients für die REST API in den fünf meistgefragten Sprachen. Jedes enthält Bearer-Token-Auth, exponentiellen Backoff-Retry bei 429 und 5xx, sowie einen verifyWebhookSignature-Helper für HMAC-SHA256-Verifizierung des X-Abundera-Signature-Headers. MIT-lizenziert.

Quelle der Wahrheit: /docs/openapi.json · Issues: support@abundera.ai

TS

TypeScript / Node

@abundera/qr-pro

Node 18+. Keine Runtime-Abhängigkeiten. ESM- und CJS-Builds.

Installieren

npm install @abundera/qr-pro

Code erstellen

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 verifizieren

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

verifyWebhookSignature({
  signature: req.headers["x-abundera-signature"],
  body: rawBody,
  secret: process.env.ABUNDERA_WEBHOOK_SECRET!,
});
// wirft bei ungültiger Signatur / Skew, sicher Body zu parsen nach dieser Zeile

Quellcode auf GitHub →

Py

Python

abundera-qr-pro

Python 3.9+. Einzelne Abhängigkeit (httpx). Synchrone und asynchrone Clients.

Installieren

pip install abundera-qr-pro

Code erstellen

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 verifizieren

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

Quellcode auf GitHub →

Go

Go

github.com/abundera/qr-pro-go

Go 1.21+. Nur Standardbibliothek. Kontextbewusst durchgehend.

Installieren

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

Code erstellen

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 verifizieren

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

Quellcode auf GitHub →

Rb

Ruby

abundera-qr-pro

Ruby 3.0+. Basiert auf Faraday. Funktioniert gut mit Rails-Initialisierern.

Installieren

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

Code erstellen

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 verifizieren

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

Quellcode auf GitHub →

PHP

PHP

abundera/qr-pro

PHP 8.1+. Funktioniert mit jedem PSR-18-HTTP-Client (Guzzle standardmäßig). Laravel- und Symfony-Service-Provider sind im selben Paket enthalten.

Installieren

composer require abundera/qr-pro

Code erstellen

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 verifizieren

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

Quellcode auf GitHub →

Was jedes SDK abdeckt

  • Codesauflisten, abrufen, erstellen, aktualisieren, löschen, Slug prüfen, importieren.
  • AnalyticsJSON- und CSV-Exporte mit from/to-Datumsfiltern.
  • Groupsauflisten, erstellen, löschen, Codes zuweisen.
  • Webhooksauflisten, erstellen (mit Secret), löschen, plus Signatur-Verifizierer-Helper.
  • User/me, Konto-Export.

Admin-, Stripe-Webhook- und Infra-Endpunkte sind absichtlich außerhalb des SDK-Scopes — nur Service-to-Service. Die vollständige Endpunktliste befindet sich in der OpenAPI 3.1 Spec.

Postman-Sammlung

Ein-Klick-Import in Postman oder Insomnia: /docs/postman.json (bei jedem Deploy aus der OpenAPI-Spec regeneriert). Jede Anfrage ist mit der Bearer-Token-Auth-Header-Vorlage vorkonfiguriert — API-Schlüssel einmal auf Sammlungsebene setzen und jeder Endpunkt erbt ihn.

Bevorzugen Sie rohes OpenAPI? Postman unterstützt OpenAPI 3.1 nativ: Datei → Importieren → Link, dann https://pro.qr.abundera.ai/docs/openapi.json einfügen.

Versionierungsrichtlinie

SDKs folgen SemVer und werden unabhängig von der API versioniert. Ein SDK-Bugfix (0.1.0 → 0.1.1) ändert nicht die API-Version. Eine additive API-Änderung (neuer Endpunkt, neues optionales Feld) erzwingt kein SDK-Major-Bump.

  • SDK-Patch (0.1.x) — Bugfix, Docs, keine öffentliche API-Änderung. Sicher zum Auto-Update.
  • SDK-Minor (0.x.0) — neue Methoden für neue API-Endpunkte oder ergonomische Ergänzungen. Rückwärtskompatibel.
  • SDK-Major (1.0.0 → 2.0.0) — Umbenennung, Entfernung, Typ-Form-Änderung. Nur wenn die API ein Major-Release hat oder bei einem langjährigen SDK-ergonomischen Bug, der nicht in einem Minor erscheinen kann.

API-Versionierung. Das URL-Präfix ist die Major-Version. Heute: /api/... (v1). Eine Breaking-Change wird als /api/v2/... ausgeliefert, v1 bleibt mindestens 12 Monate aktiv mit Deprecation- und Sunset-Antwort-Headern während des Deprecation-Fensters. Vollständige Definition von “breaking” unter /docs/changelog/.

Support-Fenster. Der neueste Minor auf dem aktuellen Major erhält Sicherheits-Fixes. Ältere Majors erhalten auf Anfrage Sicherheits-Patches für zahlende Pro-Kunden.

Beispiel-Apps

Minimale lauffähige Apps, die Code-Erstellung, Ziel-Update, Analytics-Abfrage und Webhook-Signatur-Verifizierung zeigen:

  • node-express — TypeScript + Express, Webhook-Endpunkt mit Replay-Schutz.
  • fastapi — Python 3.11 + FastAPI, Signatur-Verifizierer-Helper eingebunden.
  • gin — Go 1.21 + Gin, idiomatisches Handler-Muster.
  • rails — Rails 7 + Sidekiq, Webhook-Handler als Job.
  • laravel — Laravel 11, Signed-Route-Webhook-Controller.

Jedes Beispiel ist CI-getestet gegen eine gemockte API. Klonen, ABUNDERA_API_KEY und ABUNDERA_WEBHOOK_SECRET setzen, starten.

Ihre Sprache nicht dabei?

Die OpenAPI 3.1 Spec ist die Quelle der Wahrheit. Mit openapi-generator einen Client in beliebiger Sprache generieren oder selbst einen dünnen Wrapper schreiben — die API ist klein (sechs Kernressourcen, Bearer-Token-Auth). Für ein offizielles SDK einer Sprache, die wir noch nicht abdecken, E-Mail an support@abundera.ai.