SDKs oficiais

Clientes tipados sobre a REST API para os cinco idiomas mais solicitados. Cada um vem com autenticação por bearer token, retry com backoff exponencial em 429 e 5xx, e um helper verifyWebhookSignature para verificação HMAC-SHA256 do cabeçalho X-Abundera-Signature. Licença MIT.

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

TS

TypeScript / Node

@abundera/qr-pro

Node 18+. Zero dependências em runtime. Builds ESM e CJS.

Instalação

npm install @abundera/qr-pro

Criar um código

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

Verificar um webhook

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

verifyWebhookSignature({
  signature: req.headers["x-abundera-signature"],
  body: rawBody,
  secret: process.env.ABUNDERA_WEBHOOK_SECRET!,
});
// lança exceção em assinatura inválida / skew, seguro analisar o body após esta linha

Código no GitHub →

Py

Python

abundera-qr-pro

Python 3.9+. Dependência única (httpx). Clientes síncronos e assíncronos.

Instalação

pip install abundera-qr-pro

Criar um código

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)

Verificar um 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

Código no GitHub →

Go

Go

github.com/abundera/qr-pro-go

Go 1.21+. Apenas biblioteca padrão. Context-aware em todo lugar.

Instalação

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

Criar um código

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)

Verificar um webhook

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
}

Código no GitHub →

Rb

Ruby

abundera-qr-pro

Ruby 3.0+. Construído sobre Faraday. Funciona bem com inicializadores Rails.

Instalação

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

Criar um código

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

Verificar um 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

Código no GitHub →

PHP

PHP

abundera/qr-pro

PHP 8.1+. Funciona com qualquer cliente HTTP PSR-18 (Guzzle por padrão). Service providers para Laravel e Symfony estão no mesmo pacote.

Instalação

composer require abundera/qr-pro

Criar um código

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;

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

Código no GitHub →

O que cada SDK cobre

  • Códigoslistar, obter, criar, atualizar, excluir, verificar slug, importar.
  • Analyticsexportações JSON e CSV com filtros de data from/to.
  • Gruposlistar, criar, excluir, atribuir códigos.
  • Webhookslistar, criar (com segredo), excluir, mais um helper de verificação de assinatura.
  • Usuário/me, exportação de conta.

Endpoints admin, webhook Stripe e infra são intencionalmente fora do escopo dos SDKs — são apenas service-to-service. A lista completa de endpoints está na especificação OpenAPI 3.1.

Coleção Postman

Importação com um clique no Postman ou Insomnia: /docs/postman.json (regenerado a partir da spec OpenAPI em cada deploy). Cada requisição está pré-configurada com o template de cabeçalho de auth por bearer token — defina sua chave de API uma vez no nível da coleção e cada endpoint a herda.

Prefere OpenAPI bruto? O Postman suporta OpenAPI 3.1 nativamente: File → Import → Link, depois cole https://pro.qr.abundera.ai/docs/openapi.json.

Política de versionamento

Os SDKs seguem SemVer e são versionados independentemente da API. Uma correção de bug no SDK (0.1.0 → 0.1.1) não altera a versão da API. Uma mudança aditiva na API (novo endpoint, novo campo opcional) não força um bump major no SDK.

  • SDK patch (0.1.x) — correção de bug, docs, sem mudança de API pública. Seguro para atualização automática.
  • SDK minor (0.x.0) — novos métodos para cobrir novos endpoints de API ou adições ergonômicas. Retrocompatível.
  • SDK major (1.0.0 → 2.0.0) — renomeação, remoção, mudança de shape de tipo. Apenas quando a API faz um major, ou ao corrigir um bug ergonômico de longa data no SDK que não pode ser enviado em um minor.

Versionamento da API. O prefixo da URL é a versão major. Hoje: /api/... (v1). Uma mudança incompatível é entregue como /api/v2/..., com v1 mantido por pelo menos 12 meses e cabeçalhos de resposta Deprecation + Sunset durante a janela de deprecação. Definição completa de “incompatível” em /docs/changelog/.

Janela de suporte. O minor mais recente no major atual recebe correções de segurança. Majors mais antigos recebem patches de segurança sob demanda para clientes Pro pagantes.

Aplicativos de exemplo

Aplicativos mínimos executáveis mostrando criação de código, atualização de destino, leitura de analytics e verificação de assinatura de webhook:

  • node-express — TypeScript + Express, endpoint de webhook com proteção contra replay.
  • fastapi — Python 3.11 + FastAPI, helper de verificação de assinatura integrado.
  • gin — Go 1.21 + Gin, padrão idiomático de handler.
  • rails — Rails 7 + Sidekiq, handler de webhook como job.
  • laravel — Laravel 11, controller de webhook com rota assinada.

Cada exemplo é testado por CI contra uma API mockada. Clone, defina ABUNDERA_API_KEY e ABUNDERA_WEBHOOK_SECRET, execute.

Não encontrou seu idioma de programação?

The OpenAPI 3.1 spec is the source of truth. Generate a client in any language with openapi-generator, or write a thin wrapper yourself — the API is small (six core resources, bearer-token auth). If you’d like an official SDK for a language we don’t cover, email support@abundera.ai.