Códigos QR - GetQR Docs

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

En GetQR, un código QR es la imagen más un enlace corto a través del cual se resuelve. Al crear un código QR también se crea su enlace corto, así que puedes cambiar el destino más adelante sin volver a imprimir el código.

Método	Ruta	Descripción
`GET`	`/api/v1/qrs`	Listar códigos QR
`POST`	`/api/v1/qrs`	Crear un código QR
`GET`	`/api/v1/qrs/{qrId}`	Obtener un código QR
`PATCH`	`/api/v1/qrs/{qrId}`	Actualizar un código QR
`PUT`	`/api/v1/qrs/{qrId}`	Establecer el estado de pausa
`POST`	`/api/v1/qrs/{qrId}/pause`	Pausar un código QR
`POST`	`/api/v1/qrs/{qrId}/activate`	Reactivar un código QR
`POST`	`/api/v1/qrs/{qrId}/duplicate`	Duplicar un código QR
`DELETE`	`/api/v1/qrs/{qrId}`	Eliminar un código QR
`GET`	`/api/v1/qrs/{qrId}/download`	Descargar la imagen de un código QR

Datos del código QR por tipo

El formato de data de cada uno de los 16 tipos.

Personalización

Estilos de puntos, colores, marcos y logotipos.

Reglas de acceso

Programación, límite de escaneos y contraseña.

Para consultar las estadísticas de escaneos de un código QR, consulta Analíticas.

El objeto de código QR

Todos los endpoints de códigos QR responden con este objeto, excepto Eliminar y Descargar. El listado devuelve un array de ellos.

string

ID único del código QR, por ejemplo qr_1EPcVfeHZAY2iNoVLsgW2Aqf.

string

Tipo de código QR, por ejemplo website. Consulta Datos del código QR por tipo para ver los 16 valores.

string | null

Nombre del código QR, que se muestra en el panel.

string | null

Nota libre sobre el código QR.

string

La carga útil guardada. En wifi, vcard, social, multilink, event y sms es la carga útil que enviaste. En los demás tipos es el enlace corto, así que lee el destino en url.

boolean

true cuando el código QR está pausado.

boolean

true en un código QR estático creado en el panel, que no tiene enlace corto. La API siempre crea códigos QR dinámicos.

string | null

Enlace corto completo, por ejemplo https://getqr.sh/x7Kd2p1.

string | null

Dominio del enlace corto.

string | null

Slug del enlace corto.

boolean

true cuando el slug se eligió en lugar de generarse.

string | null

Destino al que redirige el enlace corto.

string | null

Destino para los visitantes de iOS, en los códigos QR app.

string | null

Destino para los visitantes de Android, en los códigos QR app.

integer

Número total de escaneos.

object

Reglas de acceso. La contraseña nunca se devuelve. Consulta Reglas de acceso.

Mostrar properties

boolean

Si los visitantes deben introducir una contraseña.

string | null

Inicio programado, ISO 8601.

string | null

Final programado, ISO 8601.

integer | null

Número máximo de escaneos.

string

Solo lectura. custom es un diseño que la API puede editar por completo. branded y ai son un Branded design o un AI design creado en el panel. La API no puede editar su imagen, pero la conserva cuando cambias otros campos.

object

El diseño guardado: styles, frameOptions y logoOptions, cada uno un objeto o null. Tienen la misma forma que los campos de la solicitud, así que puedes volver a enviarlos. Consulta Personalización.

object | null

El archivo de un código QR pdf, image o video: id, name y size en bytes.

string | null

Solo lectura. Nombre visible de un código QR app creado en el panel.

object | null

Solo lectura. Un código QR pdf con varios archivos, creado en el panel: title, layout y files.

object | null

Solo lectura. Un código QR image con varias imágenes, creado en el panel: title, layout y files.

string

Fecha de creación, ISO 8601.

string

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

Los secretos y los ID internos (password, userId, workspaceId, projectId) nunca se devuelven.

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "qrType": "website",
  "title": "Landing page",
  "description": null,
  "data": "https://getqr.sh/x7Kd2p1",
  "archived": false,
  "isStatic": false,
  "shortLink": "https://getqr.sh/x7Kd2p1",
  "domain": "getqr.sh",
  "key": "x7Kd2p1",
  "keyIsCustom": false,
  "url": "https://example.com",
  "ios": null,
  "android": null,
  "scans": 128,
  "access": {
    "passwordProtected": false,
    "activeAt": null,
    "pauseAt": null,
    "scanLimit": null
  },
  "designKind": "custom",
  "design": {
    "styles": { "dotsOptions": { "type": "rounded", "color": "#1E40AF" }, … },
    "frameOptions": { "id": "card", "text": "Scan me!", … },
    "logoOptions": { "type": "suggested", "id": "logo-website-3", "scalePercent": 25 }
  },
  "file": null,
  "appName": null,
  "pdfBundle": null,
  "imageGallery": null,
  "createdAt": "2026-08-01T10:00:00.000Z",
  "updatedAt": "2026-08-01T10:00:00.000Z"
}

Listar códigos QR

GET /api/v1/qrs Devuelve los códigos QR de tu espacio de trabajo, una página cada vez.

integer

predeterminado:"1"

Página que se devuelve, 1 o más.

integer

predeterminado:"100"

Códigos QR por página, de 1 a 100. Un valor mayor se rechaza.

string

Busca en el título del código QR. Las consultas de más de 2 caracteres también buscan en el data guardado. En los tipos de enlace, el data guardado es el enlace corto, así que no se puede buscar por URL de destino.

string

predeterminado:"createdAt"

Campo por el que se ordena: createdAt, updatedAt, clicks (escaneos totales), lastClicked (último escaneo) o type. type siempre ordena de forma descendente e ignora sortOrder.

string

predeterminado:"desc"

Sentido de la ordenación: asc o desc.

boolean

predeterminado:"false"

Incluye los códigos QR pausados.

boolean

predeterminado:"false"

Devuelve solo los códigos QR pausados. Tiene prioridad sobre showArchived.

Los parámetros booleanos aceptan las cadenas true o false. Pide la página siguiente mientras pagination.hasMore sea true. Consulta Paginación.

curl "https://getqr.com/api/v1/qrs?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "data": [
    {
      "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
      "qrType": "website",
      "title": "Landing page",
      "shortLink": "https://getqr.sh/x7Kd2p1",
      "url": "https://example.com",
      "scans": 128,
      "…": "…"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}

Crear un código QR

POST /api/v1/qrs Crea a la vez un código QR y su enlace corto. Responde 201 Created con el nuevo código QR.

string

Tu propio token de reintento. Si repites la solicitud con la misma clave en un plazo de 24 horas, obtienes la respuesta original en lugar de un segundo código QR. Consulta Reintentos y duplicados.

string

requerido

Qué codifica el código QR. También determina el formato que debe tener data. Uno de website, pdf, image, video, whatsapp, social, wifi, app, feedback, vcard, sms, payment, location, multilink, email, event.

string

requerido

La carga útil del tipo, validada según qrType. Una cadena vacía omite la validación. El formato de cada tipo está en Datos del código QR por tipo.

object

El enlace corto a través del cual se resuelve el código QR. Opcional: si lo omites, link.url toma el valor de data.

Mostrar properties

string

Destino al que redirige el enlace corto. Si se omite o está vacío, toma el valor de data. Si envías ambos y son distintos, gana link.url. Los códigos QR vcard, social, multilink y event siempre apuntan a su página alojada, y los códigos QR pdf, image y video con un fileId, al archivo. Esquemas aceptados: http:, https:, wifi:, mailto:, sms:, begin:.

string

Dominio del enlace corto. Debe ser un dominio activo de tu espacio de trabajo: otro dominio devuelve 403, y un dominio que aún no está activo devuelve 422. Por defecto, el dominio predeterminado del espacio de trabajo.

string

Slug del enlace corto, de 3 a 15 caracteres, guardado en minúsculas. Un slug no permitido devuelve 422, y uno ya en uso devuelve 409. Si se omite, se genera un slug aleatorio de 7 caracteres.

string | null

URL de destino para los visitantes de iOS, en los códigos QR app.

string | null

URL de destino para los visitantes de Android, en los códigos QR app.

string | null

Título de la vista previa del enlace (og:title), guardado en el enlace corto. No es el title del propio código QR. Por ahora no se muestra en ningún sitio.

string | null

Descripción de la vista previa del enlace (og:description), guardada en el enlace corto. Por ahora no se muestra en ningún sitio.

—

No disponibles en esta API: enviar cualquiera de ellos devuelve 422. Usa access.pauseAt para detener el código QR en un momento concreto.

string

Nombre del código QR, que se muestra en el panel. Se recortan los espacios; de 1 a 40 caracteres. Si lo omites, el código QR queda sin título.

string

Nota libre sobre el código QR. Hasta 280 caracteres.

string

El archivo de un código QR pdf, image o video, subido con el target correspondiente. En vcard, social y multilink, una imagen de perfil opcional subida con el target logo. event también lo acepta, pero su página lee la portada de data.fileId. Los demás tipos devuelven 422. Sube antes el archivo con Archivos. Consulta Archivos en códigos QR.

string

Plantilla cuyo diseño se aplica al nuevo código QR. Los campos de diseño que envíes se combinan sobre ella. Una plantilla de Branded design o AI design devuelve 422 (art_template_unsupported). Una plantilla desconocida, o de otro espacio de trabajo, devuelve 404.

object

Formas y colores de los puntos y las esquinas. Consulta Personalización.

object

Marco dibujado alrededor del código QR y su texto de llamada a la acción. Consulta Personalización.

object

Logotipo en el centro: un logotipo sugerido o tu propio archivo subido con el target logo. Se rechaza un archivo desconocido, una subida sin terminar o un archivo de otro target. Consulta Personalización.

object

Programación, límite de escaneos y protección con contraseña. Consulta Reglas de acceso.

Mostrar properties

string | null

Inicio programado, ISO 8601.

string | null

Final programado, ISO 8601.

integer | null

Número máximo de escaneos, un número entero positivo.

string | null

Contraseña que deben introducir los visitantes. Enviarla activa la protección.

boolean

Desactiva o vuelve a activar la protección, conservando la contraseña guardada.

boolean

Si el código QR está pausado. true lo crea ya pausado: los escaneos muestran la página de pausa en lugar del destino.

Los campos desconocidos se descartan sin error. Consulta No disponible en la API.

curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: landing-page-2026-08" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page",
    "access": { "scanLimit": 500 }
  }'

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "qrType": "website",
  "title": "Landing page",
  "data": "https://getqr.sh/x7Kd2p1",
  "shortLink": "https://getqr.sh/x7Kd2p1",
  "url": "https://example.com",
  "scans": 0,
  "access": { "passwordProtected": false, "activeAt": null, "pauseAt": null, "scanLimit": 500 },
  "…": "…"
}

Reintentos y duplicados

Con clave. Con una cabecera Idempotency-Key, la respuesta se repite durante 24 horas.
Sin clave. Un cuerpo idéntico enviado en menos de 30 segundos se trata como duplicado.
Repeticiones. Una repetición devuelve la respuesta guardada con x-idempotent-replay: true. Un código QR nuevo devuelve false.
En curso. Una segunda solicitud mientras la primera sigue en curso devuelve 409 conflict.
Fallos. Si la creación falla, la clave se libera al instante, así que puedes reintentar con la misma clave.
Sin garantía. Si la protección no está disponible, las creaciones se procesan sin protección.

Consulta también Idempotencia.

Obtener un código QR

GET /api/v1/qrs/{qrId} Devuelve un código QR con su enlace corto, sus reglas de acceso, su diseño y, en los tipos basados en archivos, su archivo.

string

requerido

ID del código QR, de la respuesta del listado o de la creación.

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY"

La respuesta es el objeto de código QR completo.

Actualizar un código QR

PATCH /api/v1/qrs/{qrId} Cambia el contenido, el destino, el diseño o las reglas de acceso de un código QR. Envía solo los campos que quieras cambiar. Responde con el código QR actualizado.

string

requerido

ID del código QR.

El cuerpo acepta los mismos campos que Crear un código QR, todos opcionales, con estas diferencias:

templateId. No se acepta.
link. Parcial. El destino actual se conserva si omites link.url. link.domain y link.key devuelven 422: el enlace corto es lo que codifica el código impreso, así que crea un código QR nuevo para usar otro.
data. Solo se valida según el tipo resultante cuando cambia data o qrType. Se rechaza cambiar qrType sin un data que coincida. Consulta Cambio de tipo.
Diseño. styles, frameOptions y logoOptions se combinan con el diseño guardado, así que un objeto parcial solo cambia lo que indica. Elegir otro logotipo lo sustituye, pero conserva su tamaño.
access. Cada clave se aplica si está presente. null borra una regla. Las reglas de acceso van dentro de access: enviarlas dentro de link devuelve 422.
archived. Pausa o reactiva a la vez el código QR y su enlace corto, igual que Pausar y Reactivar.

curl -X PATCH "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Autumn campaign",
    "access": { "password": "s3cr3t", "passwordProtected": true }
  }'

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "title": "Autumn campaign",
  "access": { "passwordProtected": true, "activeAt": null, "pauseAt": null, "scanLimit": null },
  "…": "…"
}

Lo que cada tipo te permite cambiar tras imprimir se indica en Datos del código QR por tipo.

Establecer el estado de pausa

PUT /api/v1/qrs/{qrId} Establece directamente el estado de pausa. Pausar y Reactivar hacen lo mismo y se leen mejor.

string

requerido

ID del código QR.

boolean

requerido

true para pausar el código QR, false para reactivarlo.

curl -X PUT "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": true,
  "…": "…"
}

Pausar un código QR

POST /api/v1/qrs/{qrId}/pause Hace que el código QR deje de llevar a su destino: los escaneos muestran la página de pausa. El código impreso y su enlace corto siguen siendo válidos. Sin cuerpo de solicitud.

string

requerido

ID del código QR.

curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/pause" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": true,
  "…": "…"
}

Reactivar un código QR

POST /api/v1/qrs/{qrId}/activate Hace que un código QR pausado vuelva a llevar a su destino. La programación y el límite de escaneos siguen aplicándose. Sin cuerpo de solicitud.

string

requerido

ID del código QR.

curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/activate" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": false,
  "…": "…"
}

Duplicar un código QR

POST /api/v1/qrs/{qrId}/duplicate Crea una copia con el mismo contenido y diseño. Sin cuerpo de solicitud. Responde 201 Created con el nuevo código QR.

string

requerido

ID del código QR que se copia.

Enlace corto. La copia recibe su propio enlace corto, con un slug aleatorio en el dominio predeterminado del espacio de trabajo, no en el dominio del original. Sus escaneos se cuentan por separado.
Título. El título recibe el sufijo (Copy). El resultado no supera los 40 caracteres: un título largo se acorta antes. Un código QR sin título sigue sin título.
No se copia. Las reglas de acceso (contraseña, programación, límite de escaneos) y el estado de pausa. La copia siempre está activa.
Archivos. Los archivos PDF y de imagen, incluidos los de paquetes y galerías, se copian, así que pasan a ser de la copia. Los archivos de vídeo y los archivos de diseño, como los logotipos, se comparten con el original.

curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/duplicate" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "qr_7Hk2PqWmX9cTnV4sLbR8YdZe",
  "title": "Landing page (Copy)",
  "shortLink": "https://getqr.sh/p2Wq9dL",
  "url": "https://example.com",
  "archived": false,
  "scans": 0,
  "…": "…"
}

Eliminar un código QR

DELETE /api/v1/qrs/{qrId} Elimina el código QR y su enlace corto. Responde con el ID eliminado.

La eliminación es permanente. El código impreso y su enlace corto dejan de funcionar, y el historial de escaneos ya no se puede consultar. Si puedes volver a necesitarlo, pausa el código QR en su lugar.

string

requerido

ID del código QR.

string

ID del código QR eliminado.

boolean

Siempre true.

curl -X DELETE "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{ "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf", "deleted": true }

Descargar la imagen de un código QR

GET /api/v1/qrs/{qrId}/download Genera el código QR con su diseño y devuelve el archivo.

string

requerido

ID del código QR que se genera, de la respuesta del listado o de la creación.

string

predeterminado:"jpg"

Formato de salida: jpg, png, svg, pdf (una página A4) o eps. Un Branded design o un AI design solo se descarga en jpg, png o pdf.

integer

predeterminado:"1024"

Tamaño de la imagen en píxeles: 1024, 2048 o 4096. svg y pdf lo ignoran. Un Branded design o un AI design solo se descarga en 1024.

`format`	`Content-Type`	Nombre del archivo
`jpg`	`image/jpeg`	`<title>-<resolution>px.jpg`
`png`	`image/png`	`<title>-<resolution>px.png`
`svg`	`image/svg+xml`	`<title>.svg`
`pdf`	`application/pdf`	`<title>.pdf`
`eps`	`application/postscript`	`<title>-<resolution>px.eps`

Cuerpo. El cuerpo de la respuesta es el archivo. El nombre de archivo sugerido está en la cabecera Content-Disposition, formado a partir del título, o qr-code si el código QR no tiene título.
Caché. Las respuestas incluyen un ETag y Cache-Control: private, max-age=3600, must-revalidate. Devuelve el ETag en If-None-Match para recibir 304 Not Modified si el código QR no ha cambiado.
Errores. Un formato o una resolución no admitidos devuelven 400 bad_request. El mensaje de error indica el motivo: qr_download_invalid_format, qr_download_invalid_resolution, qr_download_art_format_unsupported o qr_download_art_resolution_unsupported.

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png

HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: attachment; filename="landing-page-1024px.png"
ETag: "9f2c0e1b5a7d43c8b016e2f4a9d5c3718be40f92"
Cache-Control: private, max-age=3600, must-revalidate

<binary image data>

Reglas de acceso

Envía un objeto access al crear o actualizar para programar un inicio y un final, limitar el número de escaneos o exigir una contraseña. Las reglas omitidas no cambian, y null borra una. El comportamiento completo, con ejemplos, está en Reglas de acceso.

Objetos de diseño

styles, frameOptions y logoOptions definen las formas de los puntos y las esquinas, los colores, el marco y el logotipo. Funcionan igual en códigos QR, plantillas y creaciones masivas. Las formas, los marcos o los logotipos desconocidos se rechazan. Todos los valores aceptados y un ejemplo completo están en Personalización.

Problemas habituales

422 al definir una contraseña, una programación o un límite de escaneos

Envía la regla dentro de access, no dentro de link.

422 al cambiar link.domain o link.key

El enlace corto no puede cambiar después de crearlo, porque es lo que codifica el código impreso. Crea un código QR nuevo en su lugar.

422 "Expected … for qrType"

data no coincide con el formato de qrType. Comprueba el tipo en Datos del código QR por tipo.

409 conflict al crear un código QR

Una creación idéntica sigue en curso, o link.key ya está en uso. Reintenta cuando termine la primera solicitud. Con una Idempotency-Key, el reintento devuelve el código QR original.

La descarga es un JPEG, no un PNG

Los parámetros son format y resolution, y format es jpg por defecto. Envía format=png.

404 en un código QR que veo en el panel

Cada solicitud se ejecuta en el espacio de trabajo de tu clave de API. Comprueba que el código QR pertenece a ese espacio de trabajo. Consulta Autenticación.

Datos del código QR por tipo

Personalización

Reglas de acceso

​El objeto de código QR

​Listar códigos QR

​Crear un código QR

​Reintentos y duplicados

​Obtener un código QR

​Actualizar un código QR

​Establecer el estado de pausa

​Pausar un código QR

​Reactivar un código QR

​Duplicar un código QR

​Eliminar un código QR

​Descargar la imagen de un código QR

​Reglas de acceso

​Objetos de diseño

​Problemas habituales

​Siguientes pasos

Datos del código QR por tipo

Personalización

Reglas de acceso

Analíticas

El objeto de código QR

Listar códigos QR

Crear un código QR

Reintentos y duplicados

Obtener un código QR

Actualizar un código QR

Establecer el estado de pausa

Pausar un código QR

Reactivar un código QR

Duplicar un código QR

Eliminar un código QR

Descargar la imagen de un código QR

Reglas de acceso

Objetos de diseño

Problemas habituales

Siguientes pasos