SDKs & CLI

SDKs & CLI

qr3.app bietet offizielle Tools für Entwickler:

TypeScript/JavaScript SDK

@qr3/sdk — Für Web, Node.js, Cloudflare Workers

CLI

@qr3/cli — Für Automatisierung und Scripting

MCP Server

@qr3/mcp-server — Für Claude, Cursor und andere AI-Tools

TypeScript/JavaScript SDK

Installation

npm install @qr3/sdk
# oder
pnpm add @qr3/sdk

Grundlegende Verwendung

import { QR3 } from "@qr3/sdk";

const client = new QR3({
  apiKey: process.env.QR3_API_KEY,
  // Optional:
  // baseUrl: "https://qr3.app/v1",
  // workspaceId: "ws_xxx",  // Standardmäßig aktiver Workspace
});

// QR-Code erstellen
const code = await client.codes.create({
  type: "url",
  url: "https://example.com",
});

// QR-Codes auflisten
const { data, meta } = await client.codes.list({ limit: 10 });

// Scans abrufen
const stats = await client.scans.stats(code.id);

// Webhooks verwalten
const webhook = await client.webhooks.create({
  url: "https://example.com/webhooks",
  events: ["qr.scanned"],
  secret: "my-secret-key",
});

Error Handling

import { QR3AuthError, QR3NotFoundError, QR3RateLimitError } from "@qr3/sdk";

try {
  const code = await client.codes.get("qr_nonexistent");
} catch (err) {
  if (err instanceof QR3NotFoundError) {
    console.log("QR-Code nicht gefunden");
  } else if (err instanceof QR3AuthError) {
    console.log("Ungültiger API-Key");
  } else if (err instanceof QR3RateLimitError) {
    console.log(`Rate-Limit — Retry nach: ${err.retryAfter}s`);
  }
}

---

CLI (qr3)

Installation

npm install -g @qr3/cli

Authentifizierung

qr3 login
# Gibt deinen API-Key ein (wird sicher in ~/.qr3/config.json gespeichert)

Befehle

# QR-Code erstellen
qr3 create https://example.com --title "Mein Code" --tags marketing,q1

# QR-Codes auflisten
qr3 list --status live --limit 20

# Details anzeigen
qr3 get qr_xxx

# Statistiken
qr3 stats qr_xxx

# Ziel-URL ändern
qr3 update qr_xxx --url https://new-url.com

# Löschen (mit Bestätigung)
qr3 delete qr_xxx

# Massen-Import aus CSV
qr3 bulk create --csv codes.csv --dry-run

CSV-Format für Massen-Import

url,type,tags,notes,is_dynamic
https://product-1.example.com,url,catalog;q1,Produkt 1,true
https://product-2.example.com,url,catalog;q1,Produkt 2,true

JSON-Ausgabe für Scripting

Alle Befehle unterstützen --json für maschinenlesbare Ausgabe:

qr3 create https://example.com --json | jq '.short_url'

---

MCP-Server für AI-Assistenten

Der MCP-Server ermöglicht es Claude, Cursor und anderen AI-Tools, direkt mit qr3.app zu interagieren.

Claude Desktop

Füge folgendes zu ~/Library/Application Support/Claude/claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "qr3": {
      "url": "https://mcp.qr3.app/mcp",
      "headers": {
        "Authorization": "Bearer qr3_sk_your_key"
      }
    }
  }
}

Cursor

Füge folgendes zu .cursor/mcp.json hinzu:

{
  "mcpServers": {
    "qr3": {
      "url": "https://mcp.qr3.app/mcp",
      "headers": {
        "Authorization": "Bearer qr3_sk_your_key"
      }
    }
  }
}

Verfügbare Tools

Tool	Beschreibung
create_qr	URL-QR-Code erstellen
create_vcard_qr	Visitenkarten-QR erstellen
create_wifi_qr	WLAN-QR erstellen
update_qr	QR-Code aktualisieren
list_qrs	QR-Codes auflisten und suchen
get_qr_stats	Scan-Statistiken abrufen
create_batch	Mehrere QR-Codes erstellen (bis 50)
get_image	QR-Bild-URL oder Base64 abrufen
shorten_url	URL kürzen