Documentazione API REST QR Code
Genera QR Code statici tramite endpoint HTTP, API key e parametri supportati.
Questa pagina contiene le informazioni tecniche essenziali per integrare l'API QRCodeGenerate in applicazioni, gestionali, CRM, e-commerce o processi interni.
Base URL e autenticazione
L'endpoint attuale genera QR Code statici e richiede una API key valida.
La chiave va inviata nell'header x-api-key. Non inserirla in codice pubblico o frontend non protetto.
Endpoint
https://www.qrcodegenerate.it/api/v1/qrcode/generate-static
Metodi supportati
POSTcon body JSON: consigliato per integrazioni complete.GETcon query string: utile per richieste semplici.
Header richiesto
x-api-key: LA_TUA_API_KEY
Parametri supportati
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
content |
stringa | Sì | Testo o URL da codificare nel QR Code. |
format |
stringa | No | Formato output: png, jpeg, webp, svg, base64url. Default: png. |
size |
numero | No | Dimensione del QR Code in pixel. Default: 200. Per GET la dimensione deve essere un numero valido maggiore di 50. |
color |
oggetto | No | Solo POST: colori dark e light. Esempio: { "dark": "#000000", "light": "#ffffff" }. |
color[dark] / color[light] |
query string | No | Solo GET: colori di primo piano e sfondo passati come parametri URL. |
logoUrl |
stringa URL | No | URL di un logo da inserire al centro del QR. Supportato per output immagine png, jpeg e webp. |
Nota: svg e base64url vengono generati senza composizione diretta del logo.
Per QR con logo usa preferibilmente png, jpeg o webp.
Esempi validi di integrazione
Gli esempi usano l'endpoint reale e salvano il risultato come file immagine quando il formato scelto restituisce un contenuto binario.
Sostituisci LA_TUA_API_KEY con la tua chiave o usa una variabile d'ambiente.
cURL — POST consigliato
curl -X POST "https://www.qrcodegenerate.it/api/v1/qrcode/generate-static" \
-H "Content-Type: application/json" \
-H "x-api-key: LA_TUA_API_KEY" \
--output qrcode.png \
-d '{
"content": "https://www.tuosito.it",
"format": "png",
"size": 300,
"color": {
"dark": "#000000",
"light": "#ffffff"
}
}'
Node.js 18+ — POST
import { writeFile } from "node:fs/promises";
const apiKey = process.env.QRCODEGENERATE_API_KEY;
const endpoint = "https://www.qrcodegenerate.it/api/v1/qrcode/generate-static";
if (!apiKey) {
throw new Error("Variabile QRCODEGENERATE_API_KEY mancante");
}
const response = await fetch(endpoint, {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-key": apiKey
},
body: JSON.stringify({
content: "https://www.tuosito.it",
format: "png",
size: 300,
color: {
dark: "#000000",
light: "#ffffff"
}
})
});
if (!response.ok) {
const errorBody = await response.text();
throw new Error(`Errore API ${response.status}: ${errorBody}`);
}
const buffer = Buffer.from(await response.arrayBuffer());
await writeFile("qrcode.png", buffer);
console.log("QR Code salvato in qrcode.png");
Node.js 18+ — GET semplice
import { writeFile } from "node:fs/promises";
const apiKey = process.env.QRCODEGENERATE_API_KEY;
const endpoint = new URL("https://www.qrcodegenerate.it/api/v1/qrcode/generate-static");
endpoint.searchParams.set("content", "https://www.tuosito.it");
endpoint.searchParams.set("format", "svg");
endpoint.searchParams.set("size", "300");
endpoint.searchParams.set("color[dark]", "#000000");
endpoint.searchParams.set("color[light]", "#ffffff");
const response = await fetch(endpoint, {
method: "GET",
headers: {
"x-api-key": apiKey
}
});
if (!response.ok) {
const errorBody = await response.text();
throw new Error(`Errore API ${response.status}: ${errorBody}`);
}
const svg = await response.text();
await writeFile("qrcode.svg", svg, "utf8");
console.log("QR Code SVG salvato in qrcode.svg");
Python — POST
import os
import requests
api_key = os.environ.get("QRCODEGENERATE_API_KEY")
endpoint = "https://www.qrcodegenerate.it/api/v1/qrcode/generate-static"
if not api_key:
raise RuntimeError("Variabile QRCODEGENERATE_API_KEY mancante")
payload = {
"content": "https://www.tuosito.it",
"format": "png",
"size": 300,
"color": {
"dark": "#000000",
"light": "#ffffff"
}
}
response = requests.post(
endpoint,
headers={"x-api-key": api_key},
json=payload,
timeout=30
)
if not response.ok:
raise RuntimeError(f"Errore API {response.status_code}: {response.text}")
with open("qrcode.png", "wb") as file:
file.write(response.content)
print("QR Code salvato in qrcode.png")
PHP — POST con cURL
<?php
$apiKey = getenv('QRCODEGENERATE_API_KEY');
$endpoint = 'https://www.qrcodegenerate.it/api/v1/qrcode/generate-static';
if (!$apiKey) {
throw new RuntimeException('Variabile QRCODEGENERATE_API_KEY mancante');
}
$payload = json_encode([
'content' => 'https://www.tuosito.it',
'format' => 'png',
'size' => 300,
'color' => [
'dark' => '#000000',
'light' => '#ffffff'
]
]);
$ch = curl_init($endpoint);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'x-api-key: ' . $apiKey
],
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30
]);
$response = curl_exec($ch);
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
curl_close($ch);
if ($statusCode < 200 || $statusCode >= 300) {
throw new RuntimeException('Errore API ' . $statusCode . ': ' . $response);
}
file_put_contents('qrcode.png', $response);
echo 'QR Code salvato in qrcode.png';
TypeScript — POST
import { writeFile } from "node:fs/promises";
const apiKey = process.env.QRCODEGENERATE_API_KEY;
const endpoint = "https://www.qrcodegenerate.it/api/v1/qrcode/generate-static";
if (!apiKey) {
throw new Error("Variabile QRCODEGENERATE_API_KEY mancante");
}
const payload = {
content: "https://www.tuosito.it",
format: "png",
size: 300,
color: {
dark: "#000000",
light: "#ffffff"
}
};
const response = await fetch(endpoint, {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-key": apiKey
},
body: JSON.stringify(payload)
});
if (!response.ok) {
const errorBody = await response.text();
throw new Error(`Errore API ${response.status}: ${errorBody}`);
}
const fileBuffer = Buffer.from(await response.arrayBuffer());
await writeFile("qrcode.png", fileBuffer);
Ruby — POST
require "net/http"
require "json"
require "uri"
api_key = ENV["QRCODEGENERATE_API_KEY"]
endpoint = URI("https://www.qrcodegenerate.it/api/v1/qrcode/generate-static")
raise "Variabile QRCODEGENERATE_API_KEY mancante" if api_key.to_s.empty?
request = Net::HTTP::Post.new(endpoint)
request["Content-Type"] = "application/json"
request["x-api-key"] = api_key
request.body = {
content: "https://www.tuosito.it",
format: "png",
size: 300,
color: {
dark: "#000000",
light: "#ffffff"
}
}.to_json
response = Net::HTTP.start(endpoint.hostname, endpoint.port, use_ssl: endpoint.scheme == "https") do |http|
http.request(request)
end
unless response.is_a?(Net::HTTPSuccess)
raise "Errore API #{response.code}: #{response.body}"
end
File.binwrite("qrcode.png", response.body)
puts "QR Code salvato in qrcode.png"
Swift — POST
import Foundation
@main
struct GenerateQrCode {
static func main() async throws {
let apiKey = ProcessInfo.processInfo.environment["QRCODEGENERATE_API_KEY"] ?? ""
guard !apiKey.isEmpty else {
fatalError("Variabile QRCODEGENERATE_API_KEY mancante")
}
let endpoint = URL(string: "https://www.qrcodegenerate.it/api/v1/qrcode/generate-static")!
var request = URLRequest(url: endpoint)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue(apiKey, forHTTPHeaderField: "x-api-key")
let payload: [String: Any] = [
"content": "https://www.tuosito.it",
"format": "png",
"size": 300,
"color": [
"dark": "#000000",
"light": "#ffffff"
]
]
request.httpBody = try JSONSerialization.data(withJSONObject: payload)
let (data, response) = try await URLSession.shared.data(for: request)
guard let httpResponse = response as? HTTPURLResponse,
(200...299).contains(httpResponse.statusCode) else {
let body = String(data: data, encoding: .utf8) ?? ""
throw NSError(domain: "QRCodeGenerate", code: 1, userInfo: [NSLocalizedDescriptionKey: body])
}
try data.write(to: URL(fileURLWithPath: "qrcode.png"))
print("QR Code salvato in qrcode.png")
}
}
Go — POST
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
"os"
)
func main() {
apiKey := os.Getenv("QRCODEGENERATE_API_KEY")
if apiKey == "" {
panic("Variabile QRCODEGENERATE_API_KEY mancante")
}
payload := map[string]interface{}{
"content": "https://www.tuosito.it",
"format": "png",
"size": 300,
"color": map[string]string{
"dark": "#000000",
"light": "#ffffff",
},
}
body, err := json.Marshal(payload)
if err != nil {
panic(err)
}
req, err := http.NewRequest("POST", "https://www.qrcodegenerate.it/api/v1/qrcode/generate-static", bytes.NewReader(body))
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-api-key", apiKey)
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
errorBody, _ := io.ReadAll(resp.Body)
panic(fmt.Sprintf("Errore API %d: %s", resp.StatusCode, string(errorBody)))
}
file, err := os.Create("qrcode.png")
if err != nil {
panic(err)
}
defer file.Close()
if _, err := io.Copy(file, resp.Body); err != nil {
panic(err)
}
fmt.Println("QR Code salvato in qrcode.png")
}
C++ — POST con libcurl
#include <curl/curl.h>
#include <cstdio>
#include <cstdlib>
#include <iostream>
#include <string>
int main() {
const char* apiKeyEnv = std::getenv("QRCODEGENERATE_API_KEY");
if (apiKeyEnv == nullptr) {
std::cerr << "Variabile QRCODEGENERATE_API_KEY mancante" << std::endl;
return 1;
}
FILE* output = std::fopen("qrcode.png", "wb");
if (!output) {
std::cerr << "Impossibile creare qrcode.png" << std::endl;
return 1;
}
CURL* curl = curl_easy_init();
if (!curl) {
std::fclose(output);
return 1;
}
std::string apiHeader = std::string("x-api-key: ") + apiKeyEnv;
struct curl_slist* headers = nullptr;
headers = curl_slist_append(headers, "Content-Type: application/json");
headers = curl_slist_append(headers, apiHeader.c_str());
const char* payload = R"json({
"content": "https://www.tuosito.it",
"format": "png",
"size": 300,
"color": {
"dark": "#000000",
"light": "#ffffff"
}
})json";
curl_easy_setopt(curl, CURLOPT_URL, "https://www.qrcodegenerate.it/api/v1/qrcode/generate-static");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);
curl_easy_setopt(curl, CURLOPT_WRITEDATA, output);
CURLcode result = curl_easy_perform(curl);
if (result != CURLE_OK) {
std::cerr << curl_easy_strerror(result) << std::endl;
}
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
std::fclose(output);
return result == CURLE_OK ? 0 : 1;
}
C# — POST
using System.Text;
var apiKey = Environment.GetEnvironmentVariable("QRCODEGENERATE_API_KEY");
if (string.IsNullOrWhiteSpace(apiKey))
{
throw new InvalidOperationException("Variabile QRCODEGENERATE_API_KEY mancante");
}
var endpoint = "https://www.qrcodegenerate.it/api/v1/qrcode/generate-static";
var json = """
{
"content": "https://www.tuosito.it",
"format": "png",
"size": 300,
"color": {
"dark": "#000000",
"light": "#ffffff"
}
}
""";
using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, endpoint);
request.Headers.Add("x-api-key", apiKey);
request.Content = new StringContent(json, Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);
var body = await response.Content.ReadAsByteArrayAsync();
if (!response.IsSuccessStatusCode)
{
var errorText = Encoding.UTF8.GetString(body);
throw new Exception($"Errore API {(int)response.StatusCode}: {errorText}");
}
await File.WriteAllBytesAsync("qrcode.png", body);
Console.WriteLine("QR Code salvato in qrcode.png");
Java 11+ — POST
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
public class GenerateQrCode {
public static void main(String[] args) throws Exception {
String apiKey = System.getenv("QRCODEGENERATE_API_KEY");
if (apiKey == null || apiKey.isBlank()) {
throw new IllegalStateException("Variabile QRCODEGENERATE_API_KEY mancante");
}
String json = """
{
"content": "https://www.tuosito.it",
"format": "png",
"size": 300,
"color": {
"dark": "#000000",
"light": "#ffffff"
}
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://www.qrcodegenerate.it/api/v1/qrcode/generate-static"))
.header("Content-Type", "application/json")
.header("x-api-key", apiKey)
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpResponse<byte[]> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofByteArray());
if (response.statusCode() < 200 || response.statusCode() >= 300) {
throw new RuntimeException("Errore API " + response.statusCode() + ": " + new String(response.body()));
}
Files.write(Path.of("qrcode.png"), response.body());
System.out.println("QR Code salvato in qrcode.png");
}
}
VB.NET — POST
Imports System
Imports System.IO
Imports System.Net.Http
Imports System.Text
Imports System.Threading.Tasks
Module Program
Sub Main()
MainAsync().GetAwaiter().GetResult()
End Sub
Private Async Function MainAsync() As Task
Dim apiKey = Environment.GetEnvironmentVariable("QRCODEGENERATE_API_KEY")
If String.IsNullOrWhiteSpace(apiKey) Then
Throw New InvalidOperationException("Variabile QRCODEGENERATE_API_KEY mancante")
End If
Dim endpoint = "https://www.qrcodegenerate.it/api/v1/qrcode/generate-static"
Dim json = "{" &
"""content"":""https://www.tuosito.it""," &
"""format"":""png""," &
"""size"":300," &
"""color"":{""dark"":""#000000"",""light"":""#ffffff""}" &
"}"
Using client As New HttpClient()
Using request As New HttpRequestMessage(HttpMethod.Post, endpoint)
request.Headers.Add("x-api-key", apiKey)
request.Content = New StringContent(json, Encoding.UTF8, "application/json")
Using response = Await client.SendAsync(request)
Dim body = Await response.Content.ReadAsByteArrayAsync()
If Not response.IsSuccessStatusCode Then
Dim errorText = Encoding.UTF8.GetString(body)
Throw New Exception("Errore API " & CInt(response.StatusCode) & ": " & errorText)
End If
File.WriteAllBytes("qrcode.png", body)
Console.WriteLine("QR Code salvato in qrcode.png")
End Using
End Using
End Using
End Function
End Module
Frontend — esempio sicuro tramite tuo backend
<form id="qrForm">
<input id="qrContent" type="url" placeholder="https://www.tuosito.it" required>
<button type="submit">Genera QR</button>
</form>
<img id="qrPreview" alt="QR Code generato" hidden>
<script>
document.getElementById("qrForm").addEventListener("submit", async (event) => {
event.preventDefault();
const content = document.getElementById("qrContent").value;
const response = await fetch("/api/qr-proxy", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({ content })
});
if (!response.ok) {
throw new Error(await response.text());
}
const blob = await response.blob();
const imageUrl = URL.createObjectURL(blob);
const preview = document.getElementById("qrPreview");
preview.src = imageUrl;
preview.hidden = false;
});
</script>
Risposte API
Per png, jpeg, webp e svg, una richiesta valida restituisce direttamente il file generato.
Per base64url, la risposta è JSON con il valore base64.
| Status | Quando accade | Esempio risposta |
|---|---|---|
200 |
QR Code generato correttamente. | image/png, image/jpeg, image/webp, image/svg+xml oppure JSON per base64url. |
400 |
content mancante, formato non supportato o dimensione GET non valida. |
{ "status": "400", "message": "Contenuto del QR Code mancante." } |
401 |
Header x-api-key mancante. |
{ "error": "Chiave API mancante. Includi l'header x-api-key." } |
403 |
API key non valida, utente non trovato o piano non autorizzato. | { "error": "Accesso API non consentito per il tuo piano." } |
429 |
Limite richieste del piano o rate limit globale raggiunto. | { "error": "Limite di richieste mensile raggiunto. Effettua l'upgrade del tuo piano." } |
500 |
Errore interno durante autenticazione, verifica piano, uso API o generazione QR. | Messaggio JSON di errore interno, variabile in base al punto in cui si verifica l'errore. |
Prima di andare in produzione
Conserva la API key lato server, gestisci gli errori HTTP e verifica i limiti del piano prima di automatizzare grandi volumi. Per una panoramica commerciale e funzionale, torna alla pagina API REST principale.
Torna alla panoramica