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

# Introducción a la API

> Gestiona códigos QR, plantillas, analíticas e informes desde tu propio código.

> [!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.

La API de GetQR es una API REST para lo que haces en el panel: crear y actualizar códigos QR, descargar sus imágenes, consultar las analíticas de escaneos y exportar informes. Autentícate con la clave de API de tu cuenta y llama a los endpoints versionados bajo `/api/v1`.

## Qué puedes hacer

> [card] [Códigos QR](https://docs.getqr.com/es/api/endpoints/qr-codes.md)
>
> Crea, lista, actualiza, pausa, duplica, elimina y descarga códigos QR.

> [card] [Analíticas](https://docs.getqr.com/es/api/endpoints/analytics.md)
>
> Totales y desgloses de escaneos de un código QR o de todo el espacio de trabajo.

> [card] [Informes](https://docs.getqr.com/es/api/endpoints/reports.md)
>
> Exporta un informe puntual o programa informes periódicos por correo.

> [card] [Plantillas](https://docs.getqr.com/es/api/endpoints/templates.md)
>
> Guarda diseños y aplícalos a códigos QR nuevos.

> [card] [Creación masiva de QR](https://docs.getqr.com/es/api/endpoints/bulk-qr-creations.md)
>
> Crea hasta 100 códigos QR a la vez desde JSON o un archivo CSV.

> [card] [Archivos](https://docs.getqr.com/es/api/endpoints/files.md)
>
> Sube PDF, imágenes, vídeos y logotipos para tus códigos QR.

> [card] [Estado](https://docs.getqr.com/es/api/endpoints/health.md)
>
> Comprueba que la API funciona. No necesita clave de API.

## Guías

> [card] [Tipos de QR](https://docs.getqr.com/es/api/guides/qr-types.md)
>
> El formato de datos de cada uno de los 16 tipos de QR.

> [card] [Personalización](https://docs.getqr.com/es/api/guides/customization.md)
>
> Estilos de puntos, esquinas, colores, marcos y logotipos.

> [card] [Reglas de acceso](https://docs.getqr.com/es/api/guides/access-rules.md)
>
> Programación, límites de escaneos, contraseñas, pausa y eliminación.

## URL base

Todos los endpoints están bajo una misma URL base:

```text theme={null}
https://getqr.com/api/v1
```

## Versiones

La versión de la API forma parte de la ruta: todos los endpoints están bajo `/api/v1/`.

* Los cambios incompatibles se publican con un nuevo prefijo de versión, como `/api/v2/`, y `/api/v1/` sigue funcionando.
* Los cambios compatibles, como campos opcionales o endpoints nuevos, pueden aparecer dentro de v1. Ignora los campos de respuesta que tu código no reconozca.

## Inicio rápido

**1. Obtén tu clave de API**

Genera o muestra tu clave en la configuración de tu cuenta. Consulta [Autenticación](https://docs.getqr.com/es/api/authentication.md).

**2. Comprueba que la API responde**

```bash theme={null}
curl https://getqr.com/api/v1/health
```

La respuesta es `{ "status": "ok", "version": "v1" }`.

**3. Crea tu primer código QR**

```bash theme={null}
curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-qr-0001" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page"
  }'
```

La API responde `201` con el nuevo código QR, incluidos su `id` y su `shortLink`.

**4. Descarga la imagen**

```bash theme={null}
curl "https://getqr.com/api/v1/qrs/{qrId}/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png
```

## Solicitudes y respuestas

* **Formato.** Envía el cuerpo de las solicitudes como JSON con `Content-Type: application/json`. La excepción es la subida de CSV de la [creación masiva](https://docs.getqr.com/es/api/endpoints/bulk-qr-creations.md), que usa `multipart/form-data`.
* **Respuestas.** Las respuestas son JSON. Las descargas, como las imágenes de QR y los archivos ZIP de la creación masiva, devuelven el propio archivo.
* **Fechas.** Las fechas son cadenas ISO 8601 en UTC, por ejemplo `2026-08-01T10:00:00.000Z`.
* **Parámetros de consulta.** Los parámetros booleanos aceptan las cadenas `true` o `false`.
* **Actualizaciones parciales.** Los endpoints `PATCH` solo cambian los campos que envías.
* **Secretos.** Las respuestas nunca incluyen contraseñas ni identificadores internos. Un código QR protegido con contraseña solo indica `passwordProtected: true`.
* **Espacio de trabajo.** Cada solicitud se ejecuta en el espacio de trabajo al que pertenece tu clave de API. No indicas ningún ID de espacio de trabajo. Consulta [Acceso y roles](https://docs.getqr.com/es/api/authentication.md#acceso-y-roles).
* **Errores.** Las solicitudes fallidas devuelven un objeto `error` con un `code` estable. Consulta [Errores](https://docs.getqr.com/es/api/errors.md).

## Paginación

Los endpoints de listado (códigos QR, plantillas e informes programados) aceptan dos parámetros de consulta:

| Parámetro | Descripción |
| - | - |
| `page` | Página que se devuelve. Por defecto, `1`. |
| `pageSize` | Resultados por página, hasta `100`. Por defecto, `100`. |

Responden con un array `data` y un objeto `pagination`:

```json theme={null}
{
  "data": [ … ],
  "pagination": { "page": 1, "pageSize": 50, "total": 128, "hasMore": true }
}
```

| Campo | Descripción |
| - | - |
| `page` | La página que has recibido. |
| `pageSize` | El tamaño de página que has recibido. |
| `total` | Número de resultados en todas las páginas. |
| `hasMore` | `true` mientras quede otra página. |

Pide la página siguiente mientras `hasMore` sea `true`. Un `pageSize` mayor que `100` devuelve [`422`](https://docs.getqr.com/es/api/errors#errores-de-validación).

## Idempotencia

Un error de red puede dejarte sin saber si una solicitud ha llegado. Para reintentar [Crear un código QR](https://docs.getqr.com/es/api/endpoints/qr-codes.md#crear-un-código-qr) de forma segura, envía una cabecera `Idempotency-Key` con un valor único que elijas tú:

```bash theme={null}
-H "Idempotency-Key: order-4821-qr"
```

* 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.
* La cabecera de respuesta `x-idempotent-replay` es `true` en una respuesta repetida y `false` en una nueva.
* Si la primera solicitud con esa clave sigue en curso, la API responde `409 conflict`. Reintenta cuando termine.
* Si reutilizas una clave con otro cuerpo de solicitud, la respuesta es `422 unprocessable_entity`.
* Sin la cabecera, un cuerpo de solicitud idéntico enviado en menos de 30 segundos se trata como duplicado.

La creación masiva usa en su lugar un campo `idempotencyKey` en el cuerpo de la solicitud. Consulta [Creación masiva de QR](https://docs.getqr.com/es/api/endpoints/bulk-qr-creations.md).

## Límites de tasa

Cada clave de API puede enviar hasta 600 solicitudes por minuto. Consulta [Límites de tasa](https://docs.getqr.com/es/api/rate-limits.md).

## Próximamente

Los paquetes listos para imprimir llegarán en una versión posterior.

## Siguientes pasos

> [card] [Autenticación](https://docs.getqr.com/es/api/authentication.md)

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


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