Saltar al contenido
oqur

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.

  1. 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.

  2. 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.

  3. 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

TemaFormatoDescripció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

CabeceraTipoDescripció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

CabeceraTipoDescripció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

CabeceraTipoDescripción
Idempotency-Key string Un valor único para volver a enviar la petición con seguridad.

Cuerpo de la petición

CampoTipoDescripció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

CampoTipoDescripció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

CampoTipoDescripció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

CampoTipoDescripció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

CampoTipoDescripción
idobligatorio string El ID del código.

Cuerpo de la petición

CampoTipoDescripció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

CampoTipoDescripción
idobligatorio string El ID del código que se copia.

Cuerpo de la petición

CampoTipoDescripció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

CampoTipoDescripción
idobligatorio string El ID del código.

Cuerpo de la petición

CampoTipoDescripció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

CampoTipoDescripción
idobligatorio string El ID del código.
formatobligatorio string png, svg, pdf o eps.

Parámetros de consulta

CampoTipoDescripció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

CampoTipoDescripció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

CampoTipoDescripció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

CampoTipoDescripció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

CampoTipoDescripció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

HTTPcodeDescripció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écnico

Prué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.