SDK ufficiali

Client tipizzati sull'API REST per i cinque linguaggi più richiesti. Ognuno include autenticazione bearer token, retry con backoff esponenziale su 429 e 5xx, e un helper verifyWebhookSignature per la verifica HMAC-SHA256 dell'header X-Abundera-Signature. Licenza MIT.

Fonte: /docs/openapi.json · Problemi: support@abundera.ai

TS

TypeScript / Node

@abundera/qr-pro

Node 18+. Zero dipendenze runtime. Build ESM e CJS.

Installa

npm install @abundera/qr-pro

Crea un codice

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: "Poster lancio primavera",
});

console.log(code.short_url);

Verifica un webhook

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

verifyWebhookSignature({
  signature: req.headers["x-abundera-signature"],
  body: rawBody,
  secret: process.env.ABUNDERA_WEBHOOK_SECRET!,
});
// lancia un'eccezione su firma errata / skew, sicuro fare il parse del body dopo questa riga

Sorgente su GitHub →

Py

Python

abundera-qr-pro

Python 3.9+. Dipendenza singola (httpx). Client sincrono e asincrono.

Installa

pip install abundera-qr-pro

Crea un codice

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="Poster lancio primavera",
    )
    print(code.short_url)

Verifica un 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

Sorgente su GitHub →

Go

Go

github.com/abundera/qr-pro-go

Go 1.21+. Solo libreria standard. Context-aware ovunque.

Installa

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

Crea un codice

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:          "Poster lancio primavera",
})
if err != nil { log.Fatal(err) }
fmt.Println(code.ShortURL)

Verifica un webhook

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

Sorgente su GitHub →

Rb

Ruby

abundera-qr-pro

Ruby 3.0+. Costruito su Faraday. Si integra bene con gli initializer Rails.

Installa

gem install abundera-qr-pro
# oppure nel Gemfile
gem "abundera-qr-pro"

Crea un codice

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: "Poster lancio primavera",
)

puts code.short_url

Verifica un 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

Sorgente su GitHub →

PHP

PHP

abundera/qr-pro

PHP 8.1+. Funziona con qualsiasi client HTTP PSR-18 (Guzzle per default). I service provider per Laravel e Symfony sono inclusi nello stesso package.

Installa

composer require abundera/qr-pro

Crea un codice

use Abundera\QrPro\Client;

$client = new Client(apiKey: getenv('ABUNDERA_API_KEY'));

$code = $client->createCode(
    destinationUrl: 'https://example.com/launch',
    label: 'Poster lancio primavera',
);

echo $code->shortUrl;

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

Sorgente su GitHub →

Cosa copre ogni SDK

  • Codicielenco, get, crea, aggiorna, elimina, verifica slug, importa.
  • Analyticsesportazioni JSON e CSV con filtri data from/to.
  • Gruppielenco, crea, elimina, assegna codici.
  • Webhookelenco, crea (con segreto), elimina, più helper di verifica firma.
  • Utente/me, esportazione account.

Gli endpoint Admin, Stripe-webhook e infra sono intenzionalmente fuori scope per gli SDK — sono solo service-to-service. La lista completa degli endpoint è nella spec OpenAPI 3.1.

Collezione Postman

Import con un clic in Postman o Insomnia: /docs/postman.json (rigenerato dalla spec OpenAPI ad ogni deploy). Ogni richiesta è preconfigurata con il template dell'header di autenticazione bearer token — imposta la tua chiave API una volta a livello di collezione e ogni endpoint la eredita.

Preferisci OpenAPI grezzo? Postman supporta OpenAPI 3.1 nativamente: File → Import → Link, poi incolla https://pro.qr.abundera.ai/docs/openapi.json.

Policy di versionamento

Gli SDK seguono SemVer e sono versionati indipendentemente dall'API. Un bugfix SDK (0.1.0 → 0.1.1) non cambia la versione API. Una modifica API additiva (nuovo endpoint, nuovo campo opzionale) non forza un major bump dell'SDK.

  • SDK patch (0.1.x) — bugfix, docs, nessuna modifica all'API pubblica. Sicuro per l'aggiornamento automatico.
  • SDK minor (0.x.0) — nuovi metodi per nuovi endpoint API, o aggiunte ergonomiche. Retrocompatibile.
  • SDK major (1.0.0 → 2.0.0) — rinomina, rimozione, cambio di tipo. Solo quando l'API effettua un major, o quando si corregge un bug ergonomico SDK consolidato che non può essere spedito in un minor.

Versionamento API. Il prefisso URL è la versione major. Oggi: /api/... (v1). Una modifica breaking viene spedita come /api/v2/..., con v1 mantenuto attivo almeno 12 mesi e header di risposta Deprecation + Sunset per tutta la finestra di deprecazione. Definizione completa di “breaking” su /docs/changelog/.

Finestra di supporto. L'ultimo minor sul major corrente riceve correzioni di sicurezza. I major precedenti ricevono patch di sicurezza su richiesta per i clienti Pro a pagamento.

App di esempio

App minimali eseguibili che mostrano creazione codice, aggiornamento destinazione, lettura analytics e verifica firma webhook:

  • node-express — TypeScript + Express, endpoint webhook con protezione replay.
  • fastapi — Python 3.11 + FastAPI, helper di verifica firma integrato.
  • gin — Go 1.21 + Gin, pattern handler idiomatico.
  • rails — Rails 7 + Sidekiq, handler webhook come job.
  • laravel — Laravel 11, controller webhook con rotta firmata.

Ogni esempio è testato su CI contro un'API mockata. Clona, imposta ABUNDERA_API_KEY e ABUNDERA_WEBHOOK_SECRET, avvia.

Non trovi il tuo linguaggio?

La spec OpenAPI 3.1 è la fonte di verità. Genera un client in qualsiasi linguaggio con openapi-generator, o scrivi un wrapper sottile tu stesso — l'API è piccola (sei risorse core, autenticazione bearer token). Se vuoi un SDK ufficiale per un linguaggio che non copriamo, email support@abundera.ai.