Creación masiva de QR

curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "processing",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 18,
  "renderedCount": 12,
  "percent": 26,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:20.000Z",
  "completedAt": null,
  "failedAt": null
}

null

curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "processing",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 18,
  "renderedCount": 12,
  "percent": 26,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:20.000Z",
  "completedAt": null,
  "failedAt": null
}

null

La API de GetQR está en beta y solo está disponible para algunos espacios de trabajo. Los detalles pueden cambiar antes del lanzamiento general.

Una creación masiva convierte una lista de nombres y URL en códigos QR de tipo website con un mismo diseño. Se ejecuta en segundo plano: iníciala, consulta su progreso y descarga después el archivo ZIP.

Método	Ruta	Descripción
`GET`	`/api/v1/bulk-qr-creations`	Obtener la creación masiva actual
`POST`	`/api/v1/bulk-qr-creations`	Crear desde JSON
`POST`	`/api/v1/bulk-qr-creations/csv`	Crear desde un archivo CSV
`GET`	`/api/v1/bulk-qr-creations/{id}`	Obtener una creación masiva
`DELETE`	`/api/v1/bulk-qr-creations/{id}`	Cancelar una creación masiva
`GET`	`/api/v1/bulk-qr-creations/{id}/download`	Descargar el archivo ZIP

Cómo funciona

Inicia la creación masiva

Envía tus filas con Crear desde JSON o Crear desde un archivo CSV. La API responde 202 con la creación masiva y su id.

Consulta su progreso

Llama a Obtener una creación masiva cada pocos segundos hasta que status sea completed o failed.

Descarga el archivo ZIP

Cuando status sea completed, llama a Descargar el archivo ZIP para obtener un ZIP con las imágenes de los códigos QR.

Límite. Hasta 100 filas por creación masiva.
Una cada vez. Solo se ejecuta una creación masiva por espacio de trabajo. Si inicias otra mientras una está en curso, se devuelve la que está en curso.
Idempotencia. Cada solicitud necesita un idempotencyKey. Si repites una solicitud con la misma clave y el mismo cuerpo, se devuelve la creación masiva ya iniciada. La misma clave con otro cuerpo devuelve 422.
Filas. Cada fila necesita un name y una url. Consulta Filas.
Plan. La creación masiva no está disponible en el plan Single QR: la solicitud devuelve 403 exceeded_limit.

Filas

Nombre. Pasa a ser el título del código QR. Se recortan los espacios y se corta a 40 caracteres. Los nombres repetidos (sin distinguir mayúsculas) reciben un número: Menu, Menu 2, Menu 3.
URL. Pasa a ser el destino. Debe ser una dirección http o https con un dominio real, como example.com/menu, y no contener espacios. A una URL sin esquema se le añade https://.
Filas vacías. Las filas sin nombre ni URL se omiten. Una fila con solo uno de los dos se rechaza.

Todos los códigos QR son de tipo website con un enlace corto. Consulta Tipos de QR.

Cabeceras

string

requerido

Bearer seguido de tu clave de API. Consulta Autenticación.

string

application/json para Crear desde JSON, multipart/form-data para Crear desde un archivo CSV.

El objeto de creación masiva

string

ID de la creación masiva, por ejemplo cm2k7x9qb0003ax8eb4f6gh2t.

string

queued, processing, packaging o completed. Una creación masiva fallida o cancelada pasa por rollingBack hasta failed.

string

Nombre del archivo de origen.

integer

Número de filas.

integer

Códigos QR creados hasta ahora.

integer

Imágenes de códigos QR generadas hasta ahora.

integer

Progreso total, de 0 a 100. La creación llega hasta 40, la generación de imágenes hasta 90, el empaquetado es 95 y completed es 100.

boolean

true cuando una creación masiva en curso lleva 2 minutos sin avanzar. Sigue consultando: Obtener una creación masiva reinicia una creación masiva detenida.

object | null

Cuando status es failed: code y message. Una creación masiva cancelada tiene el código cancelled_by_user. Una creación masiva fallida se revierte, así que no se conserva ninguno de sus códigos QR.

string | null

Ruta de Descargar el archivo ZIP, cuando status es completed.

string

Fecha de inicio, ISO 8601.

string

Fecha de la última actualización, ISO 8601.

string | null

Fecha de finalización, ISO 8601.

string | null

Fecha del fallo, ISO 8601.

Obtener la creación masiva actual

GET /api/v1/bulk-qr-creations Devuelve la creación masiva que sigue en curso en tu espacio de trabajo. Si no hay ninguna en curso, devuelve la última terminada (completed o failed) hasta que se descarte: descargar su archivo ZIP o descartarla en el panel la descarta. Si no, devuelve null. Úsalo para retomar el seguimiento tras un reinicio.

curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "processing",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 18,
  "renderedCount": 12,
  "percent": 26,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:20.000Z",
  "completedAt": null,
  "failedAt": null
}

null

Crear desde JSON

POST /api/v1/bulk-qr-creations Inicia una creación masiva a partir de una lista de filas. Responde 202 Accepted. La creación masiva se ejecuta en segundo plano.

object[]

requerido

Códigos QR que se crean, hasta 100. Cada fila es { "name": "...", "url": "..." } y no admite otros campos. Consulta Filas.

object

requerido

Diseño que se aplica a todos los códigos QR: styles, frameOptions y logoOptions, todos opcionales. Envía {} para el diseño por defecto. Los demás campos se rechazan. Consulta Personalización.

string

requerido

Nombre que se muestra en el panel y se usa para el archivo ZIP, de 1 a 255 caracteres.

string

requerido

Tu propia clave para esta creación masiva, de 8 a 100 caracteres.

curl -X POST "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "name": "Menu", "url": "https://example.com/menu" },
      { "name": "Wine list", "url": "example.com/wine" }
    ],
    "design": { "styles": { "dotsOptions": { "type": "rounded" } } },
    "sourceFilename": "campaign-links.csv",
    "idempotencyKey": "campaign-2026-08-14"
  }'

{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "queued",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 2,
  "createdCount": 0,
  "renderedCount": 0,
  "percent": 0,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:00.000Z",
  "completedAt": null,
  "failedAt": null
}

Crear desde un archivo CSV

POST /api/v1/bulk-qr-creations/csv Igual que Crear desde JSON, pero recibe las filas en un archivo CSV enviado como multipart/form-data. Responde 202 Accepted. El archivo debe ser un .csv de como máximo 1.000.000 bytes. Su fila de encabezado debe ser exactamente name,url, seguida de hasta 100 filas de datos. Consulta Formato CSV.

file

requerido

El archivo CSV.

string

requerido

El objeto de diseño, serializado como JSON, por ejemplo {"styles":{"dotsOptions":{"type":"rounded"}}}. Envía {} para el diseño por defecto.

string

requerido

Tu propia clave para esta creación masiva, de 8 a 100 caracteres.

string

Nombre que se muestra en el panel y se usa para el archivo ZIP, hasta 255 caracteres. Por defecto, el nombre del archivo subido.

curl -X POST "https://getqr.com/api/v1/bulk-qr-creations/csv" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -F "[email protected]" \
  -F 'design={"styles":{"dotsOptions":{"type":"rounded"}}}' \
  -F "idempotencyKey=campaign-2026-08-14"

name,url
Menu,https://example.com/menu
Wine list,example.com/wine

{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "queued",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 2,
  "createdCount": 0,
  "renderedCount": 0,
  "percent": 0,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:00.000Z",
  "completedAt": null,
  "failedAt": null
}

Obtener una creación masiva

GET /api/v1/bulk-qr-creations/{id} Devuelve el estado y el progreso de una creación masiva. Consúltalo mientras status sea queued, processing o packaging. downloadUrl aparece cuando el archivo ZIP está listo.

string

requerido

ID de la creación masiva. Tómalo de la respuesta de creación o de la creación masiva actual.

curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "completed",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 50,
  "renderedCount": 50,
  "percent": 100,
  "stalled": false,
  "error": null,
  "downloadUrl": "/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t/download",
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:02:10.000Z",
  "completedAt": "2026-08-14T08:02:10.000Z",
  "failedAt": null
}

Cancelar una creación masiva

DELETE /api/v1/bulk-qr-creations/{id} Detiene una creación masiva en curso y elimina los códigos QR que ya ha creado. La reversión se ejecuta durante la solicitud, así que normalmente la respuesta tiene status failed y error.code cancelled_by_user. Cancelar una creación masiva que ya ha fallado la devuelve sin cambios.

Una creación masiva completada no se puede cancelar: la solicitud devuelve 400. En su lugar, elimina sus códigos QR uno a uno con Códigos QR.

string

requerido

ID de la creación masiva.

curl -X DELETE "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "failed",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 18,
  "renderedCount": 12,
  "percent": 26,
  "stalled": false,
  "error": {
    "code": "cancelled_by_user",
    "message": "Bulk QR creation was cancelled."
  },
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:40.000Z",
  "completedAt": null,
  "failedAt": "2026-08-14T08:00:40.000Z"
}

Descargar el archivo ZIP

GET /api/v1/bulk-qr-creations/{id}/download Devuelve un archivo ZIP con un JPEG de 1024 px por código QR, con el nombre de su fila: 001-Menu.jpg, 002-Wine list.jpg, etc. El archivo ZIP recibe el nombre de sourceFilename. Disponible cuando status es completed. La descarga descarta la creación masiva, así que Obtener la creación masiva actual deja de devolverla.

string

requerido

ID de la creación masiva.

curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t/download" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-codes.zip

HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="campaign-links-qr-codes.zip"

<binary archive data>

Problemas habituales

422 con "contains an invalid HTTP(S) URL"

El mensaje indica la fila. Cada URL debe ser una dirección http o https con un dominio real, como example.com/menu. Corrige la fila y vuelve a enviar la solicitud.

422 "CSV headers must be exactly: name,url."

La primera fila del CSV debe ser name,url, en ese orden y en minúsculas, sin más columnas.

422 "This idempotencyKey was already used with a different request body."

Las claves no se pueden reutilizar para otro lote. Envía un idempotencyKey nuevo.

409 "The bulk QR archive is not ready for download."

La creación masiva todavía no ha terminado. Sigue consultando hasta que status sea completed.

400 "Cannot cancel a finished bulk QR creation."

La creación masiva ya ha terminado, así que no se puede revertir.

403 exceeded_limit

Tu espacio de trabajo tiene el plan Single QR, que no incluye la creación masiva. Mejora el plan.

He recibido una creación masiva anterior en lugar de una nueva

Otra creación masiva sigue en curso en tu espacio de trabajo, o has reutilizado un idempotencyKey. Espera a que termine o usa una clave nueva.

API

Creación masiva de QR

Cómo funciona

Filas

Cabeceras

El objeto de creación masiva

Obtener la creación masiva actual

Crear desde JSON

Crear desde un archivo CSV

Obtener una creación masiva

Cancelar una creación masiva

Descargar el archivo ZIP

Problemas habituales

Siguientes pasos

Personalización

Códigos QR

Creación masiva en la app

Formato CSV

​Cómo funciona

​Filas

​Cabeceras

​El objeto de creación masiva

​Obtener la creación masiva actual

​Crear desde JSON

​Crear desde un archivo CSV

​Obtener una creación masiva

​Cancelar una creación masiva

​Descargar el archivo ZIP

​Problemas habituales

​Siguientes pasos

Personalización

Códigos QR

Creación masiva en la app

Formato CSV

Cómo funciona

Filas

Cabeceras

El objeto de creación masiva

Obtener la creación masiva actual

Crear desde JSON

Crear desde un archivo CSV

Obtener una creación masiva

Cancelar una creación masiva

Descargar el archivo ZIP

Problemas habituales

Siguientes pasos