İçeriğe geç
oqur

Kodlarını kendi sisteminden yönet.

Yüzlerce QR kodu tek istekle oluştur, hedeflerini güncelle, tarama raporlarını kendi paneline çek. REST, JSON ve bir API anahtarı yeterli.

Taslak — endpoint'ler geliştirme sırasında netleşecek. Bu sayfa önerilen yapıyı gösterir; canlı bir API henüz yok. Adresler, alan adları, limitler ve yanıt biçimleri değişebilir.

Temel adres
https://api.oqur.io/v1
Biçim
JSON, UTF-8, HTTPS
Kimlik doğrulama
Bearer API anahtarı
Planlar
İşletme ve Kurumsal

Başlarken

oqur API, panelde yaptığın işleri kendi yazılımından yapmanı sağlar: toplu QR oluşturma, hedef güncelleme, baskı dosyası indirme ve tarama raporları. Tüm istekler HTTPS üzerinden, JSON gövdeyle yapılır.

  1. Anahtar oluştur

    Panelde Ayarlar menüsündeki API anahtarları bölümünden bir anahtar oluştur ve yetkilerini seç. API hazır olduğunda İşletme ve Kurumsal planlarda açılacak.

  2. İlk isteğini gönder

    Yandaki örnek hesabındaki ilk kodu listeler. Yanıt 200 dönüyorsa her şey hazır.

  3. Limitleri izle

    Kalan istek hakkın her yanıtın başlıklarında yazar. Ayrıntılar Hız limitleri bölümünde.

Kurallar

KonuBiçimAçıklama
Tarih ve saat ISO 8601 Her zaman UTC döner: 2026-09-30T09:12:44Z. Raporlarda istediğin saat dilimini seçebilirsin.
Kimlikler string Önekli metin: QR kodlar qr_, klasörler fld_, istekler req_ ile başlar.
Sayfalama integer page ve per_page ile. Sayfa başına en fazla 100 kayıt.
Sürüm v1 Adresteki sürüm. Geriye dönük uyumsuz değişiklikler yalnızca yeni sürümle gelir.
curl "https://api.oqur.io/v1/qr-codes?per_page=1" \
  -H "Authorization: Bearer $OQUR_API_KEY" \
  -H "Accept: application/json"
<?php
// composer require guzzlehttp/guzzle
use GuzzleHttp\Client;

$oqur = new Client([
    'base_uri' => 'https://api.oqur.io/v1/',
    'headers'  => [
        'Authorization' => 'Bearer ' . getenv('OQUR_API_KEY'),
        'Accept'        => 'application/json',
    ],
]);

$res  = $oqur->get('qr-codes', ['query' => ['per_page' => 1]]);
$body = json_decode($res->getBody(), true);
// Node 18+ or other non-browser runtimes
const oqur = (path, init = {}) =>
  fetch(`https://api.oqur.io/v1${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.OQUR_API_KEY}`,
      'Content-Type': 'application/json',
      Accept: 'application/json',
      ...init.headers,
    },
  }).then((r) => r.json());

const body = await oqur('/qr-codes?per_page=1');

Yanıt 200 ÖRNEK

{
  "data": [
    {
      "id": "qr_7Kq2mX",
      "type": "menu",
      "name": "Kafe Rıhtım · Table card",
      "status": "active",
      "dynamic": true,
      "short_url": "https://oqur.io/d/7Kq2xP",
      "created_at": "2026-09-12T08:30:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 1, "total": 42 }
}

Kimlik doğrulama

Her isteğe Authorization başlığında API anahtarını ekle. Anahtarsız ya da geçersiz anahtarlı istekler 401, yetkisi yetmeyen anahtarlar 403 döner.

  • Anahtarı yalnızca sunucu tarafında kullan; tarayıcıya ya da mobil uygulamaya gömme.
  • Her entegrasyon için ayrı anahtar oluştur. Biri sızarsa yalnızca onu iptal edersin.
  • Anahtara yalnızca ihtiyaç duyduğu yetkileri ver: qr:read, qr:write, analytics:read, folders:write.

Başlıklar

BaşlıkTürAçıklama
Authorizationzorunlu string Bearer ve ardından API anahtarın.
Content-Type string Gövdeli isteklerde application/json.
Accept string application/json.
Idempotency-Key string Oluşturma isteklerini güvenle tekrar denemek için benzersiz bir değer. Aynı anahtarla 24 saat içinde gelen istek ilk yanıtı döndürür.

İstek başlıklarıÖRNEK

Authorization: Bearer oqur_live_8f3kQ2…
Content-Type: application/json
Accept: application/json

Yanıt 401 ÖRNEK

{
  "error": {
    "code": "unauthenticated",
    "message": "The API key is missing or invalid.",
    "request_id": "req_5nT2pW"
  }
}

Hız limitleri

Her API anahtarı dakikada 60 istek yapabilir; Kurumsal planda limit ihtiyaca göre belirlenir. Toplu uç noktalar tek istekte 100 öğe işler, yani dakikada 6.000 koda kadar oluşturabilir ya da düzenleyebilirsin.

Yanıt başlıkları

BaşlıkTürAçıklama
X-RateLimit-Limit integer Dakikalık toplam istek hakkın.
X-RateLimit-Remaining integer Bu dakika için kalan istek.
X-RateLimit-Reset integer Hakkın yenileneceği an, Unix zaman damgası.
Retry-After integer Yalnızca 429 yanıtında: kaç saniye beklemen gerektiği.

429 aldığında Retry-After kadar bekleyip tekrar dene. Art arda hatalarda bekleme süresini her denemede ikiye katlamak en güvenli yoldur.

Yanıt 429 ÖRNEK

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790759580
Retry-After: 18

{
  "error": {
    "code": "rate_limited",
    "message": "You used up your requests for this minute. Try again in 18 seconds.",
    "request_id": "req_9kP1sV"
  }
}

QR kodlar

Kod oluşturma, düzenleme ve baskı dosyası üretme. Dinamik bir kodun hedefini değiştirmek kısa bağlantıyı değiştirmez: basılı kod aynı kalır.

Toplu oluştur

POST /qr-codes/bulk

Tek istekte en fazla 100 QR kod oluşturur. Her öğe ayrı doğrulanır; geçersiz bir öğe varsa hiçbiri oluşturulmaz ve hatalar öğe sırasıyla döner.

Kimlik doğrulama: ApiKeyAuth (Bearer)Yetki: qr:write

Başlıklar

BaşlıkTürAçıklama
Idempotency-Key string İsteği güvenle tekrar göndermek için benzersiz bir değer.

İstek gövdesi

AlanTürAçıklama
itemszorunlu array Oluşturulacak kodlar. En az 1, en fazla 100 öğe.
items[].typezorunlu string QR tipi: url, pdf, menu, vcard-plus, wifi gibi 24 tipten biri.
items[].targetzorunlu object Tipe göre değişen hedef. url tipinde url alanı, pdf tipinde file_url alanı.
items[].name string Panelde görünen ad. En fazla 120 karakter.
items[].folder_id string Kodun ekleneceği klasör.
items[].design object Renk, desen, köşe, logo ve çerçeve. Boş bırakırsan hesabının varsayılan şablonu kullanılır.

Q5 hattındaki tipler (wifi, text, vcard, email, sms, whatsapp) statik oluşturulur ve dinamik kod kotandan düşmez.

Durum kodları

  • 201 Kodlar oluşturuldu.
  • 401 API anahtarı eksik ya da geçersiz.
  • 403 Planın API'ye ya da bu kadar dinamik koda izin vermiyor.
  • 422 Bir ya da daha fazla öğe geçersiz; ayrıntılar details dizisinde.
  • 429 Hız limitine takıldın; Retry-After kadar bekle.
curl -X POST https://api.oqur.io/v1/qr-codes/bulk \
  -H "Authorization: Bearer $OQUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: campaign-september-01" \
  -d '{
    "items": [
      {
        "type": "url",
        "name": "Poster · Kadıköy",
        "target": { "url": "https://cafename.com/campaign" },
        "folder_id": "fld_91xQ"
      },
      {
        "type": "pdf",
        "name": "Katalog 2026",
        "target": { "file_url": "https://kafeadi.com/katalog.pdf" }
      }
    ]
  }'
<?php
// $oqur: the client from Getting started
$res = $oqur->post('qr-codes/bulk', [
    'headers' => ['Idempotency-Key' => 'campaign-september-01'],
    'json'    => [
        'items' => [
            [
                'type'      => 'url',
                'name'      => 'Poster · Kadıköy',
                'target'    => ['url' => 'https://cafename.com/campaign'],
                'folder_id' => 'fld_91xQ',
            ],
            [
                'type'   => 'pdf',
                'name'   => 'Katalog 2026',
                'target' => ['file_url' => 'https://kafeadi.com/katalog.pdf'],
            ],
        ],
    ],
]);
// oqur(): the helper from Getting started
const { data } = await oqur('/qr-codes/bulk', {
  method: 'POST',
  headers: { 'Idempotency-Key': 'campaign-september-01' },
  body: JSON.stringify({
    items: [
      {
        type: 'url',
        name: 'Poster · Kadıköy',
        target: { url: 'https://cafename.com/campaign' },
        folder_id: 'fld_91xQ',
      },
      {
        type: 'pdf',
        name: 'Katalog 2026',
        target: { file_url: 'https://kafeadi.com/katalog.pdf' },
      },
    ],
  }),
});

Yanıt 201 ÖRNEK

{
  "data": [
    {
      "id": "qr_7Kq2mX",
      "type": "url",
      "name": "Poster · Kadıköy",
      "status": "active",
      "dynamic": true,
      "short_url": "https://oqur.io/d/7Kq2xP",
      "folder_id": "fld_91xQ",
      "created_at": "2026-09-30T09:12:44Z"
    },
    {
      "id": "qr_8Lr3nY",
      "type": "pdf",
      "name": "Katalog 2026",
      "status": "active",
      "dynamic": true,
      "short_url": "https://oqur.io/d/8Lr3nQ",
      "folder_id": null,
      "created_at": "2026-09-30T09:12:44Z"
    }
  ],
  "meta": { "created": 2 }
}

Toplu düzenle

PATCH /qr-codes/bulk

En fazla 100 kodu tek istekte günceller. Yalnızca gönderdiğin alanlar değişir; kısa bağlantı ve basılı kod aynı kalır.

Kimlik doğrulama: ApiKeyAuth (Bearer)Yetki: qr:write

İstek gövdesi

AlanTürAçıklama
itemszorunlu array Güncellenecek kodlar. En az 1, en fazla 100 öğe.
items[].idzorunlu string Kodun kimliği.
items[].target object Yeni hedef. Sonraki taramalar hemen yeni hedefe gider.
items[].status string active ya da paused. Duraklatılan kodu tarayanlar sade bir “geçici olarak kapalı” sayfası görür.
items[].name string Yeni ad.
items[].folder_id string Taşınacağı klasör; klasörden çıkarmak için null.
items[].design object Tasarım alanları. Gönderdiğin alt alanlar birleştirilir.

Durum kodları

  • 200 Kodlar güncellendi.
  • 401 API anahtarı eksik ya da geçersiz.
  • 404 Listedeki bir kod bulunamadı ya da sana ait değil.
  • 422 Bir öğe geçersiz; hiçbir kod güncellenmedi.
  • 429 Hız limitine takıldın.
curl -X PATCH https://api.oqur.io/v1/qr-codes/bulk \
  -H "Authorization: Bearer $OQUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "id": "qr_7Kq2mX", "target": { "url": "https://kafeadi.com/ekim" } },
      { "id": "qr_8Lr3nY", "status": "paused" }
    ]
  }'
<?php
$res = $oqur->patch('qr-codes/bulk', [
    'json' => [
        'items' => [
            ['id' => 'qr_7Kq2mX', 'target' => ['url' => 'https://kafeadi.com/ekim']],
            ['id' => 'qr_8Lr3nY', 'status' => 'paused'],
        ],
    ],
]);
const { data } = await oqur('/qr-codes/bulk', {
  method: 'PATCH',
  body: JSON.stringify({
    items: [
      { id: 'qr_7Kq2mX', target: { url: 'https://kafeadi.com/ekim' } },
      { id: 'qr_8Lr3nY', status: 'paused' },
    ],
  }),
});

Yanıt 200 ÖRNEK

{
  "data": [
    { "id": "qr_7Kq2mX", "status": "active", "updated_at": "2026-09-30T10:04:12Z" },
    { "id": "qr_8Lr3nY", "status": "paused", "updated_at": "2026-09-30T10:04:12Z" }
  ],
  "meta": { "updated": 2 }
}

Listele

GET /qr-codes

Hesabındaki kodları sayfalı olarak döndürür. Varsayılan sıralama en yeniden eskiye.

Kimlik doğrulama: ApiKeyAuth (Bearer)Yetki: qr:read

Sorgu parametreleri

AlanTürAçıklama
page integer Sayfa numarası. Varsayılan 1.
per_page integer Sayfa başına kayıt. Varsayılan 25, en fazla 100.
folder_id string Yalnızca bu klasördeki kodlar.
type string Tipe göre filtre, örneğin menu.
status string draft, scheduled, active ya da paused.
search string Ad ya da kısa bağlantıda arar.
sort string created_at, name ya da scans_total. Azalan sıra için başına eksi koy: -scans_total.

Durum kodları

  • 200 Liste döndü; sonuç yoksa data boş dizidir.
  • 401 API anahtarı eksik ya da geçersiz.
  • 422 Geçersiz filtre ya da sıralama değeri.
curl -G https://api.oqur.io/v1/qr-codes \
  -H "Authorization: Bearer $OQUR_API_KEY" \
  -d folder_id=fld_91xQ \
  -d status=active \
  -d sort=-scans_total \
  -d per_page=25
<?php
$res = $oqur->get('qr-codes', ['query' => [
    'folder_id' => 'fld_91xQ',
    'status'    => 'active',
    'sort'      => '-scans_total',
    'per_page'  => 25,
]]);
const params = new URLSearchParams({
  folder_id: 'fld_91xQ',
  status: 'active',
  sort: '-scans_total',
  per_page: '25',
});
const { data, meta } = await oqur(`/qr-codes?${params}`);

Yanıt 200 ÖRNEK

{
  "data": [
    {
      "id": "qr_7Kq2mX",
      "type": "url",
      "name": "Poster · Kadıköy",
      "status": "active",
      "short_url": "https://oqur.io/d/7Kq2xP",
      "scans_total": 312,
      "created_at": "2026-09-12T08:30:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 1 },
  "links": { "next": null, "prev": null }
}

Getir

GET /qr-codes/{id}

Tek bir kodun tüm alanlarını döndürür: hedef, tasarım, durum ve toplam tarama sayısı.

Kimlik doğrulama: ApiKeyAuth (Bearer)Yetki: qr:read

Yol parametreleri

AlanTürAçıklama
idzorunlu string Kodun kimliği, örneğin qr_7Kq2mX.

Durum kodları

  • 200 Kod bulundu.
  • 401 API anahtarı eksik ya da geçersiz.
  • 404 Kod yok ya da sana ait değil.
curl https://api.oqur.io/v1/qr-codes/qr_7Kq2mX \
  -H "Authorization: Bearer $OQUR_API_KEY"
<?php
$res  = $oqur->get('qr-codes/qr_7Kq2mX');
$code = json_decode($res->getBody(), true)['data'];
const { data: code } = await oqur('/qr-codes/qr_7Kq2mX');

Yanıt 200 ÖRNEK

{
  "data": {
    "id": "qr_7Kq2mX",
    "type": "url",
    "name": "Poster · Kadıköy",
    "status": "active",
    "dynamic": true,
    "short_url": "https://oqur.io/d/7Kq2xP",
    "target": { "url": "https://cafename.com/campaign" },
    "folder_id": "fld_91xQ",
    "design": {
      "foreground": "#0B1F3A",
      "background": "#FFFFFF",
      "dots": "rounded",
      "corners": "square",
      "logo_url": null,
      "frame": { "style": "bottom", "text": "Beni tara" },
      "error_correction": "M"
    },
    "scans_total": 312,
    "created_at": "2026-09-12T08:30:00Z",
    "updated_at": "2026-09-28T17:02:10Z"
  }
}

Güncelle

PATCH /qr-codes/{id}

Tek bir kodu günceller. Hedefi değiştirmek kodu değiştirmez: basılı QR aynı kalır, sonraki taramalar yeni hedefe gider.

Kimlik doğrulama: ApiKeyAuth (Bearer)Yetki: qr:write

Yol parametreleri

AlanTürAçıklama
idzorunlu string Kodun kimliği.

İstek gövdesi

AlanTürAçıklama
target object Yeni hedef. Statik kodlarda değiştirilemez.
status string active ya da paused.
name string Yeni ad.
folder_id string Taşınacağı klasör; klasörden çıkarmak için null.
design object Tasarım alanları. Gönderdiğin alt alanlar birleştirilir.

Durum kodları

  • 200 Kod güncellendi.
  • 401 API anahtarı eksik ya da geçersiz.
  • 404 Kod yok ya da sana ait değil.
  • 422 Geçersiz alan; örneğin statik bir kodun hedefi değiştirilemez.
curl -X PATCH https://api.oqur.io/v1/qr-codes/qr_7Kq2mX \
  -H "Authorization: Bearer $OQUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "target": { "url": "https://kafeadi.com/kis-menusu" } }'
<?php
$res = $oqur->patch('qr-codes/qr_7Kq2mX', [
    'json' => ['target' => ['url' => 'https://kafeadi.com/kis-menusu']],
]);
const { data } = await oqur('/qr-codes/qr_7Kq2mX', {
  method: 'PATCH',
  body: JSON.stringify({ target: { url: 'https://kafeadi.com/kis-menusu' } }),
});

Yanıt 200 ÖRNEK

{
  "data": {
    "id": "qr_7Kq2mX",
    "status": "active",
    "short_url": "https://oqur.io/d/7Kq2xP",
    "target": { "url": "https://kafeadi.com/kis-menusu" },
    "updated_at": "2026-09-30T10:15:03Z"
  }
}

Çoğalt

POST /qr-codes/{id}/duplicate

Kodu tasarımı ve hedefiyle birlikte kopyalar. Kopya yeni bir kısa bağlantıyla ve sıfır taramayla başlar; şubeler için aynı tasarımı çoğaltmanın en hızlı yolu.

Kimlik doğrulama: ApiKeyAuth (Bearer)Yetki: qr:write

Yol parametreleri

AlanTürAçıklama
idzorunlu string Kopyalanacak kodun kimliği.

İstek gövdesi

AlanTürAçıklama
name string Kopyanın adı. Boş bırakırsan asıl adın sonuna “(kopya)” eklenir.
folder_id string Kopyanın ekleneceği klasör. Varsayılan: asıl kodun klasörü.

Durum kodları

  • 201 Kopya oluşturuldu.
  • 401 API anahtarı eksik ya da geçersiz.
  • 403 Dinamik kod limitine ulaştın.
  • 404 Kod yok ya da sana ait değil.
curl -X POST https://api.oqur.io/v1/qr-codes/qr_7Kq2mX/duplicate \
  -H "Authorization: Bearer $OQUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Poster · Beşiktaş" }'
<?php
$res = $oqur->post('qr-codes/qr_7Kq2mX/duplicate', [
    'json' => ['name' => 'Poster · Beşiktaş'],
]);
const { data: copy } = await oqur('/qr-codes/qr_7Kq2mX/duplicate', {
  method: 'POST',
  body: JSON.stringify({ name: 'Poster · Beşiktaş' }),
});

Yanıt 201 ÖRNEK

{
  "data": {
    "id": "qr_9Ms4pZ",
    "type": "url",
    "name": "Poster · Beşiktaş",
    "status": "active",
    "short_url": "https://oqur.io/d/9Ms4pR",
    "scans_total": 0,
    "created_at": "2026-09-30T10:20:31Z"
  }
}

Görsel oluştur

POST /qr-codes/{id}/image

Kodun baskıya hazır görselini üretir ve kısa süreli bir indirme bağlantısı döndürür. Kayıtlı tasarımı değiştirmeden bu görsele özel ayar geçebilirsin.

Kimlik doğrulama: ApiKeyAuth (Bearer)Yetki: qr:read

Yol parametreleri

AlanTürAçıklama
idzorunlu string Kodun kimliği.

İstek gövdesi

AlanTürAçıklama
formatzorunlu string png, svg, pdf ya da eps.
size integer PNG için kenar uzunluğu, piksel. 256 ile 4096 arası; varsayılan 1024.
margin integer Sessiz alan, modül sayısı. Varsayılan 4; daha azı önerilmez.
design object Yalnızca bu görsel için geçici tasarım ayarları.

İndirme bağlantısı 1 saat geçerlidir. Dosyayı kendi sunucunda saklamak istiyorsan Görsel al uç noktasını kullan.

Durum kodları

  • 200 Görsel hazır.
  • 401 API anahtarı eksik ya da geçersiz.
  • 404 Kod yok ya da sana ait değil.
  • 422 Desteklenmeyen format ya da boyut.
curl -X POST https://api.oqur.io/v1/qr-codes/qr_7Kq2mX/image \
  -H "Authorization: Bearer $OQUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "format": "svg", "margin": 4 }'
<?php
$res = $oqur->post('qr-codes/qr_7Kq2mX/image', [
    'json' => ['format' => 'svg', 'margin' => 4],
]);
$url = json_decode($res->getBody(), true)['data']['url'];
const { data } = await oqur('/qr-codes/qr_7Kq2mX/image', {
  method: 'POST',
  body: JSON.stringify({ format: 'svg', margin: 4 }),
});
console.log(data.url); // valid for 1 hour

Yanıt 200 ÖRNEK

{
  "data": {
    "format": "svg",
    "url": "https://cdn.oqur.io/r/qr_7Kq2mX.svg?sig=Vb8f2…",
    "expires_at": "2026-09-30T11:12:44Z"
  }
}

Görsel al

GET /qr-codes/{id}/image.{format}

Görseli doğrudan dosya olarak döndürür. Yanıt JSON değil, dosyanın kendisidir; sunucunda saklamak ya da baskı akışına eklemek için uygundur.

Kimlik doğrulama: ApiKeyAuth (Bearer)Yetki: qr:read

Yol parametreleri

AlanTürAçıklama
idzorunlu string Kodun kimliği.
formatzorunlu string png, svg, pdf ya da eps.

Sorgu parametreleri

AlanTürAçıklama
size integer PNG için kenar uzunluğu, piksel. Varsayılan 1024.
margin integer Sessiz alan, modül sayısı. Varsayılan 4.

Durum kodları

  • 200 Dosya döndü.
  • 401 API anahtarı eksik ya da geçersiz.
  • 404 Kod yok ya da sana ait değil.
  • 422 Desteklenmeyen format ya da boyut.
curl https://api.oqur.io/v1/qr-codes/qr_7Kq2mX/image.png?size=2048 \
  -H "Authorization: Bearer $OQUR_API_KEY" \
  -o masa-karti.png
<?php
$oqur->get('qr-codes/qr_7Kq2mX/image.png', [
    'query' => ['size' => 2048],
    'sink'  => __DIR__ . '/masa-karti.png',
]);
import { writeFile } from 'node:fs/promises';

const res = await fetch('https://api.oqur.io/v1/qr-codes/qr_7Kq2mX/image.png?size=2048', {
  headers: { Authorization: `Bearer ${process.env.OQUR_API_KEY}` },
});
await writeFile('masa-karti.png', Buffer.from(await res.arrayBuffer()));

Yanıt 200 ÖRNEK

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 48213
Content-Disposition: attachment; filename="qr_7Kq2mX.png"
Cache-Control: private, max-age=300

(ikili PNG verisi)

Toplu sil

DELETE /qr-codes?ids=…

En fazla 100 kodu çöp kutusuna taşır. Çöpteki kodlar 30 gün içinde panelden geri getirilebilir; çöpteki dinamik kodu tarayanlar “bu kod kullanılmıyor” sayfası görür. Kodu yalnızca durdurmak istiyorsan status alanını paused yap.

Kimlik doğrulama: ApiKeyAuth (Bearer)Yetki: qr:write

Sorgu parametreleri

AlanTürAçıklama
idszorunlu string Virgülle ayrılmış kod kimlikleri, en fazla 100.

Durum kodları

  • 200 Kodlar çöp kutusuna taşındı.
  • 401 API anahtarı eksik ya da geçersiz.
  • 404 Listedeki bir kod bulunamadı; hiçbir kod silinmedi.
  • 422 Kimlik listesi boş ya da 100'ü aşıyor.
curl -X DELETE "https://api.oqur.io/v1/qr-codes?ids=qr_7Kq2mX,qr_8Lr3nY,qr_9Ms4pZ" \
  -H "Authorization: Bearer $OQUR_API_KEY"
<?php
$res = $oqur->delete('qr-codes', ['query' => [
    'ids' => implode(',', ['qr_7Kq2mX', 'qr_8Lr3nY', 'qr_9Ms4pZ']),
]]);
const ids = ['qr_7Kq2mX', 'qr_8Lr3nY', 'qr_9Ms4pZ'].join(',');
const { meta } = await oqur(`/qr-codes?ids=${ids}`, { method: 'DELETE' });

Yanıt 200 ÖRNEK

{
  "meta": { "deleted": 3 }
}

Analitik

Tarama verisini kendi raporlarına çek. Rapor kişisel veri içermez: IP adresi, cihaz kimliği ya da tam konum dönmez.

Analitik raporu

GET /analytics/scans

Seçtiğin kodlar ve tarih aralığı için toplamları, zaman serisini ve kırılımı döndürür. Tarih ve saatler istediğin saat diliminde gruplanır.

Kimlik doğrulama: ApiKeyAuth (Bearer)Yetki: analytics:read

Sorgu parametreleri

AlanTürAçıklama
fromzorunlu date Başlangıç tarihi, YYYY-AA-GG.
tozorunlu date Bitiş tarihi, dahil. Aralık en fazla 366 gün.
qr_ids string Virgülle ayrılmış kod kimlikleri. Boş bırakırsan tüm kodlar.
timezone string IANA saat dilimi, örneğin Europe/Istanbul. Varsayılan: çalışma alanının saat dilimi.
group_by string hour, day, week ya da month. Varsayılan day.
breakdown string country, city, device, os ya da browser.

Durum kodları

  • 200 Rapor döndü.
  • 401 API anahtarı eksik ya da geçersiz.
  • 422 Tarih aralığı geçersiz ya da 366 günü aşıyor.
  • 429 Hız limitine takıldın.
curl -G https://api.oqur.io/v1/analytics/scans \
  -H "Authorization: Bearer $OQUR_API_KEY" \
  -d from=2026-09-01 \
  -d to=2026-09-07 \
  -d timezone=Europe/Istanbul \
  -d group_by=day \
  -d breakdown=device
<?php
$res = $oqur->get('analytics/scans', ['query' => [
    'from'      => '2026-09-01',
    'to'        => '2026-09-07',
    'timezone'  => 'Europe/Istanbul',
    'group_by'  => 'day',
    'breakdown' => 'device',
]]);
const params = new URLSearchParams({
  from: '2026-09-01',
  to: '2026-09-07',
  timezone: 'Europe/Istanbul',
  group_by: 'day',
  breakdown: 'device',
});
const { data: report } = await oqur(`/analytics/scans?${params}`);

Yanıt 200 ÖRNEK

{
  "data": {
    "range": { "from": "2026-09-01", "to": "2026-09-07", "timezone": "Europe/Istanbul" },
    "totals": { "scans": 1840, "unique_scans": 1312 },
    "series": [
      { "period": "2026-09-01", "scans": 212, "unique_scans": 160 },
      { "period": "2026-09-02", "scans": 247, "unique_scans": 181 }
    ],
    "breakdown": {
      "by": "device",
      "items": [
        { "key": "ios", "scans": 1011 },
        { "key": "android", "scans": 783 },
        { "key": "desktop", "scans": 46 }
      ]
    }
  }
}

Klasörler

Kodlarını şube, kampanya ya da müşteri bazında grupla. Ekipteki herkes tüm klasörleri görür; kimin ne yapabileceğini rolü belirler.

Klasör oluştur

POST /folders

Kodlarını gruplamak için yeni bir klasör oluşturur.

Kimlik doğrulama: ApiKeyAuth (Bearer)Yetki: folders:write

İstek gövdesi

AlanTürAçıklama
namezorunlu string Klasör adı, 1 ile 80 karakter arası. Hesabında benzersiz olmalı.

Durum kodları

  • 201 Klasör oluşturuldu.
  • 401 API anahtarı eksik ya da geçersiz.
  • 409 Bu adda bir klasör zaten var.
  • 422 Ad boş ya da 80 karakteri aşıyor.
curl -X POST https://api.oqur.io/v1/folders \
  -H "Authorization: Bearer $OQUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Kadıköy branch" }'
<?php
$res = $oqur->post('folders', ['json' => ['name' => 'Kadıköy branch']]);
const { data: folder } = await oqur('/folders', {
  method: 'POST',
  body: JSON.stringify({ name: 'Kadıköy branch' }),
});

Yanıt 201 ÖRNEK

{
  "data": {
    "id": "fld_91xQ",
    "name": "Kadıköy branch",
    "qr_count": 0,
    "created_at": "2026-09-30T10:31:08Z"
  }
}

Klasörleri listele

GET /folders

Hesabındaki klasörleri, içlerindeki kod sayısıyla birlikte döndürür.

Kimlik doğrulama: ApiKeyAuth (Bearer)Yetki: qr:read

Sorgu parametreleri

AlanTürAçıklama
page integer Sayfa numarası. Varsayılan 1.
per_page integer Sayfa başına kayıt. Varsayılan 25, en fazla 100.

Durum kodları

  • 200 Liste döndü.
  • 401 API anahtarı eksik ya da geçersiz.
curl https://api.oqur.io/v1/folders \
  -H "Authorization: Bearer $OQUR_API_KEY"
<?php
$res     = $oqur->get('folders');
$folders = json_decode($res->getBody(), true)['data'];
const { data: folders } = await oqur('/folders');

Yanıt 200 ÖRNEK

{
  "data": [
    { "id": "fld_91xQ", "name": "Kadıköy branch", "qr_count": 14 },
    { "id": "fld_22bR", "name": "Packaging · September", "qr_count": 120 }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 2 }
}

Hata kodları

Hatalar her zaman aynı biçimde döner: bir HTTP durum kodu ve bir error nesnesi. code alanı yazılımın, message alanı insanların okuması için; mesaj metni değişebilir, koda güven.

Durumlar

HTTPcodeAçıklama
400 bad_request İstek gövdesi okunamadı. JSON'un geçerli olduğundan ve Content-Type başlığından emin ol.
401 unauthenticated API anahtarı eksik ya da geçersiz. Authorization başlığını kontrol et.
403 forbidden Planın ya da anahtarının yetkisi bu işleme yetmiyor; örneğin dinamik kod limitine ulaştın.
404 not_found Kayıt yok ya da senin hesabına ait değil.
409 conflict Aynı adla bir kayıt var ya da Idempotency-Key farklı bir gövdeyle tekrar kullanıldı.
422 validation_failed Bir alan geçersiz. Hangi alanın neden reddedildiği details dizisinde.
429 rate_limited Hız limitine takıldın. Retry-After kadar bekle.
500 server_error Bizim tarafımızda bir sorun var. Tekrar dene; sürerse request_id ile bize yaz.

Yanıt 422 ÖRNEK

{
  "error": {
    "code": "validation_failed",
    "message": "2 items failed validation.",
    "details": [
      { "field": "items.0.target.url", "message": "Must be a valid web address." },
      { "field": "items.3.type", "message": "Bilinmeyen QR tipi: menu2." }
    ],
    "request_id": "req_3hV8qL"
  }
}

Bir sorun mu var?

request_id değeriyle bize yaz; isteğini bulup bakalım.

Teknik destek

Önce panelde dene, sonra otomatikleştir.

API hazır olduğunda İşletme ve Kurumsal planlarda açılacak. Kurumsal entegrasyonlar için satış ekibimizle konuşabilirsin.