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

# ファイル

> QR コードで使う PDF、画像、動画、ロゴをアップロードします。

> [!NOTE]
>
> GetQR API はベータ版で、一部のワークスペースでのみご利用いただけます。正式リリースまでに内容が変更される場合があります。

PDF、Image、Video の QR コードはファイルを指しており、独自のロゴもファイルです。アップロードは 2 段階です。ファイルを登録して URL を受け取り、その URL にファイルのバイトを送ります。

| メソッド | パス | 説明 |
| - | - | - |
| `POST` | `/api/v1/files` | [ファイルのアップロードを登録する](#ファイルのアップロードを登録する) |

## ファイルをアップロードする

**1. ファイルを登録する**

ファイルの `target`、`contentType`、`size` を指定して [ファイルのアップロードを登録する](#ファイルのアップロードを登録する) を呼び出します。`target` によって、受け付けるコンテンツタイプとサイズの上限が決まります。`fileId` と `uploadUrl` が返されます。

**2. ファイルを送る**

`uploadUrl` に `PUT` リクエストでファイルを送ります。`Content-Type` と `Content-Length` は、登録した `contentType` と `size` に完全に一致する必要があり、一致しない場合は拒否されます。URL は署名付きなので、API キーは付けないでください。URL の有効期限は 10 分です。

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

**3. ファイル ID を使う**

[QR コードを作成する](https://docs.getqr.com/ja/api/endpoints/qr-codes.md) ときに `fileId` を渡します。

* `pdf`、`image`、`video` の QR コードの `fileId` として。対応する用途でアップロードします。
* `vcard`、`social`、`multilink`、`event` の QR コードのプロフィール画像の `fileId` として。`logo` 用途でアップロードします。
* 独自のロゴには、`logoOptions.type` を `uploaded` にして `logoOptions.fileId` として。`logo` 用途でアップロードします。[カスタマイズ](https://docs.getqr.com/ja/api/guides/customization.md) をご覧ください。

## 制限

| `target` | 受け付けるコンテンツタイプ | 最大サイズ |
| - | - | - |
| `pdf` | `application/pdf` | 20 MB（20,971,520 バイト） |
| `image` | `image/*` | 5 MB（5,242,880 バイト） |
| `video` | `video/*` | 50 MB（52,428,800 バイト） |
| `logo` | `image/*` | 5 MB（5,242,880 バイト） |

* **パラメータなしの MIME タイプ。** `image/png` のように、小文字のタイプとサブタイプを 1 つだけ送ります。`;charset=` のようなパラメータやリストは拒否されます。
* **SVG は不可。** `image/svg+xml` のような XML ベースのタイプは受け付けません。`image/png` や `image/jpeg` などのラスター画像をアップロードしてください。

## ヘッダー

**Authorization** `string` *required*

`Bearer` の後に API キーを続けます。[認証](https://docs.getqr.com/ja/api/authentication.md) をご覧ください。

**Content-Type** `string` *required*

`application/json`。

## ファイルのアップロードを登録する

`POST /api/v1/files`

ファイルを登録し、アップロード先の署名付き URL を返します。この呼び出し自体はファイルをアップロードしません。

**target** `string` *required*

ファイルの用途：`pdf`、`image`、`video`、`logo`。受け付けるコンテンツタイプとサイズの上限が決まります。[制限](#制限) をご覧ください。

**contentType** `string` *required*

ファイルの MIME タイプ（パラメータなし）。例：`application/pdf`。アップロードのリクエストでは、これと完全に同じ `Content-Type` を送る必要があります。

**size** `integer` *required*

ファイルの正確なサイズ（バイト単位の正の整数）。用途ごとの上限と照らし合わせて確認されます。アップロードのリクエストでは、これと完全に同じ `Content-Length` を送る必要があります。

**name** `string`

元のファイル名。最大 255 文字。ダッシュボードでの表示用に保持されます。`/` や `\` を含むパスは拒否されます。

**fileId** `string`

`fileId` または `logoOptions.fileId` として渡す ID。

**uploadUrl** `string`

ファイルを `PUT` する署名付き URL。

**expiresIn** `integer`

`uploadUrl` の有効期限が切れるまでの秒数：`600`。

**method** `string`

アップロードに使う HTTP メソッド：`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"
}
```

## よくある問題

> [accordion] 422 "Content type … is not allowed for target"
>
> コンテンツタイプが用途と一致していません。たとえば、`pdf` が受け付けるのは `application/pdf` だけです。[制限](#制限) をご覧ください。

> [accordion] 422 "must be a single lowercase type/subtype"
>
> コンテンツタイプは小文字で、パラメータを付けずに送ってください。`Image/PNG` や `image/png; charset=utf-8` ではなく `image/png` です。

> [accordion] 422 "File is too large for target"
>
> 宣言した `size` が用途の上限を超えています。登録する前にファイルを圧縮してください。

> [accordion] uploadUrl へのアップロードが失敗する
>
> URL の有効期限はファイルの登録から 10 分で、リクエストでは登録したとおりの `Content-Type` と `Content-Length` を送る必要があります。新しい URL を取得するには、ファイルをもう一度登録してください。

> [accordion] QR コードの作成時に 422 "is registered but its content was never uploaded"
>
> ファイルは登録されましたが、`uploadUrl` への `PUT` が完了していません。ファイルをアップロードしてから QR コードを作成してください。

> [accordion] QR コードの作成時に 422 "was uploaded to …"
>
> ファイルが別の用途で登録されています。たとえば、`pdf` の QR コードに `image` のファイルを使った場合です。対応する用途で新しくアップロードを登録してください。

> [accordion] QR コードの作成時に 404 "File … was not found"
>
> その `fileId` は存在しません。[ファイルのアップロードを登録する](#ファイルのアップロードを登録する) のレスポンスから取得してください。

## 次のステップ

> [card] [QR コード](https://docs.getqr.com/ja/api/endpoints/qr-codes.md)

> [card] [QR コードの種類](https://docs.getqr.com/ja/api/guides/qr-types.md)

> [card] [カスタマイズ](https://docs.getqr.com/ja/api/guides/customization.md)

> [card] [エラー](https://docs.getqr.com/ja/api/errors.md)


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