QRay API

Buat kode QR dari aplikasi Anda melalui REST API sederhana: 8 tipe data, PNG dan SVG, warna, gradien, logo, dan bingkai — semua yang bisa dilakukan generator web.

Dapatkan kunci API https://stg.qray.io/api/v1

Coba sekarang — tanpa daftar

Tempel ini di terminal. Satu permintaan, langsung dapat kode QR asli:

curl -X POST https://stg.qray.io/api/v1/demo \
  -H "Content-Type: application/json" \
  -d '{"qr":{"type":"url","fields":{"url":"https://qray.io"},"style":{"dot_style":"rounded","gradient":{"colors":["#2563EB","#A3E635"],"angle":45}}}}' \
  -o qr.png && open qr.png

Membuka qr.png (macOS; di Linux pakai xdg-open qr.png). Tanpa kunci — demo mengizinkan 10 permintaan/jam per IP.

Autentikasi

Setiap permintaan harus menyertakan kunci API di header X-Api-Key. Buat dan kelola kunci di dasbor Anda.

curl https://stg.qray.io/api/v1/usage \
  -H "X-Api-Key: qray_live_YOUR_KEY"

Kunci lengkap hanya ditampilkan sekali, saat dibuat. Simpan di secret manager — kami hanya menyimpan digest SHA-256.

Mulai cepat

Buat kode QR bergaya untuk sebuah URL:

curl -X POST https://stg.qray.io/api/v1/generate \
  -H "X-Api-Key: qray_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "qr": {
      "type": "url",
      "fields": { "url": "https://example.com" },
      "format": "png",
      "size": 512,
      "style": {
        "fg_color": "#111113",
        "dot_style": "rounded",
        "gradient": { "colors": ["#2563EB", "#A3E635"], "angle": 45 }
      }
    }
  }'

Respons berisi gambar dalam base64 serta URL permanen:

{
  "hash": "1c9a7f2b40d861e3",
  "format": "png",
  "size": 512,
  "image": "iVBORw0KGgoAAA…",          // base64
  "image_url": "https://stg.qray.io/qr/1c9a7f2b40d861e3.png",
  "share_url": "https://stg.qray.io/qr/1c9a7f2b40d861e3",
  "url": "/qr/1c9a7f2b40d861e3"
}

Endpoint

Endpoint	Deskripsi
`POST /api/v1/demo`	Membuat gambar QR tanpa kunci (demo, 10/jam per IP)
`POST /api/v1/generate`	Membuat kode QR; mengembalikan gambar base64 dan URL permanen
`GET /api/v1/qr_codes`	Daftar kode QR Anda (50 per halaman, ?page=N)
`GET /api/v1/qr_codes/:hash`	Metadata satu kode QR
`GET /api/v1/qr_codes/:hash/image`	Gambar biner (PNG/SVG); URL tidak pernah kedaluwarsa
`DELETE /api/v1/qr_codes/:hash`	Menghapus kode QR
`GET /api/v1/usage`	Paket saat ini, batas harian, dan pemakaian
`GET /api/v1/api_keys`	Daftar kunci API Anda
`POST /api/v1/api_keys`	Membuat kunci tambahan ({"name": "…"})
`DELETE /api/v1/api_keys/:id`	Mencabut kunci (kunci yang dipakai permintaan ini tidak bisa dicabut)

Butuh spesifikasi machine-readable? Jelajahi secara interaktif atau impor file OpenAPI kami ke Postman, Insomnia, atau generator klien: Penjelajah API interaktif · openapi.yaml

Tipe QR dan kolomnya

Kirim tipe data di qr.type dan kolomnya di qr.fields:

type	fields
`url`	`url`
`text`	`text`
`wifi`	`ssid`, `password`, `encryption` (WPA \| WEP \| nopass), `hidden` (true \| false)
`vcard`	`first_name`, `last_name`, `phone`, `email`, `org`, `title`, `url`
`email`	`address`, `subject`, `body`
`phone`	`number`
`sms`	`number`, `message`
`geo`	`latitude`, `longitude`

Misalnya, QR WiFi yang bisa dipindai tamu untuk terhubung:

curl -X POST https://stg.qray.io/api/v1/demo \
  -H "Content-Type: application/json" \
  -d '{"qr":{"type":"wifi","fields":{"ssid":"MyCafe","password":"latte123","encryption":"WPA"}}}' \
  -o wifi.png && open wifi.png

Opsi dan gaya

Parameter	Deskripsi
`format`	`png` (default) \| `svg`
`size`	`256` \| `512` (default) \| `1024` \| `2048`
`style.fg_color`, `style.bg_color`	hex, e.g. `#111113`
`style.dot_style`	`square` (default) \| `circle` \| `rounded`
`style.eye_style`	`square` (default) \| `rounded`
`style.gradient`	`{ "colors": ["#hex", "#hex", …], "angle": 0–360 }` — dua warna atau lebih; menggantikan fg_color
`style.frame`	`{ "type": "scan-me" \| "custom-text", "text": "…", "color": "#hex" }` — hanya PNG; diabaikan untuk SVG
`style.logo_data`	PNG/JPG dalam base64 mentah (tanpa prefiks data:), maks ~500 KB. Koreksi kesalahan dinaikkan otomatis.

Gambar di-cache 24 jam lalu diregenerasi secara transparan — image_url permanen dan aman untuk hotlink.

Paket dan batas

Setiap kunci punya kuota harian yang direset tengah malam UTC:

Paket	Permintaan
free	100 permintaan / hari
pro	10 000 permintaan / hari
enterprise	100 000 permintaan / hari

Setiap respons memuat status jendela saat ini:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87

Butuh pro atau enterprise? Tulis ke support@qray.io — kami tingkatkan kunci Anda.

Kesalahan

HTTP	`error`	Deskripsi
400	`missing_parameter`	Permintaan tidak valid (mis. parameter qr hilang)
401	`unauthorized`	Kunci API hilang, salah, atau dicabut
404	`not_found`	Kode QR tidak ditemukan (atau milik akun lain)
422	`unknown_type`	qr.type tidak dikenal
429	`rate_limited`	Batas harian habis — coba lagi setelah tengah malam UTC atau tingkatkan paket
503	`service_unavailable`	Layanan pembuatan QR sementara tidak tersedia — coba lagi dengan backoff