> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Creación masiva de QR

> Crea hasta 100 códigos QR a la vez y descárgalos en un archivo ZIP.

> [!NOTE]
>
> 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](#obtener-la-creación-masiva-actual) |
| `POST` | `/api/v1/bulk-qr-creations` | [Crear desde JSON](#crear-desde-json) |
| `POST` | `/api/v1/bulk-qr-creations/csv` | [Crear desde un archivo CSV](#crear-desde-un-archivo-csv) |
| `GET` | `/api/v1/bulk-qr-creations/{id}` | [Obtener una creación masiva](#obtener-una-creación-masiva) |
| `DELETE` | `/api/v1/bulk-qr-creations/{id}` | [Cancelar una creación masiva](#cancelar-una-creación-masiva) |
| `GET` | `/api/v1/bulk-qr-creations/{id}/download` | [Descargar el archivo ZIP](#descargar-el-archivo-zip) |

## Cómo funciona

**1. Inicia la creación masiva**

Envía tus filas con [Crear desde JSON](#crear-desde-json) o [Crear desde un archivo CSV](#crear-desde-un-archivo-csv). La API responde `202` con la creación masiva y su `id`.

**2. Consulta su progreso**

Llama a [Obtener una creación masiva](#obtener-una-creación-masiva) cada pocos segundos hasta que `status` sea `completed` o `failed`.

**3. Descarga el archivo ZIP**

Cuando `status` sea `completed`, llama a [Descargar el archivo ZIP](#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](#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](https://docs.getqr.com/es/api/guides/qr-types.md).

## Cabeceras

**Authorization** `string` *required*

`Bearer` seguido de tu clave de API. Consulta [Autenticación](https://docs.getqr.com/es/api/authentication.md).

**Content-Type** `string`

`application/json` para [Crear desde JSON](#crear-desde-json), `multipart/form-data` para [Crear desde un archivo CSV](#crear-desde-un-archivo-csv).

## El objeto de creación masiva

**id** `string`

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

**status** `string`

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

**sourceFilename** `string`

Nombre del archivo de origen.

**totalCount** `integer`

Número de filas.

**createdCount** `integer`

Códigos QR creados hasta ahora.

**renderedCount** `integer`

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

**percent** `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.

**stalled** `boolean`

`true` cuando una creación masiva en curso lleva 2 minutos sin avanzar. Sigue consultando: [Obtener una creación masiva](#obtener-una-creación-masiva) reinicia una creación masiva detenida.

**error** `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.

**downloadUrl** `string | null`

Ruta de [Descargar el archivo ZIP](#descargar-el-archivo-zip), cuando `status` es `completed`.

**createdAt** `string`

Fecha de inicio, ISO 8601.

**updatedAt** `string`

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

**completedAt** `string | null`

Fecha de finalización, ISO 8601.

**failedAt** `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.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "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
}
```

```json 200 (nothing to resume) theme={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.

**rows** `object[]` *required*

Códigos QR que se crean, hasta 100. Cada fila es `{ "name": "...", "url": "..." }` y no admite otros campos. Consulta [Filas](#filas).

**design** `object` *required*

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](https://docs.getqr.com/es/api/guides/customization.md).

**sourceFilename** `string` *required*

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

**idempotencyKey** `string` *required*

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

```bash cURL theme={null}
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"
  }'
```

```json 202 theme={null}
{
  "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](#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](https://docs.getqr.com/es/bulk/csv-format.md).

**file** `file` *required*

El archivo CSV.

**design** `string` *required*

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

**idempotencyKey** `string` *required*

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

**sourceFilename** `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.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/bulk-qr-creations/csv" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -F "file=@campaign-links.csv" \
  -F 'design={"styles":{"dotsOptions":{"type":"rounded"}}}' \
  -F "idempotencyKey=campaign-2026-08-14"
```

```csv campaign-links.csv theme={null}
name,url
Menu,https://example.com/menu
Wine list,example.com/wine
```

```json 202 theme={null}
{
  "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.

**id** `string` *required*

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

```bash cURL theme={null}
curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "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.

> [!WARNING]
>
> 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](https://docs.getqr.com/es/api/endpoints/qr-codes.md).

**id** `string` *required*

ID de la creación masiva.

```bash cURL theme={null}
curl -X DELETE "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "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](#obtener-la-creación-masiva-actual) deja de devolverla.

**id** `string` *required*

ID de la creación masiva.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t/download" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-codes.zip
```

```http 200 theme={null}
HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="campaign-links-qr-codes.zip"

<binary archive data>
```

## Problemas habituales

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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`.

> [accordion] 400 "Cannot cancel a finished bulk QR creation."
>
> La creación masiva ya ha terminado, así que no se puede revertir.

> [accordion] 403 exceeded\_limit
>
> Tu espacio de trabajo tiene el plan Single QR, que no incluye la creación masiva. Mejora el plan.

> [accordion] 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.

## Siguientes pasos

> [card] [Personalización](https://docs.getqr.com/es/api/guides/customization.md)

> [card] [Códigos QR](https://docs.getqr.com/es/api/endpoints/qr-codes.md)

> [card] [Creación masiva en la app](https://docs.getqr.com/es/bulk/overview.md)

> [card] [Formato CSV](https://docs.getqr.com/es/bulk/csv-format.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.