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.
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.
Erste Anfrage senden
Das Beispiel daneben listet den ersten Code in deinem Konto. Wenn die Antwort 200 ist, ist alles bereit.
Limits im Blick behalten
Deine verbleibenden Anfragen stehen in den Headern jeder Antwort. Details im Abschnitt Ratenlimits.
Regeln
| Thema | Format | Beschreibung |
|---|---|---|
| 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
| Header | Typ | Beschreibung |
|---|---|---|
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
| Header | Typ | Beschreibung |
|---|---|---|
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
| Header | Typ | Beschreibung |
|---|---|---|
Idempotency-Key |
string |
Ein eindeutiger Wert, um die Anfrage sicher erneut zu senden. |
Anfragebody
| Feld | Typ | Beschreibung |
|---|---|---|
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
| Feld | Typ | Beschreibung |
|---|---|---|
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
| Feld | Typ | Beschreibung |
|---|---|---|
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
| Feld | Typ | Beschreibung |
|---|---|---|
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
| Feld | Typ | Beschreibung |
|---|---|---|
idPflicht |
string |
Die ID des Codes. |
Anfragebody
| Feld | Typ | Beschreibung |
|---|---|---|
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
| Feld | Typ | Beschreibung |
|---|---|---|
idPflicht |
string |
Die ID des zu kopierenden Codes. |
Anfragebody
| Feld | Typ | Beschreibung |
|---|---|---|
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
| Feld | Typ | Beschreibung |
|---|---|---|
idPflicht |
string |
Die ID des Codes. |
Anfragebody
| Feld | Typ | Beschreibung |
|---|---|---|
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
| Feld | Typ | Beschreibung |
|---|---|---|
idPflicht |
string |
Die ID des Codes. |
formatPflicht |
string |
png, svg, pdf oder eps. |
Query-Parameter
| Feld | Typ | Beschreibung |
|---|---|---|
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
| Feld | Typ | Beschreibung |
|---|---|---|
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
| Feld | Typ | Beschreibung |
|---|---|---|
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
| Feld | Typ | Beschreibung |
|---|---|---|
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
| Feld | Typ | Beschreibung |
|---|---|---|
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
| HTTP | code | Beschreibung |
|---|---|---|
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 SupportProbier 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.