Visión general de la API
El motor se publica como una API HTTP pequeña. Hay dos formas de autenticarse.
Dos canales
1. RapidAPI Marketplace (clientes existentes)
Llama a https://api.qr-branding.com con tu proxy secret de RapidAPI. Los endpoints de IA usan tu propia clave del LLM, o el endpoint gestionado, que no necesita ninguna. Nada cambia respecto a cómo funcionaba la Signet QR API original.
2. Paquetes de créditos para consumidores (nuevo)
Compra un paquete en /pricing. Tus endpoints de IA usan claves de LLM del servidor (Groq / Gemini / OpenAI) y los créditos se descuentan por cada generación correcta. El editor web consume este canal de forma transparente.
Endpoints
| Método | Ruta | Para qué sirve |
|---|---|---|
POST | /api/qr/generate | Renderiza un QR a partir de un QrConfig explícito. |
POST | /api/qr/ai/generate | IA de Marketplace: aportas tu propia clave del LLM. |
POST | /api/qr/ai/generate-managed | IA gestionada de Marketplace: no hace falta clave del LLM. |
POST | /api/qr/ai/generate/server | IA para consumidores: clave del LLM del servidor, descuenta créditos. |
GET | /api/qr/templates | Lista las 118 plantillas predefinidas (opcionalmente ?category=…). |
POST | /api/qr/templates/{templateId} | Renderiza un QR a partir del id de una plantilla, con ajustes opcionales. |
POST | /api/qr/content/wifi | Utilidad: construye la cadena de contenido de un QR WiFi. |
POST | /api/qr/content/vcard | Utilidad: construye la cadena de contenido de una vCard. |
POST | /api/qr/content/geo | Utilidad: construye la cadena de contenido de una geolocalización. |
GET | /api/qr/ai/providers | Lista los proveedores de LLM y modelos admitidos. |
GET | /api/ping | Comprobación de estado (anónima). |
Cabeceras de autenticación
RapidAPI
X-RapidAPI-Proxy-Secret: <secret>
BFF interno (sitio para consumidores)
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 antirrepetición: 60 segundos. Las usa internamente el frontend de Next.js; nunca tendrás que ponerlas a mano.
Formato de error
Toda respuesta que no sea 2xx tiene una forma estable:
{
"success": false,
"error": "Content length (5000) exceeds maximum allowed (4296 characters).",
"code": "CONTENT_TOO_LONG",
"field": "content"
}
field aparece cuando el fallo apunta a una entrada concreta.
Límites de peticiones
| Nivel | Por minuto | Notas |
|---|---|---|
| RapidAPI general | 60 | documentación, ping, utilidades |
| RapidAPI generación | 30 | /api/qr/generate |
| RapidAPI IA | 15 | llamadas a LLM externos |
| Consumidor general | 120 | por id de cliente |
| Consumidor generación | 60 | por id de cliente |
| Consumidor IA | 30 | por id de cliente |
También hay topes globales por minuto para proteger el nivel gratuito de Azure. Si alcanzas uno, recibes un 429 con la cabecera Retry-After.
Formatos de salida
png (por defecto, en base64), jpg, svg, pdf, webp. Usa "responseType": "binary" para descargar el archivo directamente en lugar de recibir base64 dentro del JSON.