QivoEstudis de codi QR
Creació de codi QR

Per a la integració

Un codi QR en una sol·licitud

Enviar continguts i configuracions de disseny a través de GET / POST i rebre un PNG o SVG sense un control d'escaneig addicional.

Lliure i per sempre.PNG, SVG i API - sense taxes ni subscripcions.

Codi QR directe. No s’ha redirigit, no s’acaba.

GET / POSThttps://qivo.umind.group/

Sol·licitud i autenticació

Passar la clau en l'anomenada X-API-Key. no es requereixen sessions d'editorial i cookies. QIVO_API_KEY en aquest exemple és una variable de medi ambient del client que conté la seva clau.

Exemple de curl
curl --fail --show-error --get 'https://qivo.umind.group/' \
  --header "X-API-Key: $QIVO_API_KEY" \
  --data-urlencode 'data=https://umind.group' \
  --data-urlencode 'contentType=url' \
  --data-urlencode 'format=svg' \
  --data-urlencode 'shape=rounded' \
  --data-urlencode 'size=1024' \
  --output qr-code.svg

Si la seva integració accepta només una URL, passa la clau en el paràmetre clau:

Un exemple d'URL
https://qivo.umind.group/?key=YOUR_SECRET_KEY&data=https%3A%2F%2Fumind.group&format=png&size=1024

El títol pren precisió sobre el paràmetre clau. URL-encodeix els valors del paràmetre: # → %23, + → %2B, i & dins d'un valor → %26.

Utilitzeu HTTPS i mantingueu la clau al vostre servidor. No la poseu en JavaScript públic. Les claus i les dades en les URL de GET poden aparèixer en la història del navegador o en els logs del servidor; prefereix el títol per a la clau.

Exemples de codi

Emmagatzema la clau en la variable mediambiental QIVO_API_KEY; no la publiqueu en codi de pàgina.

qr-code.php
<?php
$key = getenv('QIVO_API_KEY');
if (!$key) throw new RuntimeException('Set QIVO_API_KEY');
$query = http_build_query([
    'data' => 'https://umind.group', 'format' => 'svg',
    'shape' => 'rounded', 'size' => 1024,
], '', '&', PHP_QUERY_RFC3986);
$curl = curl_init('https://qivo.umind.group/?' . $query);
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . $key],
    CURLOPT_TIMEOUT => 30,
]);
$image = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);
if ($image === false || $status !== 200) {
    throw new RuntimeException('Qivo request failed: ' . $status);
}
file_put_contents('qr-code.svg', $image);
qr-code.mjs
import { writeFile } from 'node:fs/promises';
const key = process.env.QIVO_API_KEY;
if (!key) throw new Error('Set QIVO_API_KEY');
const url = new URL('https://qivo.umind.group/');
url.search = new URLSearchParams({
  data: 'https://umind.group', format: 'svg',
  shape: 'rounded', size: '1024'
});
const response = await fetch(url, {
  headers: { 'X-API-Key': key },
  signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`Qivo request failed: ${response.status}`);
await writeFile('qr-code.svg', Buffer.from(await response.arrayBuffer()));
qr-code.py
import os
from pathlib import Path
from urllib.parse import urlencode
from urllib.request import Request, urlopen

key = os.environ['QIVO_API_KEY']
query = urlencode({
    'data': 'https://umind.group', 'format': 'svg',
    'shape': 'rounded', 'size': 1024,
})
request = Request('https://qivo.umind.group/?' + query,
                  headers={'X-API-Key': key})
# urlopen raises HTTPError for unsuccessful HTTP responses.
with urlopen(request, timeout=30) as response:
    Path('qr-code.svg').write_bytes(response.read())

Llogotip de l'Upload

POSThttps://qivo.umind.group/

Content-Type: multipart/form-data
X-API-Key: YOUR_SECRET_KEY

Qivo accepta els fitxers PNG, JPEG i WebP fins a 2 MB, amb un màxim costat de 2048 píxels. no s'accepten les pujades SVG. PNG o WebP amb transparència funciona bé per a una marca sense fons.

ParàmetresTipusRequisitsValors
X-API-KeyheaderNecessitatYOUR_SECRET_KEY
logostringNecessitatupload
logoFilefileNecessitatPNG / JPEG / WebP · ≤ 2 MiB · ≤ 2048 × 2048 px · ≤ 4,000,000 px
logoScaleintegerOpció12–30 · Definició: 24
logoPaddingintegerOpció0–25% · Definició: 5

GET → logo=none / whatsapp / …
POST → logo=upload + logoFile
logoUrl / logoBase64 / SVG / GIF → 422
Content-Length > 3 MiB → 413
level → H

cURL · multipart/form-data
curl --fail --show-error 'https://qivo.umind.group/' \
  --header "X-API-Key: $QIVO_API_KEY" \
  --form-string 'data=https://umind.group' \
  --form-string 'format=svg' \
  --form-string 'logo=upload' \
  --form-string 'logoPadding=10' \
  --form-string 'logoScale=24' \
  --form 'logoFile=@./logo.png;type=image/png' \
  --output qr-code.svg
PHP · CURLFile
<?php
$key = getenv('QIVO_API_KEY');
if (!$key) throw new RuntimeException('Set QIVO_API_KEY');
$curl = curl_init('https://qivo.umind.group/');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . $key],
    CURLOPT_TIMEOUT => 30,
    CURLOPT_POSTFIELDS => [
        'data' => 'https://umind.group', 'format' => 'png',
        'logo' => 'upload', 'logoScale' => '24', 'logoPadding' => '10',
        'logoFile' => new CURLFile(__DIR__ . '/logo.png', 'image/png', 'logo.png'),
    ],
]);
$image = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);
if ($image === false || $status !== 200) throw new RuntimeException('Qivo: ' . $status);
file_put_contents('qr-code.png', $image);
JavaScript · Node.js 20+
import { readFile, writeFile } from 'node:fs/promises';
const key = process.env.QIVO_API_KEY;
if (!key) throw new Error('Set QIVO_API_KEY');
const form = new FormData();
form.set('data', 'https://umind.group');
form.set('format', 'svg');
form.set('logo', 'upload');
form.set('logoPadding', '10');
form.set('logoFile', new Blob([await readFile('./logo.png')], { type: 'image/png' }), 'logo.png');
// FormData supplies Content-Type and the multipart boundary automatically.
const response = await fetch('https://qivo.umind.group/', {
  method: 'POST', headers: { 'X-API-Key': key }, body: form,
  signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`Qivo: ${response.status}`);
await writeFile('qr-code.svg', Buffer.from(await response.arrayBuffer()));
Python · requests
# python -m pip install requests
import os
from pathlib import Path
import requests

with open('logo.png', 'rb') as logo:
    response = requests.post(
        'https://qivo.umind.group/',
        headers={'X-API-Key': os.environ['QIVO_API_KEY']},
        data={'data': 'https://umind.group', 'format': 'svg', 'logo': 'upload', 'logoPadding': '10'},
        files={'logoFile': ('logo.png', logo, 'image/png')},
        timeout=30,
    )
response.raise_for_status()
Path('qr-code.svg').write_bytes(response.content)

La geometria QR dins d'un SVG és basada en vectors. El seu logotip carregat està incorporat com una imatge de raster netejat, de manera que el seu detall no esdevé il·limitat.

Paràmetres de disseny

ParàmetresTipusRequisitsValors
X-API-Key / keystringNecessitat
Títol secret: el cap o el paràmetre GET
datastringText i URL
Contingut requerit per a text/url
contentTypestringOpció
texturlwifivcardwhatsapptelegramphoneviberemailsms
Definició: text
formatstringOpció
pngsvg
Definició: png
sizeintegerOpció
25651210242048
Definició: 1024
shapestringOpció
squaresoftroundeddotsleaf-softleafhorizontalverticalpointednotchedstardiamondxx-roundedplusplus-roundedheartsparkleconfetti
Definició: square
borderstringOpció
squarecircleroundedskewdrop-tldrop-brleafleaf-inner-brleaf-circleleaf-inner-tlsquare-circlesoft-tlsoft-brsoft-leafrough
Definició: square
centerstringOpció
squarecircleroundedskewroughdrop-tldrop-brleafgearstardiamondxx-roundedplusplus-roundedheart
Definició: square
foreground / eyeColorstringOpció
#RRGGBB
Definició: #192b39
backgroundstringOpció
#RRGGBB
Definició: #ffffff
levelstringOpció
LMQH
Definició: M
quietZoneintegerOpció
0 - 12 mòduls
Definició: 4
logostringOpció
noneuploadwhatsapplinklocationwificredentialemailscanbellmenuscan-mescan-me-v2paypalbitcoinsparkplusdiamond
Definició: none
logoScaleintegerOpció
12–30
Definició: 24
logoPaddingintegerOpció
0–25%
Definició: 5

logo=upload → POST / · logoFile · level=H

Tipus de continguts

Els camps depenen del contingutTip. per a les URL, proporcionar una adreça completa https:// o http://. per als números de telèfon, inclou el codi de país.

contentTypeCamps necessarisCamps opcionals
text / urldata—
phone / viberphone—
whatsapp / smsphonemessage
telegramtelegram—
emailemailsubject, message
wifissid; wifiSecurity≠nopass → wifiPasswordwifiSecurity (WPA), wifiHidden (0)
vcardfirstName / lastNameorganization, jobTitle, phone, email, website, address
Exemple de telèfon
https://qivo.umind.group/?key=YOUR_SECRET_KEY&contentType=phone&phone=%2B380671234567&format=svg

Reacció de l'Api

Una resposta reeixida és el fitxer d'imatge en si, sense un xifrat JSON. El tipus de contingut és imatge/png o imatge/svg+xml. Els errors es retornen com a JSON:

JSON
{"error":"Invalid API key."}
  • 200 — Imatge generada.
  • 401 — La clau desapareguda o invalidada.
  • 405 — GET / POST
  • 413 — Content-Length > 3 MiB
  • 415 — POST: multipart/form-data
  • 422 — Paràmetres invalidats o continguts faltants.
  • 429 — El límit de la taxa ha superat; Retre-After: 60.
  • 503 — L'accés a API no està configurat o la protecció és temporalment inaccessible.
  • 500 — Errors de generació interna.

Límits i validació

El límit de default és 60 sol·licituds per minut per IP. El contingut encodat està limitat a 800 bytes. La sortida PNG suporta fins a 2048 × 2048 px. SVG conserva les formes vectores.

L'API valida els formats de paràmetres, la mida i el contrast, però no executa un decoder o comprova si els QR escaneixen.

Obtenir accés

L'API és lliure i sempre quedarà lliure. Completeu el breu formulari per sol·licitar una clau secreta.

Els detalls del formulari s'enviaran a l'equip de Qivo per revisar la seva sol·licitud i resposta.