Manualul dezvoltatorului CreateQR

Automatizezi generarea de QR-uri fără complicații inutile

Folosești trei endpoint-uri pentru a crea, lista și șterge coduri QR cu control complet asupra stilului. Integrare rapidă, JSON curat, iar toate QR-urile rămân în dashboardul tău.

Obține cheia API Vezi planurile
Calea de bază: /api/v1 Autentificare: Authorization: Bearer <key> (recomandat)

Exemple de coduri QR generate cu API-ul nostru

Același endpoint, stiluri diferite. Îl poți păstra simplu, îl poți aduce în identitatea brandului sau îl poți încadra pentru campanii offline.

Simplu

Simplu

Fără artificii, scanare rapidă

Contrast ridicat

Contrast ridicat

Construit pentru distanță

Culorile brandului

Culorile brandului

Campanie aliniată vizual

Logo central

Pictogramă watermark presetată

Ramă cu text

Ramă cu text

Pregătit pentru postere cu "SCANEAZĂ"

Gradient expresiv

Gradient expresiv

Stil suplimentar pentru social media

Creează coduri QR

Creezi un cod QR static sau dinamic și îl salvezi în contul tău.

POST https://createqr.app/api/v1/create

Trimite doar JSON. Pentru autentificare, headerul este varianta recomandată. Câmpurile din body sunt păstrate pentru compatibilitate cu integrările existente.

Quickstart (cURL)

Acesta este cel mai rapid traseu pentru primul request funcțional.

curl -sS -X POST 'https://createqr.app/api/v1/create' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ck_live_XXXXXXXXXXXXXXXXXXXXXXXX' \
  -d '{"data":"https://createqr.app","qrtype":"static"}'

Autentificare și compatibilitate

  • Recomandat: Authorization: Bearer <key>
  • Acceptat și: X-API-Key
  • Fallback JSON: apikey sau api_key
  • Content-Type trebuie să fie application/json
  • Metodele non-POST returnează 405 method_not_allowed

Parametri principali

Parametru Tip Implicit Descriere
apikey String Obligatoriu Cheie API secretă. Recomandat în headerul Authorization (Bearer). Sunt acceptate și câmpurile JSON apikey/api_key.
data String Obligatoriu Conținutul care va fi codificat. Pentru QR dinamic, trebuie să fie un URL valid.
qrtype String static Modul QR: static sau dynamic.
title String Opțional Titlul QR-ului afișat în dashboard, limitat la 120 de caractere.
folderid Number Opțional ID numeric pozitiv al unui folder din contul tău.

Parametri de culoare și formă

Parametru Tip Implicit Descriere
transparent String/Bool off Sunt acceptate on/off, true/false, 1/0, yes/no.
backcolor String #FFFFFF Culoarea de fundal în format hex #RRGGBB.
frontcolor String #000000 Culoarea principală a modulelor QR în format #RRGGBB.
gradient String/Bool off Activează gradientul în două culori pentru puncte.
radial String/Bool off Activează gradientul radial, când gradient este pornit.
gradient_color String #15A97C A doua culoare a gradientului, în format #RRGGBB.
marker_out_color String #000000 Culoarea markerilor exteriori.
marker_in_color String #000000 Culoarea markerilor interiori.
pattern String default Preset pentru stilul punctelor QR.
default circle star diamond sparkle danger cross plus x heart shake blob special-circle-orizz special-circle-vert special-circle special-diamond ribbon oriental ellipse
marker String default Preset pentru markerii exteriori.
default flurry sdoz drop_in drop dropeye dropeyeleft dropeyeleaf dropeyeright squarecircle circle rounded flower flower_in leaf
marker_in String default Preset pentru markerii interiori.
default flurry sdoz drop_in drop dropeye circle rounded sun star diamond danger cross plus x heart
optionlogo String none none, cale locală recomandată către watermark SVG, cale locală legacy către PNG sau date de imagine în base64.
none data:image/*;base64,... /images/watermarks/v2/01-link.svg /images/watermarks/v2/02-location.svg /images/watermarks/v2/03-email.svg /images/watermarks/v2/04-whatsapp.svg /images/watermarks/v2/05-wifi.svg /images/watermarks/v2/06-vcard.svg /images/watermarks/v2/07-menu.svg /images/watermarks/v2/08-app.svg /images/watermarks/v2/09-video.svg /images/watermarks/v2/10-feedback.svg /images/watermarks/v2/11-event.svg /images/watermarks/v2/12-coupon.svg /images/watermarks/v2/13-music.svg /images/watermarks/v2/14-social.svg /images/watermarks/v2/15-paypal.svg /images/watermarks/v2/16-bitcoin.svg /images/watermarks/v2/17-scan.svg
no_logo_bg String/Bool off Dezactivează placa de fundal din spatele logo-ului.

Parametri de ramă

Parametru Tip Implicit Descriere
outer_frame String none Preset pentru stilul ramei.
none bottom top balloon-bottom balloon-top ribbon-bottom ribbon-top phone cine
framelabel String SCAN ME Textul din ramă, limitat la 80 de caractere.
label_font String Arial, Helvetica, sans-serif Stiva de fonturi folosită pentru textul ramei.
custom_frame_color String/Bool off Activează culoare personalizată pentru ramă.
framecolor String #000000 Culoarea ramei în format hex #RRGGBB.

Exemple de request pentru creare

Exemplu: QR simplu

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "data": "https://createqr.app",
    "qrtype": "static",
    "title": "Launch Landing QR",
    "transparent": "off",
    "backcolor": "#FFFFFF",
    "frontcolor": "#000000",
    "marker_out_color": "#000000",
    "marker_in_color": "#000000",
    "pattern": "default",
    "marker": "default",
    "marker_in": "default",
    "optionlogo": "none"
}
Previzualizare rezultat exemplu

Exemplu: culoare + logo

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "data": "https://createqr.app/features",
    "qrtype": "static",
    "title": "Feature Tour QR",
    "transparent": "off",
    "backcolor": "#033895",
    "frontcolor": "#FFFFFF",
    "marker_out_color": "#669DF4",
    "marker_in_color": "#669DF4",
    "pattern": "oriental",
    "marker": "flower",
    "marker_in": "circle",
    "optionlogo": "/images/watermarks/v2/01-link.svg"
}

Exemplu: QR de campanie cu ramă

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "data": "https://createqr.app/pricing",
    "qrtype": "static",
    "title": "Pricing Poster QR",
    "transparent": "off",
    "frontcolor": "#2B0011",
    "marker_out_color": "#3B0001",
    "marker_in_color": "#3B0001",
    "pattern": "ellipse",
    "marker": "sdoz",
    "marker_in": "sdoz",
    "optionlogo": "none",
    "outer_frame": "balloon-top",
    "framelabel": "SCAN ME",
    "label_font": "Arial, Helvetica, sans-serif",
    "custom_frame_color": "on",
    "framecolor": "#3B0001"
}
Previzualizare rezultat exemplu

Envelope de răspuns cu succes

{
    "success": true,
    "data": {
        "qrid": "1284",
        "svg": "<svg ...>...</svg>",
        "type": "static",
        "title": "Pricing Poster QR",
        "dashboard_url": "https://createqr.app/app/qrs/1284",
        "download_url": "https://createqr.app/app/qrs/1284/download/svg"
    },
    "request_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}

Șterge coduri QR

Ștergi un QR după ID, doar dacă îți aparține.

POST https://createqr.app/api/v1/delete

Body request

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "qrid": "1284"
}

Răspuns

{
    "success": true,
    "data": {
        "deleted": true,
        "qrid": "1284"
    },
    "request_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}

Listează coduri QR

Listezi QR-urile tale în pagini de 100, ordonate de la cele mai noi.

POST https://createqr.app/api/v1/list

Folosește pagination începând de la 1. Rezultatele returnează maximum 100 de elemente pe pagină.

Body request

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "pagination": "1"
}

Răspuns

{
    "success": true,
    "data": {
        "pagination": "1",
        "page_size": 100,
        "total": 2,
        "items": [
            {
                "qrid": "1284",
                "title": "Campaign QR",
                "type": "dynamic",
                "created_at": "2026-02-17 09:12:30",
                "short_url": "https://createqr.app/r/a1b2c3",
                "dashboard_url": "https://createqr.app/app/qrs/1284"
            },
            {
                "qrid": "1269",
                "title": "Storefront QR",
                "type": "static",
                "created_at": "2026-02-17 08:02:08",
                "dashboard_url": "https://createqr.app/app/qrs/1269"
            }
        ]
    },
    "request_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}

Răspunsuri de eroare, limite și retry

Fiecare răspuns include request_id. Păstrează-l când contactezi suportul, ca să putem investiga rapid.

Envelope tipic de eroare

{
    "success": false,
    "error": {
        "code": "validation_error",
        "message": "Dynamic QR requires a valid URL in data."
    },
    "request_id": "5f5fbd38-f82f-49ad-bf11-f7f04ca9747a"
}

Strategie de retry

  • 429 rate_limited: reîncearcă folosind exponential backoff plus jitter.
  • Respectă Retry-After atunci când este prezent.
  • 429 monthly_quota_exceeded: așteaptă resetarea cotei sau folosește o cheie care mai are disponibilitate.
  • 5xx: reîncearcă de câteva ori, apoi alertează echipa ta.
Cod eroare HTTP Când apare Ce ai de făcut
invalid_api_key 401 Cheia API lipsește sau este invalidă Trimite o cheie validă prin Bearer, X-API-Key sau câmp JSON.
invalid_content_type 415 Body-ul nu este application/json Trimite Content-Type: application/json.
request_too_large 413 Payload-ul depășește limita configurată Redu dimensiunea body-ului, mai ales pentru logo-uri base64.
plan_upgrade_required 403 Planul nu permite acces API Fă upgrade la Business din Facturare.
validation_error 422 Câmpuri invalide precum URL, culoare sau folderid Corectează payload-ul și trimite din nou.
rate_limited 429 Ai atins limita pe minut Reîncearcă cu exponential backoff și respectă Retry-After.
monthly_quota_exceeded 429 Cota lunară este epuizată Așteaptă resetarea sau ajustează cota și setările cheii.
qr_not_found 404 QR-ul de șters nu există sau nu îți aparține Verifică ownership-ul pentru qrid și încearcă din nou.
internal_error 500 A apărut o problemă internă neașteptată Reîncearcă cu backoff și păstrează request_id pentru suport.

FAQ

Răspunsuri scurte la întrebările pe care le vedem cel mai des în integrări.

Câte request-uri API pot rula?

API-ul este disponibil pe Business. Cota lunară depinde de planul activ și de eventualele override-uri pe cheie. Seed-ul implicit pentru Business este generos, iar adminii pot ajusta fin fiecare cheie.

Pot trimite cheia API în body-ul JSON?

Da. Autentificarea prin header rămâne recomandată, dar câmpurile apikey și api_key sunt acceptate pentru compatibilitate.

QR-urile create prin API apar în dashboard?

Da. Fiecare request de creare reușit este salvat în contul tău și poate fi administrat ca orice alt QR.

Ce se întâmplă când ating limitele?

Primești erori JSON. Pentru răspunsurile 429, respectă Retry-After și folosește exponential backoff cu jitter.

Pot șterge un QR din alt cont?

Nu. Operațiunile de delete și list sunt limitate la proprietarul cheii API autentificate.

Bune practici de securitate

  • Nu expune niciodată cheile API brute în JavaScript din browser, bundle-uri mobile sau repo-uri publice.
  • Folosește allowlist-uri IP pentru cheile API, ca să limitezi utilizarea la servere de încredere.
  • Înregistrează request_id împreună cu propriile trace ID-uri pentru triere mai rapidă a incidentelor.
  • Rotește cheile periodic și imediat după orice scurgere de credențiale.
Deschide managerul de chei API