Gestiona tus códigos desde tu propio sistema.
Crea cientos de códigos QR en una sola petición, actualiza sus destinos y lleva los informes de escaneo a tu propio panel. Basta con REST, JSON y una clave de API.
Borrador: los endpoints se definirán durante el desarrollo. Esta página muestra la estructura propuesta; aún no hay una API activa. Las direcciones, los nombres de campo, los límites y los formatos de respuesta pueden cambiar.
- URL base
https://api.oqur.io/v1- Formato
- JSON, UTF-8, HTTPS
- Autenticación
- Clave de API Bearer
- Planes
- Negocio y Empresa
Primeros pasos
La API de oqur te permite hacer desde tu propio software lo que haces en el panel: creación masiva de QR, actualización de destinos, descarga de archivos de impresión e informes de escaneo. Cada petición va por HTTPS con un cuerpo JSON.
Crea una clave
Crea una clave en la sección Claves de API del menú Ajustes del panel y elige sus alcances. Cuando la API esté lista, se abrirá en los planes Negocio y Empresa.
Envía tu primera petición
El ejemplo de al lado lista el primer código de tu cuenta. Si la respuesta es 200, todo está listo.
Vigila los límites
Tus peticiones restantes están en las cabeceras de cada respuesta. Los detalles están en la sección Límites de peticiones.
Reglas
| Tema | Formato | Descripción |
|---|---|---|
| Fecha y hora | ISO 8601 |
Siempre se devuelven en UTC: 2026-09-30T09:12:44Z. En los informes puedes elegir la zona horaria que quieras. |
| ID | string |
Texto con prefijo: los códigos QR empiezan por qr_, las carpetas por fld_ y las peticiones por req_. |
| Paginación | integer |
Con page y per_page. Como máximo 100 registros por página. |
| Versión | v1 |
La versión va en la dirección. Los cambios incompatibles con versiones anteriores solo llegan con una versión nueva. |
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+ u otros entornos fuera del navegador
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');
Respuesta 200 EJEMPLO
{
"data": [
{
"id": "qr_7Kq2mX",
"type": "menu",
"name": "Kafe Rıhtım · Tarjeta de mesa",
"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 }
}
Autenticación
Añade tu clave de API a cada petición en la cabecera Authorization. Las peticiones sin clave o con una clave no válida devuelven 401; las claves sin permiso suficiente devuelven 403.
- Usa la clave solo en el lado del servidor; no la incrustes en un navegador ni en una app móvil.
- Crea una clave distinta para cada integración. Si una se filtra, solo revocas esa.
- Da a cada clave solo los alcances que necesita:
qr:read,qr:write,analytics:read,folders:write.
Cabeceras
| Cabecera | Tipo | Descripción |
|---|---|---|
Authorizationobligatorio |
string |
Bearer seguido de tu clave de API. |
Content-Type |
string |
application/json en las peticiones con cuerpo. |
Accept |
string |
application/json. |
Idempotency-Key |
string |
Un valor único para reintentar con seguridad las peticiones de creación. Una petición con la misma clave en 24 horas devuelve la primera respuesta. |
Cabeceras de la peticiónEJEMPLO
Authorization: Bearer oqur_live_8f3kQ2…
Content-Type: application/json
Accept: application/json
Respuesta 401 EJEMPLO
{
"error": {
"code": "unauthenticated",
"message": "Falta la clave de API o no es válida.",
"request_id": "req_5nT2pW"
}
}
Límites de peticiones
Cada clave de API puede hacer 60 peticiones por minuto; en el plan Empresa el límite se ajusta a tus necesidades. Los endpoints masivos procesan 100 elementos en una petición, así que puedes crear o editar hasta 6.000 códigos por minuto.
Cabeceras de la respuesta
| Cabecera | Tipo | Descripción |
|---|---|---|
X-RateLimit-Limit |
integer |
Tu total de peticiones por minuto. |
X-RateLimit-Remaining |
integer |
Peticiones restantes en este minuto. |
X-RateLimit-Reset |
integer |
Cuándo se renueva tu cupo, como marca de tiempo Unix. |
Retry-After |
integer |
Solo en una respuesta 429: cuántos segundos esperar. |
Cuando recibas un 429, espera lo que indique Retry-After y vuelve a intentarlo. Ante errores repetidos, duplicar la espera en cada intento es lo más seguro.
Respuesta 429 EJEMPLO
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": "Agotaste tus peticiones de este minuto. Vuelve a intentarlo en 18 segundos.",
"request_id": "req_9kP1sV"
}
}
Códigos QR
Creación y edición de códigos y generación de archivos de impresión. Cambiar el destino de un código dinámico no cambia su enlace corto: el código impreso no cambia.
Creación masiva
POST
/qr-codes/bulk
Crea hasta 100 códigos QR en una sola petición. Cada elemento se valida por separado; si alguno no es válido, no se crea ninguno y los errores vuelven en el orden de los elementos.
Autenticación: ApiKeyAuth (Bearer)Alcance: qr:write
Cabeceras
| Cabecera | Tipo | Descripción |
|---|---|---|
Idempotency-Key |
string |
Un valor único para volver a enviar la petición con seguridad. |
Cuerpo de la petición
| Campo | Tipo | Descripción |
|---|---|---|
itemsobligatorio |
array |
Los códigos que se crean. Al menos 1 y como máximo 100 elementos. |
items[].typeobligatorio |
string |
Tipo de QR: uno de los 24 tipos, como url, pdf, menu, vcard-plus o wifi. |
items[].targetobligatorio |
object |
Un destino que depende del tipo. El campo url para el tipo url; el campo file_url para el tipo pdf. |
items[].name |
string |
El nombre que se muestra en el panel. Como máximo 120 caracteres. |
items[].folder_id |
string |
La carpeta a la que se añade el código. |
items[].design |
object |
Color, patrón, esquinas, logotipo y marco. Si se deja vacío, se usa la plantilla predeterminada de tu cuenta. |
Los tipos de la línea Q5 (wifi, text, vcard, email, sms, whatsapp) se crean estáticos y no cuentan para tu cupo de códigos dinámicos.
Códigos de estado
- 201 Se crearon los códigos.
- 401 Falta la clave de API o no es válida.
- 403 Tu plan no permite la API o tantos códigos dinámicos.
- 422 Uno o más elementos no son válidos; los detalles están en el array details.
- 429 Alcanzaste el límite de peticiones; espera lo que indique Retry-After.
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": "Póster · 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: el cliente de Primeros pasos
$res = $oqur->post('qr-codes/bulk', [
'headers' => ['Idempotency-Key' => 'campaign-september-01'],
'json' => [
'items' => [
[
'type' => 'url',
'name' => 'Póster · 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(): la función auxiliar de Primeros pasos
const { data } = await oqur('/qr-codes/bulk', {
method: 'POST',
headers: { 'Idempotency-Key': 'campaign-september-01' },
body: JSON.stringify({
items: [
{
type: 'url',
name: 'Póster · 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' },
},
],
}),
});
Respuesta 201 EJEMPLO
{
"data": [
{
"id": "qr_7Kq2mX",
"type": "url",
"name": "Póster · 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 }
}
Actualización masiva
PATCH
/qr-codes/bulk
Actualiza hasta 100 códigos en una sola petición. Solo cambian los campos que envías; el enlace corto y el código impreso no cambian.
Autenticación: ApiKeyAuth (Bearer)Alcance: qr:write
Cuerpo de la petición
| Campo | Tipo | Descripción |
|---|---|---|
itemsobligatorio |
array |
Los códigos que se actualizan. Al menos 1 y como máximo 100 elementos. |
items[].idobligatorio |
string |
El ID del código. |
items[].target |
object |
El nuevo destino. Los siguientes escaneos van a él enseguida. |
items[].status |
string |
active o paused. Quien escanea un código en pausa ve una sencilla página de «cerrado temporalmente». |
items[].name |
string |
El nuevo nombre. |
items[].folder_id |
string |
La carpeta a la que se mueve; null para sacarlo de su carpeta. |
items[].design |
object |
Campos de diseño. Los subcampos que envías se combinan. |
Códigos de estado
- 200 Se actualizaron los códigos.
- 401 Falta la clave de API o no es válida.
- 404 No se encontró un código de la lista o no es tuyo.
- 422 Un elemento no es válido; no se actualizó ningún código.
- 429 Alcanzaste el límite de peticiones.
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' },
],
}),
});
Respuesta 200 EJEMPLO
{
"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 }
}
Listar
GET
/qr-codes
Devuelve los códigos de tu cuenta, paginados. El orden predeterminado es de más reciente a más antiguo.
Autenticación: ApiKeyAuth (Bearer)Alcance: qr:read
Parámetros de consulta
| Campo | Tipo | Descripción |
|---|---|---|
page |
integer |
Número de página. Predeterminado: 1. |
per_page |
integer |
Registros por página. Predeterminado: 25; como máximo 100. |
folder_id |
string |
Solo los códigos de esta carpeta. |
type |
string |
Filtra por tipo, por ejemplo menu. |
status |
string |
draft, scheduled, active o paused. |
search |
string |
Busca en el nombre o en el enlace corto. |
sort |
string |
created_at, name o scans_total. Para orden descendente, pon un signo menos delante: -scans_total. |
Códigos de estado
- 200 Se devolvió la lista; sin resultados, data es un array vacío.
- 401 Falta la clave de API o no es válida.
- 422 Un valor de filtro u orden no válido.
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}`);
Respuesta 200 EJEMPLO
{
"data": [
{
"id": "qr_7Kq2mX",
"type": "url",
"name": "Póster · 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 }
}
Obtener
GET
/qr-codes/{id}
Devuelve todos los campos de un código: destino, diseño, estado y escaneos totales.
Autenticación: ApiKeyAuth (Bearer)Alcance: qr:read
Parámetros de ruta
| Campo | Tipo | Descripción |
|---|---|---|
idobligatorio |
string |
El ID del código, por ejemplo qr_7Kq2mX. |
Códigos de estado
- 200 Se encontró el código.
- 401 Falta la clave de API o no es válida.
- 404 El código no existe o no es tuyo.
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');
Respuesta 200 EJEMPLO
{
"data": {
"id": "qr_7Kq2mX",
"type": "url",
"name": "Póster · 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"
}
}
Actualizar
PATCH
/qr-codes/{id}
Actualiza un código. Cambiar el destino no cambia el código: el QR impreso no cambia y los siguientes escaneos van al nuevo destino.
Autenticación: ApiKeyAuth (Bearer)Alcance: qr:write
Parámetros de ruta
| Campo | Tipo | Descripción |
|---|---|---|
idobligatorio |
string |
El ID del código. |
Cuerpo de la petición
| Campo | Tipo | Descripción |
|---|---|---|
target |
object |
El nuevo destino. No se puede cambiar en los códigos estáticos. |
status |
string |
active o paused. |
name |
string |
El nuevo nombre. |
folder_id |
string |
La carpeta a la que se mueve; null para sacarlo de su carpeta. |
design |
object |
Campos de diseño. Los subcampos que envías se combinan. |
Códigos de estado
- 200 Se actualizó el código.
- 401 Falta la clave de API o no es válida.
- 404 El código no existe o no es tuyo.
- 422 Un campo no válido; por ejemplo, el destino de un código estático no se puede cambiar.
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' } }),
});
Respuesta 200 EJEMPLO
{
"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"
}
}
Duplicar
POST
/qr-codes/{id}/duplicate
Copia el código con su diseño y su destino. La copia empieza con un enlace corto nuevo y cero escaneos; la forma más rápida de repetir el mismo diseño en varias sucursales.
Autenticación: ApiKeyAuth (Bearer)Alcance: qr:write
Parámetros de ruta
| Campo | Tipo | Descripción |
|---|---|---|
idobligatorio |
string |
El ID del código que se copia. |
Cuerpo de la petición
| Campo | Tipo | Descripción |
|---|---|---|
name |
string |
El nombre de la copia. Si se deja vacío, se añade «(copia)» al nombre original. |
folder_id |
string |
La carpeta a la que se añade la copia. Predeterminada: la carpeta del código original. |
Códigos de estado
- 201 Se creó la copia.
- 401 Falta la clave de API o no es válida.
- 403 Alcanzaste el límite de códigos dinámicos.
- 404 El código no existe o no es tuyo.
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": "Póster · Beşiktaş" }'
<?php
$res = $oqur->post('qr-codes/qr_7Kq2mX/duplicate', [
'json' => ['name' => 'Póster · Beşiktaş'],
]);
const { data: copy } = await oqur('/qr-codes/qr_7Kq2mX/duplicate', {
method: 'POST',
body: JSON.stringify({ name: 'Póster · Beşiktaş' }),
});
Respuesta 201 EJEMPLO
{
"data": {
"id": "qr_9Ms4pZ",
"type": "url",
"name": "Póster · Beşiktaş",
"status": "active",
"short_url": "https://oqur.io/d/9Ms4pR",
"scans_total": 0,
"created_at": "2026-09-30T10:20:31Z"
}
}
Crear imagen
POST
/qr-codes/{id}/image
Genera una imagen del código lista para imprimir y devuelve un enlace de descarga de corta duración. Puedes pasar ajustes solo para esta imagen sin cambiar el diseño guardado.
Autenticación: ApiKeyAuth (Bearer)Alcance: qr:read
Parámetros de ruta
| Campo | Tipo | Descripción |
|---|---|---|
idobligatorio |
string |
El ID del código. |
Cuerpo de la petición
| Campo | Tipo | Descripción |
|---|---|---|
formatobligatorio |
string |
png, svg, pdf o eps. |
size |
integer |
Para PNG, la longitud del lado en píxeles. Entre 256 y 4096; predeterminado: 1024. |
margin |
integer |
La zona de silencio, en módulos. Predeterminado: 4; no se recomienda menos. |
design |
object |
Ajustes de diseño temporales solo para esta imagen. |
El enlace de descarga es válido durante 1 hora. Si quieres guardar el archivo en tu propio servidor, usa el endpoint Obtener imagen.
Códigos de estado
- 200 La imagen está lista.
- 401 Falta la clave de API o no es válida.
- 404 El código no existe o no es tuyo.
- 422 Un formato o tamaño no admitido.
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); // válido durante 1 hora
Respuesta 200 EJEMPLO
{
"data": {
"format": "svg",
"url": "https://cdn.oqur.io/r/qr_7Kq2mX.svg?sig=Vb8f2…",
"expires_at": "2026-09-30T11:12:44Z"
}
}
Obtener imagen
GET
/qr-codes/{id}/image.{format}
Devuelve la imagen directamente como archivo. La respuesta es el propio archivo, no JSON; útil para guardarlo en tu servidor o añadirlo a un flujo de impresión.
Autenticación: ApiKeyAuth (Bearer)Alcance: qr:read
Parámetros de ruta
| Campo | Tipo | Descripción |
|---|---|---|
idobligatorio |
string |
El ID del código. |
formatobligatorio |
string |
png, svg, pdf o eps. |
Parámetros de consulta
| Campo | Tipo | Descripción |
|---|---|---|
size |
integer |
Para PNG, la longitud del lado en píxeles. Predeterminado: 1024. |
margin |
integer |
La zona de silencio, en módulos. Predeterminado: 4. |
Códigos de estado
- 200 Se devolvió el archivo.
- 401 Falta la clave de API o no es válida.
- 404 El código no existe o no es tuyo.
- 422 Un formato o tamaño no admitido.
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()));
Respuesta 200 EJEMPLO
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)
Eliminación masiva
DELETE
/qr-codes?ids=…
Mueve hasta 100 códigos a la papelera. Los códigos de la papelera se pueden recuperar desde el panel en un plazo de 30 días; quien escanea un código dinámico en la papelera ve una página de «este código no está en uso». Si solo quieres detener un código, pon su estado en paused.
Autenticación: ApiKeyAuth (Bearer)Alcance: qr:write
Parámetros de consulta
| Campo | Tipo | Descripción |
|---|---|---|
idsobligatorio |
string |
ID de códigos separados por comas, como máximo 100. |
Códigos de estado
- 200 Los códigos se movieron a la papelera.
- 401 Falta la clave de API o no es válida.
- 404 No se encontró un código de la lista; no se eliminó ningún código.
- 422 La lista de ID está vacía o supera los 100.
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' });
Respuesta 200 EJEMPLO
{
"meta": { "deleted": 3 }
}
Analítica
Lleva los datos de escaneo a tus propios informes. Los informes no contienen datos personales: no se devuelve ninguna dirección IP, ID de dispositivo ni ubicación exacta.
Informe de analítica
GET
/analytics/scans
Devuelve los totales, la serie temporal y el desglose de los códigos y el rango de fechas que elijas. Las fechas y horas se agrupan en la zona horaria que quieras.
Autenticación: ApiKeyAuth (Bearer)Alcance: analytics:read
Parámetros de consulta
| Campo | Tipo | Descripción |
|---|---|---|
fromobligatorio |
date |
Fecha de inicio, YYYY-MM-DD. |
toobligatorio |
date |
Fecha de fin, incluida. El rango es de 366 días como máximo. |
qr_ids |
string |
ID de códigos separados por comas. Si se deja vacío, todos los códigos. |
timezone |
string |
Una zona horaria IANA, por ejemplo Europe/Istanbul. Predeterminada: la zona horaria del espacio de trabajo. |
group_by |
string |
hour, day, week o month. Predeterminado: day. |
breakdown |
string |
country, city, device, os o browser. |
Códigos de estado
- 200 Se devolvió el informe.
- 401 Falta la clave de API o no es válida.
- 422 El rango de fechas no es válido o supera los 366 días.
- 429 Alcanzaste el límite de peticiones.
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}`);
Respuesta 200 EJEMPLO
{
"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 }
]
}
}
}
Carpetas
Agrupa tus códigos por sucursal, campaña o cliente. Todos en el equipo ven todas las carpetas; su rol decide lo que pueden hacer.
Crear carpeta
POST
/folders
Crea una carpeta nueva para agrupar tus códigos.
Autenticación: ApiKeyAuth (Bearer)Alcance: folders:write
Cuerpo de la petición
| Campo | Tipo | Descripción |
|---|---|---|
nameobligatorio |
string |
Nombre de la carpeta, entre 1 y 80 caracteres. Debe ser único en tu cuenta. |
Códigos de estado
- 201 Se creó la carpeta.
- 401 Falta la clave de API o no es válida.
- 409 Ya existe una carpeta con este nombre.
- 422 El nombre está vacío o supera los 80 caracteres.
curl -X POST https://api.oqur.io/v1/folders \
-H "Authorization: Bearer $OQUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Sucursal de Kadıköy" }'
<?php
$res = $oqur->post('folders', ['json' => ['name' => 'Sucursal de Kadıköy']]);
const { data: folder } = await oqur('/folders', {
method: 'POST',
body: JSON.stringify({ name: 'Sucursal de Kadıköy' }),
});
Respuesta 201 EJEMPLO
{
"data": {
"id": "fld_91xQ",
"name": "Sucursal de Kadıköy",
"qr_count": 0,
"created_at": "2026-09-30T10:31:08Z"
}
}
Listar carpetas
GET
/folders
Devuelve las carpetas de tu cuenta con cuántos códigos contiene cada una.
Autenticación: ApiKeyAuth (Bearer)Alcance: qr:read
Parámetros de consulta
| Campo | Tipo | Descripción |
|---|---|---|
page |
integer |
Número de página. Predeterminado: 1. |
per_page |
integer |
Registros por página. Predeterminado: 25; como máximo 100. |
Códigos de estado
- 200 Se devolvió la lista.
- 401 Falta la clave de API o no es válida.
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');
Respuesta 200 EJEMPLO
{
"data": [
{ "id": "fld_91xQ", "name": "Sucursal de Kadıköy", "qr_count": 14 },
{ "id": "fld_22bR", "name": "Envase · Septiembre", "qr_count": 120 }
],
"meta": { "page": 1, "per_page": 25, "total": 2 }
}
Códigos de error
Los errores siempre vuelven de la misma forma: un código de estado HTTP y un objeto error. El campo code es para tu software y el campo message para las personas; el texto del mensaje puede cambiar, básate en el código.
Estados
| HTTP | code | Descripción |
|---|---|---|
400 |
bad_request |
No se pudo leer el cuerpo de la petición. Asegúrate de que el JSON es válido y revisa la cabecera Content-Type. |
401 |
unauthenticated |
Falta la clave de API o no es válida. Revisa la cabecera Authorization. |
403 |
forbidden |
Tu plan o tu clave no permiten hacer esto; por ejemplo, alcanzaste el límite de códigos dinámicos. |
404 |
not_found |
El registro no existe o no está en tu cuenta. |
409 |
conflict |
Existe un registro con el mismo nombre, o se reutilizó una Idempotency-Key con otro cuerpo. |
422 |
validation_failed |
Un campo no es válido. Qué campo se rechazó y por qué está en el array details. |
429 |
rate_limited |
Alcanzaste el límite de peticiones. Espera lo que indique Retry-After. |
500 |
server_error |
Algo falló por nuestra parte. Vuelve a intentarlo; si persiste, escríbenos con el request_id. |
Respuesta 422 EJEMPLO
{
"error": {
"code": "validation_failed",
"message": "2 elementos no superaron la validación.",
"details": [
{ "field": "items.0.target.url", "message": "Debe ser una dirección web válida." },
{ "field": "items.3.type", "message": "Bilinmeyen QR tipi: menu2." }
],
"request_id": "req_3hV8qL"
}
}
¿Algo va mal?
Escríbenos con el valor de request_id; encontraremos tu petición y la revisaremos.
Soporte técnicoPruébalo primero en el panel y luego automatiza.
Cuando la API esté lista, se abrirá en los planes Negocio y Empresa. Para integraciones empresariales puedes hablar con nuestro equipo de ventas.