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.

Documentazione API REST per generare QR Code

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

  • POST con body JSON: consigliato per integrazioni complete.
  • GET con query string: utile per richieste semplici.

Header richiesto

x-api-key: LA_TUA_API_KEY

Parametri supportati

Parametro Tipo Obbligatorio Descrizione
content stringa 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