Anbindung in fünf Minuten.

Scan Gogh hat zwei programmatische Zugänge auf demselben Renderer: MCP für KI-Clients, REST für alles andere. Beide brauchen einen API-Key, den wir pro Mandant ausgeben — auf Anfrage auch für dein Projekt.

Zugang anfragen. Scan Gogh kommt bewusst ohne Selbstregistrierung: Jeden Mandanten richten wir persönlich ein — mit eigenem Kontingent, eigenen Presets und eigenem Logo. Sag uns kurz, wofür du die Schnittstelle nutzen möchtest, und wir schalten dich gerne frei. Der Key wird genau einmal angezeigt und bei uns ausschließlich als Hash gespeichert; im Klartext versenden wir ihn nie.

Zugang anfragen

MCP — Claude, Claude Code, Cursor

Der Endpunkt ist https://scan-gogh.na15.io/mcp, Transport ist Streamable HTTP nach Revision 2026-07-28 (zustandslos). Ältere Clients auf der 2025er Ära werden vom selben Endpunkt mitbedient.

Claude Code, Cursor, Windsurf

claude mcp add --transport http qr \
  https://scan-gogh.na15.io/mcp \
  --header "Authorization: Bearer $NA15_QR_KEY"

Claude Desktop, claude.ai, Cowork

Als Custom Connector mit der URL https://scan-gogh.na15.io/mcp hinzufügen. Drei Einstellungen sind dabei entscheidend:

Authentifizierung: Keine. Claude schlägt von sich aus „Immer erforderlich“ vor, weil unser Endpunkt auf einen Aufruf ohne Key mit einem WWW-Authenticate-Header antwortet. Einen OAuth-Server gibt es dahinter aber nicht — die Anmeldung läuft über den Key im Header.
Zusätzlicher Anfrage-Header: x-api-key aus der Auswahlliste. Der Name authorization steht dort nicht zur Wahl, er ist für das OAuth-Token reserviert.
Wert: der Key pur, also na15_qr_live_… — ohne Bearer davor. Das ist der häufigste Fehler beim Einrichten.

Der Key gehört damit dem Konto beziehungsweise der Organisation, die den Connector anlegt, nicht einzelnen Chats.

Werkzeuge

Tool	Wofür	Pflichtparameter
`qr_generate_url`	Der häufigste Fall: QR-Code für eine Webadresse	`url`
`qr_generate_wifi`	WLAN-Zugang, Sonderzeichen werden korrekt maskiert	`ssid`
`qr_generate_vcard`	Kontaktkarte als vCard 3.0	`name`
`qr_generate`	Universell, mit `input` oder fertigem `content`	eines von beiden
`qr_validate`	Kapazität, Kontrast und Logo/EC-Verhältnis prüfen, ohne zu rendern	—
`qr_list_styles`	Verfügbare Stile, Paletten und Presets	—

Dazu die Ressourcen qr://styles, qr://tenant/presets und qr://docs/quickstart sowie die Prompts brand-qr und print-ready.

Was zurückkommt

Jedes Ergebnis enthält dreierlei: das Bild, einen Link darauf und eine Zusammenfassung, die den Link im Klartext nennt. Das ist Absicht — nicht jede Oberfläche stellt alle drei dar. claude.ai und Claude Desktop klappen den Werkzeugaufruf samt Bild standardmäßig zu; über den Link im Antworttext kommst du trotzdem direkt an den Code.

PNG und JPEG kommen als Bild zurück; für den Bildschirm genügen 512 bis 800 Pixel. SVG ist für Druck und Weiterverarbeitung gedacht und kommt nur als Link mit einer PNG-Vorschau — SVG-Quelltext kann kein Client als Bild darstellen. Dasselbe gilt für sehr große Rasterdateien. Die Links sind signiert, verfallen nach einer Stunde und öffnen das Bild direkt im Browser; ?download=1 angehängt erzwingt stattdessen das Speichern.

Kapazität, Farbkontrast und das Verhältnis von Logogröße zu Fehlerkorrektur prüft der Server bei jedem Aufruf. Auffälligkeiten stehen als warnings im Ergebnis — der Code muss nicht nachträglich dekodiert werden, um die Scanbarkeit zu beurteilen.

REST

curl -X POST https://scan-gogh.na15.io/api/v1/qr \
  -H "Authorization: Bearer $NA15_QR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "input":  { "type": "url", "url": "https://example.de" },
        "style":  { "dotStyle": "rounded", "fg": "#1e3a8a", "bg": "#dbeafe" },
        "output": { "format": "png", "size": 1200 }
      }' \
  -o qr.png

Ohne Accept-Header kommt das Bild direkt zurück. Mit Accept: application/json antwortet derselbe Endpunkt als { data, encoding, mimeType, meta } — praktisch, wenn die Datei ohnehin weiterverarbeitet oder in ein CMS geschrieben wird.

Endpunkt	Methode	Zweck
`/api/v1/qr`	POST	Code erzeugen
`/api/v1/validate`	POST	Prüfen ohne Rendern
`/api/v1/styles`	GET	Stilverzeichnis (ohne Key nutzbar)
`/api/v1/presets`	GET	Presets und Logos des Mandanten
`/openapi.json`	GET	OpenAPI 3.1, aus denselben Schemas erzeugt
`/healthz`	GET	Health-Check

n8n

Kein eigener Node notwendig: HTTP-Request-Node auf POST https://scan-gogh.na15.io/api/v1/qr, als Credential ein Header-Auth mit Authorization: Bearer …. Response-Format File wählen, dann landet das Bild direkt als Binary im Item. Für KI-Workflows kann alternativ der MCP-Client-Node den Endpunkt /mcp nutzen.

TYPO3

Empfohlenes Muster für die Extension na15_qr: Key aus der Umgebung lesen, beim Speichern des Inhaltselements einmal rendern, das Ergebnis als FAL-Datei ablegen und über das Cache-Framework ausliefern. So löst kein Websitebesucher je einen Request an unseren Server aus — schneller und datenschutzrechtlich sauber. Ohne konfigurierten Key sollte die Extension auf einen einfachen lokalen Renderer zurückfallen, damit sie nie hart von der API abhängt.

Parameter

Feld	Werte	Standard
`style.dotStyle`	square, dots, rounded, classy, classy-rounded, extra-rounded	square
`style.cornerStyle`	square, dot, extra-rounded	square
`style.fg` / `style.bg`	Hex `#rrggbb`	#0a0a0a / #ffffff
`style.gradient`	`{ to, direction }`, Richtung horizontal \| diagonal-down \| vertical \| diagonal-up	aus
`style.errorCorrection`	L, M, Q, H	Q
`style.margin`	0–64 Module	8
`logo`	`{ dataUrl }` (max. 1 MB) oder `{ tenantLogoId }`	—
`logoSize`	0.1–0.5	0.3
`output.format`	svg, png, jpeg	png
`output.size`	128–4096 px	1200
`preset`	Name eines Mandanten- oder Systempresets	Standard-Preset des Mandanten, falls gesetzt

Ein Preset wird zuerst angewandt, explizit gesetzte style-Felder gewinnen anschließend. Erlaubte Logo-Typen sind PNG, JPEG und SVG; SVG-Logos werden serverseitig geprüft und bei Skripten, Event-Attributen oder externen Referenzen abgelehnt.

Presets legen wir pro Mandant an — sie können Farben, Punktformen und ein hinterlegtes Logo umfassen. Ist eines davon als Standard markiert, gilt es für jeden Aufruf ohne preset-Angabe: QR-Codes sitzen dann ohne einen einzigen Parameter im richtigen Corporate Design. Wer bewusst neutral rendern will, gibt preset: "default" an. Welche Presets für deinen Zugang hinterlegt sind, nennt qr_list_styles beziehungsweise GET /api/v1/styles.

Fehler und Grenzen

Status	Code	Bedeutung
400	`invalid_input`	Feld fehlt oder hat einen unerlaubten Wert
401	`unauthorized`	Key fehlt, ist widerrufen oder abgelaufen
403	`insufficient_scope`	Der Key hat den benötigten Scope nicht
404	`preset_unknown`	Preset oder Tenant-Logo existiert nicht
413	`logo_too_large`	Logo über 1 MB
422	`content_too_long`	Inhalt passt bei diesem EC-Level in keinen QR-Code
429	`rate_limited` / `quota_exceeded`	Rate-Limit oder Monatskontingent erreicht, siehe `Retry-After`

Standardgrenzen pro Mandant: 60 Anfragen pro Minute, 5.000 pro Monat, maximal 4096 px Ausgabegröße, 5 Sekunden pro Rendering. Antworten tragen X-Qr-Version, X-Qr-Modules, X-Qr-Contrast und, falls vorhanden, X-Qr-Warnings.

Warnungen ernst nehmen. Ein Code mit zu großem Logo oder zu wenig Kontrast wird trotzdem erzeugt — er ist dann aber schlecht oder nicht scanbar. qr_validate bzw. /api/v1/validate sagt vorher, was zu erwarten ist.

Kontakt

Du brauchst einen Zugang, ein größeres Kontingent oder Unterstützung bei der Anbindung an TYPO3, n8n oder einen KI-Client? Melde dich bei der nullacht15 GmbH. Wir richten den Mandanten ein, hinterlegen Presets und Logo und begleiten die Integration.

Zugang anfragen OpenAPI 3.1 Datenschutz der API