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

# Archivos

> Sube PDF, imágenes, vídeos y logotipos para tus códigos QR.

> [!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 códigos QR de PDF, imagen y vídeo apuntan a un archivo, y un logotipo personalizado también es un archivo. La subida tiene dos pasos: registra el archivo para obtener una URL y envía después los bytes a esa URL.

| Método | Ruta | Descripción |
| - | - | - |
| `POST` | `/api/v1/files` | [Registrar la subida de un archivo](#registrar-la-subida-de-un-archivo) |

## Sube un archivo

**1. Registra el archivo**

Llama a [Registrar la subida de un archivo](#registrar-la-subida-de-un-archivo) con el `target`, el `contentType` y el `size` del archivo. El `target` determina los tipos de contenido admitidos y el límite de tamaño. Recibes un `fileId` y una `uploadUrl`.

**2. Envía el archivo**

Envía el archivo con una solicitud `PUT` a `uploadUrl`. Su `Content-Type` y su `Content-Length` deben coincidir exactamente con el `contentType` y el `size` que registraste: cualquier otro valor se rechaza. La URL está prefirmada, así que no añadas tu clave de API. Caduca a los 10 minutos.

```bash theme={null}
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @menu.pdf
```

**3. Usa el ID del archivo**

Pasa `fileId` al [crear un código QR](https://docs.getqr.com/es/api/endpoints/qr-codes.md):

* Como `fileId` en un código QR `pdf`, `image` o `video`. Súbelo con el target correspondiente.
* Como `fileId` para la imagen de perfil de un código QR `vcard`, `social`, `multilink` o `event`. Súbelo con el target `logo`.
* Como `logoOptions.fileId`, con `logoOptions.type` definido como `uploaded`, para un logotipo personalizado. Súbelo con el target `logo`. Consulta [Personalización](https://docs.getqr.com/es/api/guides/customization.md).

## Límites

| `target` | Tipos de contenido admitidos | Tamaño máximo |
| - | - | - |
| `pdf` | `application/pdf` | 20 MB (20.971.520 bytes) |
| `image` | `image/*` | 5 MB (5.242.880 bytes) |
| `video` | `video/*` | 50 MB (52.428.800 bytes) |
| `logo` | `image/*` | 5 MB (5.242.880 bytes) |

* **Tipo MIME simple.** Envía un único tipo y subtipo en minúsculas, como `image/png`. Se rechazan los parámetros, como `;charset=`, y las listas.
* **Sin SVG.** No se aceptan tipos basados en XML, como `image/svg+xml`. Sube una imagen de mapa de bits, como `image/png` o `image/jpeg`.

## 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` *required*

`application/json`.

## Registrar la subida de un archivo

`POST /api/v1/files`

Registra un archivo y devuelve una URL prefirmada a la que subirlo. Esta llamada no sube el archivo en sí.

**target** `string` *required*

Para qué es el archivo: `pdf`, `image`, `video` o `logo`. Determina los tipos de contenido admitidos y el límite de tamaño. Consulta [Límites](#límites).

**contentType** `string` *required*

Tipo MIME del archivo, por ejemplo `application/pdf`, sin parámetros. La solicitud de subida debe enviar exactamente este `Content-Type`.

**size** `integer` *required*

Tamaño exacto del archivo en bytes, un número entero positivo. Se comprueba con el límite del target. La solicitud de subida debe enviar exactamente este `Content-Length`.

**name** `string`

Nombre original del archivo, hasta 255 caracteres. Se conserva para mostrarlo en el panel. Se rechaza una ruta con `/` o `\`.

**fileId** `string`

ID que se pasa como `fileId` o `logoOptions.fileId`.

**uploadUrl** `string`

URL prefirmada a la que se envía el archivo con `PUT`.

**expiresIn** `integer`

Segundos que faltan para que caduque `uploadUrl`: `600`.

**method** `string`

Método HTTP de la subida: `PUT`.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/files" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "pdf",
    "contentType": "application/pdf",
    "size": 248000,
    "name": "menu.pdf"
  }'
```

```json 200 theme={null}
{
  "fileId": "file_7bQ2xR9mKp",
  "uploadUrl": "https://storage.getqr.com/qrs-content/pdf/file_7bQ2xR9mKp?X-Amz-...",
  "expiresIn": 600,
  "method": "PUT"
}
```

## Problemas habituales

> [accordion] 422 "Content type … is not allowed for target"
>
> El tipo de contenido no coincide con el target. Por ejemplo, `pdf` solo acepta `application/pdf`. Consulta [Límites](#límites).

> [accordion] 422 "must be a single lowercase type/subtype"
>
> Envía el tipo de contenido en minúsculas y sin parámetros: `image/png`, no `Image/PNG` ni `image/png; charset=utf-8`.

> [accordion] 422 "File is too large for target"
>
> El `size` declarado supera el límite del target. Comprime el archivo antes de registrarlo.

> [accordion] Falla la subida a uploadUrl
>
> La URL caduca 10 minutos después de registrar el archivo, y la solicitud debe enviar exactamente el `Content-Type` y el `Content-Length` registrados. Vuelve a registrar el archivo para obtener una URL nueva.

> [accordion] 422 "is registered but its content was never uploaded" al crear un código QR
>
> Registraste el archivo, pero el `PUT` a `uploadUrl` no se completó. Sube el archivo y crea después el código QR.

> [accordion] 422 "was uploaded to …" al crear un código QR
>
> El archivo se registró con otro target, por ejemplo un archivo `image` usado para un código QR `pdf`. Registra una nueva subida con el target correspondiente.

> [accordion] 404 "File … was not found" al crear un código QR
>
> El `fileId` no existe. Tómalo de la respuesta de [Registrar la subida de un archivo](#registrar-la-subida-de-un-archivo).

## Siguientes pasos

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

> [card] [Tipos de QR](https://docs.getqr.com/es/api/guides/qr-types.md)

> [card] [Personalización](https://docs.getqr.com/es/api/guides/customization.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.