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

# Informes

> Exporta un informe de escaneos puntual o programa informes periódicos por correo.

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

Los informes resumen los escaneos por código QR de un día, una semana o un mes ya cerrados. Exporta uno al momento o programa un informe que se envíe por correo con regularidad.

| Método | Ruta | Descripción |
| - | - | - |
| `POST` | `/api/v1/reports` | [Exportar un informe](#exportar-un-informe) |
| `GET` | `/api/v1/reports/schedules` | [Listar informes programados](#listar-informes-programados) |
| `POST` | `/api/v1/reports/schedules` | [Programar un informe](#programar-un-informe) |
| `PATCH` | `/api/v1/reports/schedules/{id}` | [Actualizar un informe programado](#actualizar-un-informe-programado) |
| `DELETE` | `/api/v1/reports/schedules/{id}` | [Eliminar un informe programado](#eliminar-un-informe-programado) |

## 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`. Obligatorio en las solicitudes `POST` y `PATCH`.

## Ámbito

Tanto los informes puntuales como los programados aceptan un `scope`:

| `scope` | Cubre | `qrIds` |
| - | - | - |
| `all` | Los códigos QR de tu espacio de trabajo | Omítelo |
| `selected` | Un conjunto elegido de códigos QR | Uno o más ID |
| `single` | Exactamente un código QR | Exactamente un ID |

Un informe incluye como máximo 50 códigos QR. Con `all`, son los códigos QR activos creados más recientemente; los códigos pausados se excluyen. Con `selected` y `single`, los códigos pausados se incluyen. Los códigos QR sin enlace corto no tienen escaneos y se omiten.

## Periodo

El periodo es siempre el último ya cerrado, así que un informe nunca incluye los datos parciales de hoy. Sus límites son la medianoche en la zona horaria del informe.

| `period` o `frequency` | Cubre |
| - | - |
| `daily` | El día anterior |
| `weekly` | La semana anterior, de lunes a domingo |
| `monthly` | El mes natural anterior |

## Exportar un informe

`POST /api/v1/reports`

Genera un informe del último periodo cerrado y lo devuelve en la respuesta.

**scope** `string` *required*

`all`, `selected` o `single`. Consulta [Ámbito](#ámbito).

**period** `string` *required*

`daily`, `weekly` o `monthly`. Consulta [Periodo](#periodo).

**format** `string` *required*

`json` devuelve el informe en el cuerpo de la respuesta. `csv` y `pdf` devuelven un archivo para descargar.

**qrIds** `string[]`

Códigos QR que se incluyen. Obligatorio con `selected` (uno o más ID) y `single` (exactamente un ID). Omítelo con `all`.

**timezone** `string` (default: UTC)

Zona horaria IANA con la que se alinean los límites del periodo, por ejemplo `America/New_York`. Una zona horaria desconocida devuelve `422`.

**locale** `string` (default: en)

Idioma del PDF, por ejemplo `en` o `de`. Un valor no admitido pasa a inglés. `csv` y `json` lo ignoran.

**name** `string`

Título que aparece en el PDF, hasta 40 caracteres. `csv` y `json` lo ignoran.

### Respuesta JSON

**periodStart** `string`

Primer día del periodo, `YYYY-MM-DD`.

**periodEnd** `string`

Primer día después del periodo, `YYYY-MM-DD`. El periodo termina a la medianoche del inicio de este día.

**qrs** `object[]`

Una entrada por código QR.

**properties**

**qrId** `string`

ID del código QR.

**name** `string`

Título del código QR, o `Untitled QR`.

**type** `string`

Tipo de código QR, por ejemplo `website`.

**totalScans** `integer`

Escaneos totales del periodo.

**uniqueScans** `integer`

Escaneos únicos del periodo.

**topGeography** `string`

Código del país con más escaneos, o `—` si no hay escaneos.

**topDevice** `string`

Dispositivo con más escaneos, o `—`.

**topOs** `string`

Sistema operativo con más escaneos, o `—`.

**topBrowser** `string`

Navegador con más escaneos, o `—`.

### Respuestas CSV y PDF

El cuerpo es el archivo. `Content-Disposition` le pone el nombre del periodo, por ejemplo `report-2026-08-10_2026-08-17.csv`. El CSV tiene una fila por código QR con las columnas `QR ID`, `QR name`, `QR type`, `Total scans`, `Unique scans`, `Top geography`, `Top device`, `Top OS` y `Top browser`.

```bash JSON theme={null}
curl -X POST "https://getqr.com/api/v1/reports" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "selected",
    "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
    "period": "weekly",
    "format": "json",
    "timezone": "America/New_York"
  }'
```

```bash PDF theme={null}
curl -X POST "https://getqr.com/api/v1/reports" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "all", "period": "monthly", "format": "pdf", "locale": "de" }' \
  --output report.pdf
```

```json 200 theme={null}
{
  "periodStart": "2026-08-10",
  "periodEnd": "2026-08-17",
  "qrs": [
    {
      "qrId": "clw3n7t1x0002ab0d5mqe8pkr",
      "name": "Landing page",
      "type": "website",
      "totalScans": 128,
      "uniqueScans": 96,
      "topGeography": "US",
      "topDevice": "Mobile",
      "topOs": "iOS",
      "topBrowser": "Safari"
    }
  ]
}
```

## El objeto de informe programado

Un informe programado se envía por correo a la cuenta que lo creó, a medianoche en su zona horaria.

**id** `string`

ID del informe programado.

**name** `string | null`

Etiqueta que aparece en el asunto del correo y en el panel.

**frequency** `string`

`daily`, `weekly` o `monthly`.

**scope** `string`

`all`, `selected` o `single`.

**qrIds** `string[] | null`

Códigos QR que cubre el informe con los ámbitos `selected` y `single`. `null` si no se enviaron ID.

**filters** `null`

Siempre `null`. Reservado.

**includePdf** `boolean`

Si se adjunta un PDF al correo.

**status** `string`

`active` o `paused`.

**timezone** `string`

Zona horaria IANA con la que se alinean la hora de envío y el periodo.

**locale** `string`

Idioma del correo y del PDF.

**nextRunAt** `string`

Cuándo toca el próximo correo, ISO 8601: la próxima medianoche (`daily`), el próximo lunes (`weekly`) o el día 1 del mes siguiente (`monthly`), en la zona horaria del informe.

**lastRunAt** `string | null`

Cuándo se envió el último correo, ISO 8601.

**createdAt** `string`

Fecha de creación, ISO 8601.

**updatedAt** `string`

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

## Listar informes programados

`GET /api/v1/reports/schedules`

Devuelve los informes programados de tu espacio de trabajo, incluidos los creados por otros miembros, del más reciente al más antiguo. La lista está paginada: consulta [Paginación](https://docs.getqr.com/es/api/introduction.md#paginación).

**page** `integer` (default: 1)

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

**pageSize** `integer` (default: 100)

Resultados por página, de 1 a 100.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/reports/schedules?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "clx8f2k9a0001qk0c8vhd3xyz",
      "name": "Weekly campaign digest",
      "frequency": "weekly",
      "scope": "selected",
      "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr", "clw3n7t1x0004ab0d9rzu2wfh"],
      "filters": null,
      "includePdf": true,
      "status": "active",
      "timezone": "America/New_York",
      "locale": "en",
      "nextRunAt": "2026-08-10T04:00:00.000Z",
      "lastRunAt": "2026-08-03T04:00:12.000Z",
      "createdAt": "2026-07-01T12:34:56.000Z",
      "updatedAt": "2026-07-28T09:12:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}
```

## Programar un informe

`POST /api/v1/reports/schedules`

Crea un informe que se envía por correo con regularidad. `nextRunAt` se calcula a partir de la frecuencia y la zona horaria.

> [!NOTE]
>
> Un código QR solo puede pertenecer a un informe programado por frecuencia. Una programación que se solapa devuelve `409 conflict`.

Un informe con el ámbito `all` se solapa con todos los demás informes de la misma frecuencia. Los informes pausados también cuentan.

**frequency** `string` *required*

Con qué frecuencia se envía el informe: `daily`, `weekly` o `monthly`. También define el periodo que cubre. Consulta [Periodo](#periodo).

**scope** `string` *required*

`all`, `selected` o `single`. Consulta [Ámbito](#ámbito).

**timezone** `string` *required*

Zona horaria IANA con la que se alinean la hora de envío y el periodo, por ejemplo `America/New_York`. Una zona horaria desconocida devuelve `422`.

**locale** `string` *required*

Idioma del correo y del PDF, por ejemplo `en` o `de`. Un valor no admitido pasa a inglés. Los PDF en `zh`, `ja`, `ko` y `ar` se generan en inglés.

**qrIds** `string[]`

Códigos QR que se incluyen. Obligatorio con `selected` (uno o más ID) y `single` (exactamente un ID). Cada ID debe ser un código QR de tu espacio de trabajo, o la solicitud devuelve `404`.

**name** `string`

Etiqueta que aparece en el asunto del correo y en el panel, hasta 40 caracteres.

**includePdf** `boolean` (default: false)

Adjunta una versión en PDF del informe al correo.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/reports/schedules" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly campaign digest",
    "frequency": "weekly",
    "scope": "selected",
    "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
    "includePdf": true,
    "timezone": "America/New_York",
    "locale": "en"
  }'
```

```json 200 theme={null}
{
  "id": "clx8f2k9a0001qk0c8vhd3xyz",
  "name": "Weekly campaign digest",
  "frequency": "weekly",
  "scope": "selected",
  "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
  "filters": null,
  "includePdf": true,
  "status": "active",
  "timezone": "America/New_York",
  "locale": "en",
  "nextRunAt": "2026-08-10T04:00:00.000Z",
  "lastRunAt": null,
  "createdAt": "2026-08-03T12:34:56.000Z",
  "updatedAt": "2026-08-03T12:34:56.000Z"
}
```

## Actualizar un informe programado

`PATCH /api/v1/reports/schedules/{id}`

Cambia un informe programado, o lo pausa y lo reanuda. Envía solo los campos que quieras cambiar, al menos uno. Cambiar la frecuencia o la zona horaria, o reanudar un informe pausado, recalcula `nextRunAt`. La regla de un informe por frecuencia sigue aplicándose, así que un cambio que se solapa devuelve `409`.

**id** `string` *required*

ID del informe programado. Tómalo de la respuesta del listado o de la creación.

**status** `string`

`paused` detiene los correos sin eliminar la programación. `active` los reanuda.

**name** `string`

Etiqueta, hasta 40 caracteres.

**frequency** `string`

`daily`, `weekly` o `monthly`.

**scope** `string`

`all`, `selected` o `single`.

**qrIds** `string[]`

Códigos QR que se incluyen. Cada ID debe ser un código QR de tu espacio de trabajo.

**includePdf** `boolean`

Adjunta un PDF al correo.

**timezone** `string`

Zona horaria IANA.

**locale** `string`

Idioma del correo y del PDF.

```bash cURL theme={null}
curl -X PATCH "https://getqr.com/api/v1/reports/schedules/clx8f2k9a0001qk0c8vhd3xyz" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly campaign digest",
    "frequency": "monthly",
    "status": "active"
  }'
```

```json 200 theme={null}
{
  "id": "clx8f2k9a0001qk0c8vhd3xyz",
  "name": "Monthly campaign digest",
  "frequency": "monthly",
  "scope": "selected",
  "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
  "filters": null,
  "includePdf": true,
  "status": "active",
  "timezone": "America/New_York",
  "locale": "en",
  "nextRunAt": "2026-09-01T04:00:00.000Z",
  "lastRunAt": "2026-08-03T04:00:12.000Z",
  "createdAt": "2026-07-01T12:34:56.000Z",
  "updatedAt": "2026-08-05T10:15:00.000Z"
}
```

## Eliminar un informe programado

`DELETE /api/v1/reports/schedules/{id}`

Elimina la programación y detiene todos los correos siguientes.

> [!WARNING]
>
> La eliminación de un informe programado no se puede deshacer.

**id** `string` *required*

ID del informe programado.

```bash cURL theme={null}
curl -X DELETE "https://getqr.com/api/v1/reports/schedules/clx8f2k9a0001qk0c8vhd3xyz" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{ "id": "clx8f2k9a0001qk0c8vhd3xyz", "deleted": true }
```

## Problemas habituales

> [accordion] 404 al exportar un informe
>
> Con el ámbito `selected` o `single`, ninguno de los `qrIds` coincide con un código QR con enlace corto de tu espacio de trabajo. Comprueba los ID.

> [accordion] 404 "QR not found." al programar un informe
>
> Uno de los `qrIds` no es un código QR de tu espacio de trabajo, o se ha eliminado. Comprueba los ID con [Listar códigos QR](https://docs.getqr.com/es/api/endpoints/qr-codes.md).

> [accordion] 409 al programar un informe
>
> Uno de los códigos QR ya pertenece a un informe programado con la misma frecuencia, o un informe de esa frecuencia usa el ámbito `all`. Edita o elimina ese informe, o elige otra frecuencia.

> [accordion] 404 "Scheduled report not found."
>
> El `id` no coincide con ningún informe programado de tu espacio de trabajo. Tómalo de [Listar informes programados](#listar-informes-programados).

> [accordion] Al informe le faltan los escaneos de hoy
>
> Los informes solo cubren el último periodo cerrado. Usa [Analíticas](https://docs.getqr.com/es/api/endpoints/analytics.md) para ver los números en tiempo real.

## Siguientes pasos

> [card] [Analíticas](https://docs.getqr.com/es/api/endpoints/analytics.md)

> [card] [Informes programados en la app](https://docs.getqr.com/es/analytics/scheduled-reports.md)

> [card] [Lee tus informes](https://docs.getqr.com/es/analytics/reading-reports.md)

> [card] [Errores](https://docs.getqr.com/es/api/errors.md)


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