Zum Inhalt springen
oqur

Verwalte deine Codes aus deinem eigenen System.

Erstelle Hunderte QR-Codes mit einer Anfrage, aktualisiere ihre Ziele, hol Scanberichte in dein eigenes Dashboard. REST, JSON und ein API-Schlüssel genügen.

Entwurf — die Endpunkte werden während der Entwicklung festgelegt. Diese Seite zeigt die vorgeschlagene Struktur; eine Live-API gibt es noch nicht. Adressen, Feldnamen, Limits und Antwortformate können sich ändern.

Basis-URL
https://api.oqur.io/v1
Format
JSON, UTF-8, HTTPS
Authentifizierung
Bearer-API-Schlüssel
Tarife
Business und Enterprise

Erste Schritte

Mit der oqur-API machst du aus deiner eigenen Software, was du im Panel machst: QR-Codes gesammelt erstellen, Ziele aktualisieren, Druckdateien herunterladen und Scanberichte abrufen. Jede Anfrage läuft über HTTPS mit einem JSON-Body.

  1. Schlüssel erstellen

    Erstell im Panel im Menü Einstellungen unter API-Schlüssel einen Schlüssel und wähl seine Scopes. Wenn die API fertig ist, öffnet sie in den Tarifen Business und Enterprise.

  2. Erste Anfrage senden

    Das Beispiel daneben listet den ersten Code in deinem Konto. Wenn die Antwort 200 ist, ist alles bereit.

  3. Limits im Blick behalten

    Deine verbleibenden Anfragen stehen in den Headern jeder Antwort. Details im Abschnitt Ratenlimits.

Regeln

ThemaFormatBeschreibung
Datum und Uhrzeit ISO 8601 Immer in UTC zurückgegeben: 2026-09-30T09:12:44Z. In Berichten kannst du die gewünschte Zeitzone wählen.
IDs string Text mit Präfix: QR-Codes beginnen mit qr_, Ordner mit fld_, Anfragen mit req_.
Paginierung integer Mit page und per_page. Höchstens 100 Einträge pro Seite.
Version v1 Die Version steht in der Adresse. Inkompatible Änderungen kommen nur mit einer neuen Version.
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+ oder andere Umgebungen außerhalb des Browsers
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');

Antwort 200 BEISPIEL

{
  "data": [
    {
      "id": "qr_7Kq2mX",
      "type": "menu",
      "name": "Kafe Rıhtım · Tischaufsteller",
      "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 }
}

Authentifizierung

Füg deinen API-Schlüssel jeder Anfrage im Header Authorization hinzu. Anfragen ohne oder mit ungültigem Schlüssel geben 401 zurück; Schlüssel ohne ausreichende Berechtigung geben 403 zurück.

  • Nutze den Schlüssel nur serverseitig; bette ihn nicht in einen Browser oder eine mobile App ein.
  • Erstell für jede Integration einen eigenen Schlüssel. Wenn einer durchsickert, widerrufst du nur diesen.
  • Gib einem Schlüssel nur die Scopes, die er braucht: qr:read, qr:write, analytics:read, folders:write.

Header

HeaderTypBeschreibung
AuthorizationPflicht string Bearer, gefolgt von deinem API-Schlüssel.
Content-Type string application/json bei Anfragen mit Body.
Accept string application/json.
Idempotency-Key string Ein eindeutiger Wert, um Erstellanfragen sicher zu wiederholen. Eine Anfrage mit demselben Schlüssel innerhalb von 24 Stunden gibt die erste Antwort zurück.

Anfrage-HeaderBEISPIEL

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

Antwort 401 BEISPIEL

{
  "error": {
    "code": "unauthenticated",
    "message": "Der API-Schlüssel fehlt oder ist ungültig.",
    "request_id": "req_5nT2pW"
  }
}

Ratenlimits

Jeder API-Schlüssel kann 60 Anfragen pro Minute stellen; im Tarif Enterprise wird das Limit nach deinem Bedarf festgelegt. Sammel-Endpunkte verarbeiten 100 Einträge pro Anfrage, so kannst du bis zu 6.000 Codes pro Minute erstellen oder bearbeiten.

Antwort-Header

HeaderTypBeschreibung
X-RateLimit-Limit integer Deine gesamten Anfragen pro Minute.
X-RateLimit-Remaining integer Für diese Minute verbleibende Anfragen.
X-RateLimit-Reset integer Wann dein Kontingent zurückgesetzt wird, als Unix-Zeitstempel.
Retry-After integer Nur bei einer 429-Antwort: wie viele Sekunden du warten sollst.

Wenn du 429 bekommst, warte Retry-After ab und versuch es erneut. Bei wiederholten Fehlern ist es am sichersten, die Wartezeit bei jedem Versuch zu verdoppeln.

Antwort 429 BEISPIEL

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": "Du hast deine Anfragen für diese Minute aufgebraucht. Versuch es in 18 Sekunden erneut.",
    "request_id": "req_9kP1sV"
  }
}

QR-Codes

Codes erstellen und bearbeiten und Druckdateien erzeugen. Das Ziel eines dynamischen Codes zu ändern, ändert seinen Kurzlink nicht: Der gedruckte Code bleibt gleich.

Gesammelt erstellen

POST /qr-codes/bulk

Erstellt bis zu 100 QR-Codes mit einer Anfrage. Jeder Eintrag wird einzeln geprüft; ist ein Eintrag ungültig, wird keiner erstellt und die Fehler kommen in der Reihenfolge der Einträge zurück.

Authentifizierung: ApiKeyAuth (Bearer)Scope: qr:write

Header

HeaderTypBeschreibung
Idempotency-Key string Ein eindeutiger Wert, um die Anfrage sicher erneut zu senden.

Anfragebody

FeldTypBeschreibung
itemsPflicht array Die zu erstellenden Codes. Mindestens 1, höchstens 100 Einträge.
items[].typePflicht string QR-Typ: einer der 24 Typen wie url, pdf, menu, vcard-plus, wifi.
items[].targetPflicht object Ein Ziel, das vom Typ abhängt. Das Feld url beim Typ url, das Feld file_url beim Typ pdf.
items[].name string Der im Panel gezeigte Name. Höchstens 120 Zeichen.
items[].folder_id string Der Ordner, in den der Code kommt.
items[].design object Farbe, Muster, Ecken, Logo und Rahmen. Bleibt es leer, wird die Standardvorlage deines Kontos genutzt.

Typen der Linie Q5 (wifi, text, vcard, email, sms, whatsapp) werden statisch erstellt und zählen nicht zu deinem Kontingent an dynamischen Codes.

Statuscodes

  • 201 Die Codes wurden erstellt.
  • 401 Der API-Schlüssel fehlt oder ist ungültig.
  • 403 Dein Tarif erlaubt die API oder so viele dynamische Codes nicht.
  • 422 Ein oder mehrere Einträge sind ungültig; die Details stehen im Array details.
  • 429 Du hast das Ratenlimit erreicht; warte Retry-After ab.
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": "Plakat · Kadıköy",
        "target": { "url": "https://cafename.de/kampagne" },
        "folder_id": "fld_91xQ"
      },
      {
        "type": "pdf",
        "name": "Katalog 2026",
        "target": { "file_url": "https://kafeadi.com/katalog.pdf" }
      }
    ]
  }'
<?php
// $oqur: der Client aus Erste Schritte
$res = $oqur->post('qr-codes/bulk', [
    'headers' => ['Idempotency-Key' => 'campaign-september-01'],
    'json'    => [
        'items' => [
            [
                'type'      => 'url',
                'name'      => 'Plakat · Kadıköy',
                'target'    => ['url' => 'https://cafename.de/kampagne'],
                'folder_id' => 'fld_91xQ',
            ],
            [
                'type'   => 'pdf',
                'name'   => 'Katalog 2026',
                'target' => ['file_url' => 'https://kafeadi.com/katalog.pdf'],
            ],
        ],
    ],
]);
// oqur(): der Helfer aus Erste Schritte
const { data } = await oqur('/qr-codes/bulk', {
  method: 'POST',
  headers: { 'Idempotency-Key': 'campaign-september-01' },
  body: JSON.stringify({
    items: [
      {
        type: 'url',
        name: 'Plakat · Kadıköy',
        target: { url: 'https://cafename.de/kampagne' },
        folder_id: 'fld_91xQ',
      },
      {
        type: 'pdf',
        name: 'Katalog 2026',
        target: { file_url: 'https://kafeadi.com/katalog.pdf' },
      },
    ],
  }),
});

Antwort 201 BEISPIEL

{
  "data": [
    {
      "id": "qr_7Kq2mX",
      "type": "url",
      "name": "Plakat · 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 }
}

Gesammelt aktualisieren

PATCH /qr-codes/bulk

Aktualisiert bis zu 100 Codes mit einer Anfrage. Nur die gesendeten Felder ändern sich; Kurzlink und gedruckter Code bleiben gleich.

Authentifizierung: ApiKeyAuth (Bearer)Scope: qr:write

Anfragebody

FeldTypBeschreibung
itemsPflicht array Die zu aktualisierenden Codes. Mindestens 1, höchstens 100 Einträge.
items[].idPflicht string Die ID des Codes.
items[].target object Das neue Ziel. Die nächsten Scans gehen sofort dorthin.
items[].status string active oder paused. Wer einen pausierten Code scannt, sieht eine schlichte Seite „vorübergehend geschlossen“.
items[].name string Der neue Name.
items[].folder_id string Der Zielordner; null, um ihn aus dem Ordner zu nehmen.
items[].design object Designfelder. Die gesendeten Unterfelder werden zusammengeführt.

Statuscodes

  • 200 Die Codes wurden aktualisiert.
  • 401 Der API-Schlüssel fehlt oder ist ungültig.
  • 404 Ein Code in der Liste wurde nicht gefunden oder gehört nicht dir.
  • 422 Ein Eintrag ist ungültig; kein Code wurde aktualisiert.
  • 429 Du hast das Ratenlimit erreicht.
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' },
    ],
  }),
});

Antwort 200 BEISPIEL

{
  "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 }
}

Auflisten

GET /qr-codes

Gibt die Codes deines Kontos seitenweise zurück. Standardmäßig die neuesten zuerst.

Authentifizierung: ApiKeyAuth (Bearer)Scope: qr:read

Query-Parameter

FeldTypBeschreibung
page integer Seitennummer. Standard 1.
per_page integer Einträge pro Seite. Standard 25, höchstens 100.
folder_id string Nur die Codes in diesem Ordner.
type string Nach Typ filtern, zum Beispiel menu.
status string draft, scheduled, active oder paused.
search string Durchsucht den Namen oder den Kurzlink.
sort string created_at, name oder scans_total. Für absteigende Reihenfolge ein Minus davor: -scans_total.

Statuscodes

  • 200 Die Liste kam zurück; ohne Ergebnisse ist data ein leeres Array.
  • 401 Der API-Schlüssel fehlt oder ist ungültig.
  • 422 Ein ungültiger Filter- oder Sortierwert.
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}`);

Antwort 200 BEISPIEL

{
  "data": [
    {
      "id": "qr_7Kq2mX",
      "type": "url",
      "name": "Plakat · 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 }
}

Abrufen

GET /qr-codes/{id}

Gibt alle Felder eines Codes zurück: Ziel, Design, Status und Scans insgesamt.

Authentifizierung: ApiKeyAuth (Bearer)Scope: qr:read

Pfadparameter

FeldTypBeschreibung
idPflicht string Die ID des Codes, zum Beispiel qr_7Kq2mX.

Statuscodes

  • 200 Der Code wurde gefunden.
  • 401 Der API-Schlüssel fehlt oder ist ungültig.
  • 404 Der Code existiert nicht oder gehört nicht dir.
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');

Antwort 200 BEISPIEL

{
  "data": {
    "id": "qr_7Kq2mX",
    "type": "url",
    "name": "Plakat · Kadıköy",
    "status": "active",
    "dynamic": true,
    "short_url": "https://oqur.io/d/7Kq2xP",
    "target": { "url": "https://cafename.de/kampagne" },
    "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"
  }
}

Aktualisieren

PATCH /qr-codes/{id}

Aktualisiert einen Code. Das Ziel zu ändern, ändert den Code nicht: Der gedruckte QR bleibt gleich, die nächsten Scans gehen zum neuen Ziel.

Authentifizierung: ApiKeyAuth (Bearer)Scope: qr:write

Pfadparameter

FeldTypBeschreibung
idPflicht string Die ID des Codes.

Anfragebody

FeldTypBeschreibung
target object Das neue Ziel. Bei statischen Codes nicht änderbar.
status string active oder paused.
name string Der neue Name.
folder_id string Der Zielordner; null, um ihn aus dem Ordner zu nehmen.
design object Designfelder. Die gesendeten Unterfelder werden zusammengeführt.

Statuscodes

  • 200 Der Code wurde aktualisiert.
  • 401 Der API-Schlüssel fehlt oder ist ungültig.
  • 404 Der Code existiert nicht oder gehört nicht dir.
  • 422 Ein ungültiges Feld; zum Beispiel kann das Ziel eines statischen Codes nicht geändert werden.
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' } }),
});

Antwort 200 BEISPIEL

{
  "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"
  }
}

Duplizieren

POST /qr-codes/{id}/duplicate

Kopiert den Code mit Design und Ziel. Die Kopie startet mit neuem Kurzlink und null Scans; der schnellste Weg, dasselbe Design für Filialen zu wiederholen.

Authentifizierung: ApiKeyAuth (Bearer)Scope: qr:write

Pfadparameter

FeldTypBeschreibung
idPflicht string Die ID des zu kopierenden Codes.

Anfragebody

FeldTypBeschreibung
name string Der Name der Kopie. Bleibt er leer, wird „(Kopie)“ an den Originalnamen gehängt.
folder_id string Der Ordner für die Kopie. Standard: der Ordner des Originals.

Statuscodes

  • 201 Die Kopie wurde erstellt.
  • 401 Der API-Schlüssel fehlt oder ist ungültig.
  • 403 Du hast das Limit für dynamische Codes erreicht.
  • 404 Der Code existiert nicht oder gehört nicht dir.
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": "Plakat · Beşiktaş" }'
<?php
$res = $oqur->post('qr-codes/qr_7Kq2mX/duplicate', [
    'json' => ['name' => 'Plakat · Beşiktaş'],
]);
const { data: copy } = await oqur('/qr-codes/qr_7Kq2mX/duplicate', {
  method: 'POST',
  body: JSON.stringify({ name: 'Plakat · Beşiktaş' }),
});

Antwort 201 BEISPIEL

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

Bild erstellen

POST /qr-codes/{id}/image

Erzeugt ein druckfertiges Bild des Codes und gibt einen kurzlebigen Download-Link zurück. Du kannst Einstellungen nur für dieses Bild übergeben, ohne das gespeicherte Design zu ändern.

Authentifizierung: ApiKeyAuth (Bearer)Scope: qr:read

Pfadparameter

FeldTypBeschreibung
idPflicht string Die ID des Codes.

Anfragebody

FeldTypBeschreibung
formatPflicht string png, svg, pdf oder eps.
size integer Bei PNG die Kantenlänge in Pixeln. Zwischen 256 und 4096; Standard 1024.
margin integer Die Ruhezone in Modulen. Standard 4; weniger wird nicht empfohlen.
design object Vorübergehende Designeinstellungen nur für dieses Bild.

Der Download-Link ist 1 Stunde gültig. Wenn du die Datei auf deinem eigenen Server behalten willst, nutze den Endpunkt Bild abrufen.

Statuscodes

  • 200 Das Bild ist bereit.
  • 401 Der API-Schlüssel fehlt oder ist ungültig.
  • 404 Der Code existiert nicht oder gehört nicht dir.
  • 422 Ein nicht unterstütztes Format oder eine nicht unterstützte Größe.
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); // 1 Stunde gültig

Antwort 200 BEISPIEL

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

Bild abrufen

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

Gibt das Bild direkt als Datei zurück. Die Antwort ist die Datei selbst, kein JSON; gut, um sie auf deinem Server zu speichern oder in einen Druckablauf aufzunehmen.

Authentifizierung: ApiKeyAuth (Bearer)Scope: qr:read

Pfadparameter

FeldTypBeschreibung
idPflicht string Die ID des Codes.
formatPflicht string png, svg, pdf oder eps.

Query-Parameter

FeldTypBeschreibung
size integer Bei PNG die Kantenlänge in Pixeln. Standard 1024.
margin integer Die Ruhezone in Modulen. Standard 4.

Statuscodes

  • 200 Die Datei kam zurück.
  • 401 Der API-Schlüssel fehlt oder ist ungültig.
  • 404 Der Code existiert nicht oder gehört nicht dir.
  • 422 Ein nicht unterstütztes Format oder eine nicht unterstützte Größe.
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()));

Antwort 200 BEISPIEL

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)

Gesammelt löschen

DELETE /qr-codes?ids=…

Verschiebt bis zu 100 Codes in den Papierkorb. Codes im Papierkorb können innerhalb von 30 Tagen im Panel zurückgeholt werden; wer einen dynamischen Code im Papierkorb scannt, sieht die Seite „Dieser Code wird nicht verwendet“. Wenn du einen Code nur anhalten willst, setz seinen Status auf paused.

Authentifizierung: ApiKeyAuth (Bearer)Scope: qr:write

Query-Parameter

FeldTypBeschreibung
idsPflicht string Kommagetrennte Code-IDs, höchstens 100.

Statuscodes

  • 200 Die Codes wurden in den Papierkorb verschoben.
  • 401 Der API-Schlüssel fehlt oder ist ungültig.
  • 404 Ein Code in der Liste wurde nicht gefunden; kein Code wurde gelöscht.
  • 422 Die ID-Liste ist leer oder hat mehr als 100 Einträge.
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' });

Antwort 200 BEISPIEL

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

Analysen

Hol Scandaten in deine eigenen Berichte. Berichte enthalten keine personenbezogenen Daten: Es werden keine IP-Adresse, keine Geräte-ID und kein genauer Standort zurückgegeben.

Analysebericht

GET /analytics/scans

Gibt Summen, Zeitreihe und Aufschlüsselung für die gewählten Codes und den Zeitraum zurück. Datum und Uhrzeit werden in der gewünschten Zeitzone gruppiert.

Authentifizierung: ApiKeyAuth (Bearer)Scope: analytics:read

Query-Parameter

FeldTypBeschreibung
fromPflicht date Startdatum, YYYY-MM-DD.
toPflicht date Enddatum, eingeschlossen. Der Zeitraum umfasst höchstens 366 Tage.
qr_ids string Kommagetrennte Code-IDs. Bleibt es leer, alle Codes.
timezone string Eine IANA-Zeitzone, zum Beispiel Europe/Berlin. Standard: die Zeitzone des Arbeitsbereichs.
group_by string hour, day, week oder month. Standard day.
breakdown string country, city, device, os oder browser.

Statuscodes

  • 200 Der Bericht kam zurück.
  • 401 Der API-Schlüssel fehlt oder ist ungültig.
  • 422 Der Zeitraum ist ungültig oder länger als 366 Tage.
  • 429 Du hast das Ratenlimit erreicht.
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}`);

Antwort 200 BEISPIEL

{
  "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 }
      ]
    }
  }
}

Ordner

Gruppiere deine Codes nach Filiale, Kampagne oder Kunde. Alle im Team sehen jeden Ordner; die Rolle entscheidet, was sie tun können.

Ordner erstellen

POST /folders

Erstellt einen neuen Ordner, um deine Codes zu gruppieren.

Authentifizierung: ApiKeyAuth (Bearer)Scope: folders:write

Anfragebody

FeldTypBeschreibung
namePflicht string Ordnername, zwischen 1 und 80 Zeichen. Muss in deinem Konto eindeutig sein.

Statuscodes

  • 201 Der Ordner wurde erstellt.
  • 401 Der API-Schlüssel fehlt oder ist ungültig.
  • 409 Es gibt schon einen Ordner mit diesem Namen.
  • 422 Der Name ist leer oder länger als 80 Zeichen.
curl -X POST https://api.oqur.io/v1/folders \
  -H "Authorization: Bearer $OQUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Filiale Kadıköy" }'
<?php
$res = $oqur->post('folders', ['json' => ['name' => 'Filiale Kadıköy']]);
const { data: folder } = await oqur('/folders', {
  method: 'POST',
  body: JSON.stringify({ name: 'Filiale Kadıköy' }),
});

Antwort 201 BEISPIEL

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

Ordner auflisten

GET /folders

Gibt die Ordner deines Kontos zurück, mit der Anzahl Codes in jedem.

Authentifizierung: ApiKeyAuth (Bearer)Scope: qr:read

Query-Parameter

FeldTypBeschreibung
page integer Seitennummer. Standard 1.
per_page integer Einträge pro Seite. Standard 25, höchstens 100.

Statuscodes

  • 200 Die Liste kam zurück.
  • 401 Der API-Schlüssel fehlt oder ist ungültig.
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');

Antwort 200 BEISPIEL

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

Fehlercodes

Fehler kommen immer gleich zurück: ein HTTP-Statuscode und ein error-Objekt. Das Feld code ist für deine Software, das Feld message für Menschen; der Nachrichtentext kann sich ändern, verlass dich auf den Code.

Status

HTTPcodeBeschreibung
400 bad_request Der Anfragebody konnte nicht gelesen werden. Stell sicher, dass das JSON gültig ist, und prüf den Content-Type-Header.
401 unauthenticated Der API-Schlüssel fehlt oder ist ungültig. Prüf den Authorization-Header.
403 forbidden Dein Tarif oder Schlüssel darf das nicht; zum Beispiel ist das Limit für dynamische Codes erreicht.
404 not_found Der Eintrag existiert nicht oder gehört nicht zu deinem Konto.
409 conflict Ein Eintrag mit demselben Namen existiert, oder ein Idempotency-Key wurde mit anderem Body erneut verwendet.
422 validation_failed Ein Feld ist ungültig. Welches Feld abgelehnt wurde und warum, steht im Array details.
429 rate_limited Du hast das Ratenlimit erreicht. Warte Retry-After ab.
500 server_error Bei uns ist etwas schiefgelaufen. Versuch es erneut; wenn es bleibt, schreib uns mit der request_id.

Antwort 422 BEISPIEL

{
  "error": {
    "code": "validation_failed",
    "message": "2 Einträge konnten nicht geprüft werden.",
    "details": [
      { "field": "items.0.target.url", "message": "Muss eine gültige Webadresse sein." },
      { "field": "items.3.type", "message": "Bilinmeyen QR tipi: menu2." }
    ],
    "request_id": "req_3hV8qL"
  }
}

Stimmt etwas nicht?

Schreib uns mit dem Wert request_id; wir finden deine Anfrage und sehen sie uns an.

Technischer Support

Probier es zuerst im Panel aus, dann automatisiere.

Wenn die API fertig ist, öffnet sie in den Tarifen Business und Enterprise. Für Unternehmensintegrationen kannst du mit unserem Vertriebsteam sprechen.