Generarea în masă a codurilor QR: din CSV în fișiere pentru tipar

Generarea în masă a codurilor QR înseamnă două apeluri API pe rând și un dosar la final. Creezi un link scurt pentru fiecare destinație, randezi un cod QR pentru acel link scurt și scrii SVG-ul și PNG-ul pe disc. O foaie de calcul cu 5.000 de produse devine 5.000 de fișiere gata de tipar în câteva minute.

Uneltele nu sunt decizia. Decizia este ce codifică codul. Dacă codifici direct destinația, codul este înghețat în clipa în care pleacă la tipar, deci un singur URL greșit într-un tiraj de 5.000 de autocolante înseamnă că tot tirajul e rebut; dacă codifici un link scurt pe care îl controlezi, destinația rămâne editabilă pentru totdeauna, iar fiecare cod își raportează discret propriile scanări.

Faci un singur cod, nu mii? Cum creezi un cod QR este ghidul mai simplu, iar campania cu coduri QR de la zero acoperă plasarea și măsurarea.

Pipeline-ul în patru etape

Ține o coloană id în CSV, chiar dacă pare redundantă. Devine numele fișierului, cheia de idempotență și elementul după care potrivești când echipa de design îți trimite "codul 412 este greșit". Fără ea potrivești după URL-uri, iar URL-urile sunt lungi și ușor de greșit la scriere.

import csv, base64, hashlib, pathlib, os, requests

API = "https://api.elido.app"
HEAD = {"Authorization": f"Bearer {os.environ['ELIDO_API_KEY']}"}
out = pathlib.Path("qr-out")
out.mkdir(exist_ok=True)

with open("products.csv") as f:
    for row in csv.DictReader(f):        # columns: id, destination
        key = hashlib.sha256(row["destination"].encode()).hexdigest()

        link = requests.post(
            f"{API}/v1/links",
            headers={**HEAD, "Idempotency-Key": key},
            json={"destination_url": row["destination"]},
            timeout=10,
        )
        link.raise_for_status()
        short_url = link.json()["short_url"]

        qr = requests.post(
            f"{API}/v1/qr/generate",
            headers=HEAD,
            json={
                "content": short_url,          # the short link, never the destination
                "formats": ["svg", "png"],
                "size": 1024,
                "error_correction": "M",
            },
            timeout=20,
        )
        qr.raise_for_status()
        payload = qr.json()

        (out / f"{row['id']}.svg").write_text(payload["svg"])
        (out / f"{row['id']}.png").write_bytes(base64.b64decode(payload["png"]))
        print(row["id"], short_url)

Cheia de idempotență este derivată din destinație, deci relansarea fișierului după corectarea a trei rânduri nu creează nimic de două ori și nu costă nimic. Această proprietate face un job în masă sigur la repetare și merită înțeleasă bine înainte să-l îndrepți spre 5.000 de rânduri: limitele de rate și idempotența explică mecanismul.

Bucla de mai sus este secvențială, ceea ce e în regulă până la câteva sute de rânduri. Peste asta, rulează circa opt în paralel; ghidurile pentru Python și JavaScript au ambele un tipar de concurență limitată pe care îl poți prelua direct.

Vrei să-l rulezi? Creează o cheie în planul gratuit, exportă ELIDO_API_KEY și îndreaptă scriptul spre un CSV de cinci rânduri înainte să-l îndrepți spre cel real.

Static sau dinamic, la scară

Un cod static are exact un avantaj: nu depinde de nimic. Niciun domeniu de ținut în viață, niciun serviciu de plătit. Contează pentru un cod gravat pe o mașină care va trăi mai mult decât contractul cu furnizorul tău și aproape nicăieri altundeva.

Tot restul favorizează dinamicul. Numărul de scanări pe cod, singura cale de a compara plasările pe raft sau locațiile magazinelor. O destinație pe care o poți corecta când pagina campaniei se mută. Și coduri mai mici și mai rare, fiindcă un link scurt are o fracțiune din caracterele unui URL de produs cu tag-uri. Coduri QR dinamice versus statice conține comparația completă.

Setările de tipar care contează cu adevărat

Trei parametri decid dacă lotul se scanează în lumea reală.

Corecția erorilor. Nivelul M recuperează din aproximativ 15 la sută deteriorare și ține codul rar. Treci la Q când un logo stă la mijloc sau când codul va fi manevrat, zgâriat sau tipărit pe ceva curbat. H sună mai sigur și de obicei nu este: redundanța în plus înghesuie mai multe module, iar codurile mai dense se scanează mai greu la dimensiuni mici. Standardul QR documentează toate cele patru niveluri.

Formatul. SVG pentru tipar, fiindcă scalează la un poster fără să înmoaie marginile modulelor. PNG pentru prezentări, marketplace-uri și orice respinge vectorii. Cere-le pe amândouă într-o singură cerere și sari peste dus-întorsul când cineva are nevoie de celălalt.

Zona liberă. Marginea goală din jurul codului face parte din cod. Patru module este minimul specificat, iar designerii o taie cu regularitate, fiindcă pare spațiu irosit. Un cod cu bordura strânsă se scanează prost pe camere ieftine de telefon și nimeni nu face vreodată legătura.

Încă un lucru de știut înainte să fixezi o dimensiune pentru tot lotul: cantitatea de date decide versiunea, iar versiunea decide câte module are codul. Denso Wave, care a inventat formatul, publică tabelul de versiuni și capacitate. Un link scurt de 30 de caractere se află spre baza lui; un URL de produs cu tag-uri, de 180 de caractere, nu, iar diferența se vede ca un cod vizibil mai dens la aceeași dimensiune tipărită.

Dimensiunea din fișier contează mai puțin decât dimensiunea de pe obiect. Cât de mare ar trebui să fie un cod QR conține regula distanței de scanare care decide dimensiunea fizică.

Verifică înainte ca ceva să plece la tipar

Generează un lot, apoi verifică cinci coduri la întâmplare. Nu pe biroul tău, la luminozitate maximă a ecranului: tipărește-le la dimensiunea la care vor fi de fapt, lipește unul pe raft sau pe ambalaj și scanează de unde ar sta un client.

Apoi verifică redirecționarea în sine. curl -sI pe trei dintre linkurile scurte confirmă că returnează o redirecționare spre destinația corectă, ceea ce prinde clasica eroare cu o poziție decalată, în care coloana doi din CSV a fost citită drept coloana trei și fiecare cod trimite spre produsul vecin. Aceea este silențioasă, supraviețuiește oricărei verificări vizuale și se vede doar în destinație.

Păstrează CSV-ul care a produs lotul, cu id-ul, destinația, linkul scurt și numele fișierului. Când cineva întreabă peste șase luni ce cod este pe ce palet, fișierul acela este răspunsul, iar regenerarea lui din dashboard e mult mai multă muncă decât păstrarea lui.

Unde apar scanările

Odată ce codurile sunt active, fiecare raportează separat. Acesta este tot motivul pentru un cod pe articol, nu unul comun: un singur cod îți spune că a mers campania, iar codurile pe articol îți spun ce magazin, raft sau SKU a mers.

Cum urmărești scanările codurilor QR acoperă citirea acestor date, iar webhookurile pentru evenimentele linkurilor acoperă trimiterea scanărilor în propriile sisteme în loc să verifici un dashboard. Pentru contextul produselor fizice, codurile QR pentru pașaportul digital al produsului acoperă versiunea reglementată a aceluiași pipeline.

Citește seria de articole de bază

Articolul face parte din clusterul de funcții. Începe cu cum creezi un cod QR pentru varianta cu un singur cod, apoi campania cu coduri QR de la zero pentru designul campaniei. Pagina funcției coduri QR acoperă opțiunile de stilizare pe care scriptul acesta le omite.

Pe același subiect pe blog

• Coduri QR dinamice vs statice: de care ai nevoie
• Cât de mare ar trebui să fie un cod QR pentru tipar?
• Cum urmărești scanările codurilor QR
• Importă în masă linkuri scurte dintr-un Google Sheet