Panoramica dell'API
Il motore è pubblicato come una piccola API HTTP. Ci sono due modi per autenticarsi.
Due canali
1. Marketplace di RapidAPI (clienti esistenti)
Chiama https://api.qr-branding.com con il proxy secret di RapidAPI. Gli endpoint IA usano la tua chiave LLM, oppure l'endpoint gestito, che non ne richiede nessuna. Nulla cambia rispetto al funzionamento dell'API Signet QR originale.
2. Pacchetti di crediti consumer (nuovo)
Acquista un pacchetto su /pricing. I tuoi endpoint IA usano chiavi LLM lato server (Groq / Gemini / OpenAI) e i crediti vengono scalati a ogni generazione riuscita. L'editor del front-end usa questo canale in modo trasparente.
Endpoint
| Metodo | Percorso | Scopo |
|---|---|---|
POST | /api/qr/generate | Genera un QR da un QrConfig esplicito. |
POST | /api/qr/ai/generate | IA marketplace: usi la tua chiave LLM. |
POST | /api/qr/ai/generate-managed | IA marketplace gestita: non serve nessuna chiave LLM. |
POST | /api/qr/ai/generate/server | IA consumer: chiave LLM lato server, a consumo di crediti. |
GET | /api/qr/templates | Elenca i 118 modelli predefiniti (facoltativamente ?category=…). |
POST | /api/qr/templates/{templateId} | Genera un QR da un id di modello con eventuali sovrascritture. |
POST | /api/qr/content/wifi | Helper: costruisce la stringa di contenuto di un QR WiFi. |
POST | /api/qr/content/vcard | Helper: costruisce la stringa di contenuto di una vCard. |
POST | /api/qr/content/geo | Helper: costruisce la stringa di contenuto di una geolocalizzazione. |
GET | /api/qr/ai/providers | Elenca i provider LLM supportati + i modelli. |
GET | /api/ping | Controllo di stato (anonimo). |
Header di autenticazione
RapidAPI
X-RapidAPI-Proxy-Secret: <secret>
BFF interno (sito consumer)
X-Internal-Service-Secret: <secret>
X-Internal-Customer-Id: <customer id>
X-Internal-Ts: <unix seconds>
X-Internal-Signature: <HMAC-SHA256(signing-key, "{customerId}.{ts}")>
TTL anti-replay: 60 secondi. Usato internamente dal frontend Next.js: non dovrai mai impostarli a mano.
Formato degli errori
Ogni risposta non 2xx ha una struttura stabile:
{
"success": false,
"error": "Content length (5000) exceeds maximum allowed (4296 characters).",
"code": "CONTENT_TOO_LONG",
"field": "content"
}
field è presente quando l'errore riguarda un input specifico.
Limiti di richieste
| Livello | Al minuto | Note |
|---|---|---|
| RapidAPI generale | 60 | docs, ping, helper |
| RapidAPI generazione | 30 | /api/qr/generate |
| RapidAPI IA | 15 | chiamate a LLM esterni |
| Consumer generale | 120 | per id cliente |
| Consumer generazione | 60 | per id cliente |
| Consumer IA | 30 | per id cliente |
Esistono anche tetti globali al minuto per proteggere il piano gratuito di Azure. Se ne raggiungi uno ricevi un 429 con un header Retry-After.
Formati di output
png (predefinito, base64), jpg, svg, pdf, webp. Imposta "responseType": "binary" per scaricare direttamente il file invece di ricevere il base64 nel JSON.