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

# 印刷とラベル

> ZPL と PDF のラベルを物理プリンターに送信します。プリンターのルートとロケーションごとの割り当てを設定し、入荷、出荷、分割、製造指図の開始での自動印刷を制御し、すべてのラベルを印刷ジョブキューで追跡します。

印刷は、部品、バッチ、棚、かんばんのビンに物理的なラベルを貼る機能です。管理者がプリンターを接続し、各ステーションで使うプリンターを決めると、倉庫や現場のスタッフは、入荷を転記したとき、バッチを分割したとき、製造指図の最初の工程を終えたときに、自動的にラベルを受け取ります。

## 概要

印刷システムは 3 つの部分からなります。

| 部分 | 役割 |
| - | - |
| **プリンタールート** | 物理プリンター 1 台につき 1 レコード。どこに、どの形式で配信するかを示します。 |
| **割り当て** | 各ロケーションとコンテキストでどのプリンターを使うか、また自動で印刷するかどうか。 |
| **印刷ジョブキュー** | 自動・手動を問わず、すべての印刷を、レンダリングから配信まで追跡します。 |

これは、請求書、発注書、見積、製造指図の現品票など、ファイルとして届く生成ドキュメントとは異なります。印刷は出力を**物理プリンター**に送るもので、デフォルトでは、その出力は感熱式の ZPL ラベルです。

### 形式

ジョブがどのプリンターにルーティングされるかによって、レンダリングの方法が決まります。

* **ZPL** は感熱式ラベルプリンターのコマンド言語で、部品ラベルと保管ラベルのデフォルトです。ZPL ラベルは、メディアサイズに ZPL の寸法がある場合にのみレンダリングされます。
* **PDF** は完全なドキュメントで、請求書や現品票を生成するのと同じ React-PDF エンジンで描画されます。かんばんカードは**PDF のみ**のため、テンプレートで対応しない限り、ZPL 専用のプリンターに送ると失敗します。

### ドキュメントタイプ

3 種類のラベルが定義されています（`packages/web/printing/src/registry.ts` の `documentTypeRegistry`）。

FieldType

<details>
  <summary>**productLabel**`zpl default`</summary>

  追跡対象エンティティ（シリアルまたはバッチ番号）のラベル。`Receipt`、`Shipment`、`Operation`、`Entity`、`Job`、`Split`、`StockTransfer` から印刷されます。
</details>

<details>
  <summary>**storageUnitLabel**`zpl default`</summary>

  棚、ビン、その他の保管場所のラベル。`StorageUnit` から印刷されます。
</details>

<details>
  <summary>**kanbanCard**`pdf only`</summary>

  かんばんのビンの補充カード。`Kanban` から印刷されます。
</details>

どのタイプを印刷できるかは、元のドキュメントによって決まります。出荷を転記すると製品ラベルが、保管ユニットをスキャンすると保管ラベルが作成されます。この検索は `getDocumentTypesForSource` が行います。

## 印刷を設定する

### 1. プリンタールートを追加する

**プリンタールート**は、1 台の物理プリンターを表します。**設定 → 印刷 → プリンター**に移動し、**プリンターを追加**を選択します。

FieldType

<details>
  <summary>**name**required`text`</summary>

  プリンターの名前。例：「Zebra 2x1」。同じロケーション内で一意である必要があります。
</details>

<details>
  <summary>**format**required`"zpl" | "pdf"`</summary>

  「ZPL（感熱ラベル）」または「PDF（ドキュメント）」。
</details>

<details>
  <summary>**mediaSizeId**required`text`</summary>

  プリンターにセットされているラベルのサイズ。ZPL プリンターには感熱（ZPL 対応）のサイズだけが表示され、PDF プリンターにはすべてのサイズが表示されます。
</details>

<details>
  <summary>**printerUrl**required`url`</summary>

  レンダリングされたラベルを POST で受け取る HTTP エンドポイント。有効な URL である必要があります。
</details>

<details>
  <summary>**apiKey**`text`</summary>

  任意。配信ごとに `X-API-Key` ヘッダーとして送信され、暗号化して保存されます。
</details>

<details>
  <summary>**templateId**`text`</summary>

  任意。「組み込みを使用する場合は空欄」：空の値は、Alforse の組み込みレンダラーを使用します。
</details>

<details>
  <summary>**locationId**`text`</summary>

  任意。プリンターのロケーション。ない場合、ルートは全社に適用されます。
</details>

NOTE

Alforse がプリンターの raw ポートを開くことはありません。レンダリングしたバイト列を `printerUrl` への HTTP POST で送信して配信します。そのため、現場のプリンターには、印刷ゲートウェイやプリンター自身の HTTP インターフェースなど、Alforse が到達できる HTTP エンドポイントが必要です。送信先は、その会社で承認されたプリンターのオリジンでもある必要があり、Alforse はそれ以外には送信しません。

### 2. プリンターをテストする

すべてのルートには**テスト**アクションがあり、小さな ZPL ラベルを `printerUrl` に直接送信するため、使用する前にプリンターに到達できることを確認できます。テストが使えるのは、メディアサイズのある ZPL ルートだけで、成功すると `"Test label sent to printer"`（テストラベルをプリンターに送信しました）と表示されます。

### 3. プリンターをコンテキストに割り当てる

ルートはプリンターであり、**割り当て**がそれをいつ使うかを決めます。**設定 → 印刷 → 割り当て**を開くと、ロケーションごとにブロックがあります。その中で、各**コンテキスト**にプリンターを割り当てます（`packages/web/printing/src/assignments.ts` の `printerContexts`）。

FieldType

<details>
  <summary>**default**</summary>

  ロケーションのフォールバック。専用のプリンターがないコンテキストは、これを使います。
</details>

<details>
  <summary>**shipping**</summary>

  元のドキュメントのタイプが `Shipment` の場合。
</details>

<details>
  <summary>**receiving**</summary>

  元のドキュメントのタイプが `Receipt` の場合。
</details>

<details>
  <summary>**inventory**</summary>

  `StockTransfer` または `StorageUnit` の場合。
</details>

<details>
  <summary>**workCenter**</summary>

  作業区ごとに設定し、製造指図の工程から印刷するラベル用。割り当てのない作業区は、ロケーションのデフォルトを直接使います。
</details>

各コンテキストの行には**自動印刷**スイッチもあり、オンの場合、対応する業務イベントが、誰もクリックしなくても印刷されます。`getPrinterContextForSource` が元のドキュメントのコンテキストを見つけ、`resolveContextAssignment` がフォールバックを適用するため、割り当てのないコンテキストは、ロケーションのデフォルトのプリンターを使います。

HEADS UP

明示的な行のないコンテキストは、ロケーションのデフォルトの行でオフになっていても、自動印刷が**オン**になります。たとえば出荷などのステーションを静かにしておくには、デフォルトの行に頼らず、自動印刷をオフにした専用の行を用意してください。

## 自動印刷

対応する業務イベントの後、Alforse はロケーションとコンテキストに対するプリンターを見つけ、`autoPrint`（未設定の場合は**オン**として扱われる）を確認して、ジョブをキューに入れます。印刷の失敗が、それを引き起こした入荷、出荷、製造指図をブロックすることはありません。

| イベント | コンテキスト | 印刷されるもの |
| - | - | - |
| 入荷が転記された | receiving | 受け入れた追跡対象エンティティの製品ラベル。 |
| 出荷が転記された | shipping | 製品ラベルと、バッチ分割用の `Split` ラベル。 |
| 在庫移動の明細が分割された | inventory | `Split` ラベルと、元のバッチの `Entity` 再印刷。 |
| MES で製造指図の最初の工程が完了した | 作業区 | 製造指図の製品ラベル。 |

ステーションを静かにするには、そのロケーションのコンテキストの行で**自動印刷**をオフにします。

HEADS UP

同じ元のドキュメントに対する自動印刷は、**30 秒以内で重複が排除されます**。2 回目のイベントは、再試行不可のエラーで破棄されます。手動の印刷と再印刷は、重複排除されません。

## 手動で印刷する

関連する画面で**印刷**を選択するか、元のドキュメントを手動印刷ルート（`/x/print`）に送信します。リクエストを検証し、同じ種類のジョブをキューに入れます。

**印刷**の動作は、ロケーションによって異なります。

| ロケーションにプリンタールートがあるか | 動作 |
| - | - |
| ある | 解決されたデフォルトが選択された状態で、プリンターピッカーが開きます。確認するとジョブがキューに入ります。 |
| ない | **ダウンロード**モーダルが開き、ラベルを ZPL または PDF として保存できます。 |

## 印刷ジョブキュー

### ジョブのステータス

<details>
  <summary>**generating（生成中）**</summary>

  ジョブは存在し、内容が ZPL テキストまたは base64 の PDF としてレンダリングされています。
</details>

<details>
  <summary>**queued（キュー済み）**</summary>

  レンダリング済み。プリンターへの配信がキューに入っています。
</details>

<details>
  <summary>**printing（印刷中）**</summary>

  プリンターのエンドポイントに送信済み。配信が進行中です。
</details>

<details open>
  <summary>**completed（完了）**</summary>

  配信済み、または送信先のプリンターがないままレンダリング済み（ダウンロード専用のジョブ）。
</details>

<details>
  <summary>**failed（失敗）**</summary>

  レンダリングまたは配信に失敗した、または配信を確認できませんでした。`error` が理由を示し、`attempts` が試行回数を数えます。
</details>

各ジョブは `origin` を記録します。

| 起源 | 意味 |
| - | - |
| **auto** | 業務イベントの後に自動で印刷された。 |
| **manual** | 誰かが印刷を選択した。 |
| **reprint** | ジョブ一覧から再実行された。 |

ジョブは、`sourceDocument`、`sourceDocumentId`、読みやすい ID、`contentType`、送信先の `printerUrl` も保存します。

### 監視と再印刷

**設定 → 印刷 → 印刷ジョブ**を開きます。テーブルは、ステータス、説明、ソース、タイプ、起源、時刻とともにリアルタイムで更新されます。行を展開すると、プリンターの URL、試行回数、タイムスタンプ、エラーが確認できます。行からは次の操作ができます。

* 内容を**表示**：ZPL は Labelary でプレビューされ、PDF はインラインフレームで表示されます。
* **再印刷**：`origin: "reprint"` の新しいジョブが作成されます。
* **削除**。

NOTE

タイムアウトや結果を記録できなかったことにより、配信の結果を確認できない場合、ジョブは失敗とマークされ、**自動的に再送されることはありません**。ラベルがすでに印刷されている可能性があるためです。プリンターを確認し、必要な場合は**再印刷**してください。

## ラベルサイズ

メディアサイズは、固定のカタログ（`packages/web/utils/src/labels.ts`）から取得されます。`label2x1`、`label4x2`、メートル法の `label100x50mm` と `label50x25mm`、PDF 専用の `avery5163` です。感熱式プリンターで印刷できるのは ZPL の寸法を持つサイズだけなので、Avery のような PDF 専用のサイズは使えません。

サイズは 2 か所で設定されます。

* 各プリンタールートは、そのプリンターにセットされたラベルに合わせて、独自の `mediaSizeId` を固定します。
* 文書テンプレート画面で設定する、会社の**デフォルトの製品ラベルサイズ**（`companySettings.productLabelSize`）は、どのルートもサイズを設定していない場合に、対話型のラベルダウンロードルートで使用されます。

そのデフォルトの場所については[会社設定](https://docs.alforse.com/ja/docs/reference/company-settings.md)を、組み込みのラベルテンプレートをスタイルするカスタマイザーについては[ドキュメント](https://docs.alforse.com/ja/docs/reference/documents.md)を参照してください。

## トラブルシューティング

### ラベルが印刷されなかった

次の項目を順に確認してください。

1. ロケーションとコンテキストにプリンタールートが割り当てられており、その**自動印刷**スイッチがオンになっている。
2. ルートに到達可能な `printerUrl` がある。ない場合、ジョブはレンダリングされますが、配信できません。
3. ジョブが**設定 → 印刷 → 印刷ジョブ**で**失敗**になっていない。行を展開して `error` を読みます。

自動印刷のキュー投入時の失敗は、「Auto-print failed」（自動印刷に失敗しました）としてログに記録されるだけで、入荷や出荷の画面には表示されないため、確認する場所は印刷ジョブ一覧です。ジョブがまったくない場合は、プリンターが解決されず自動印刷もオフだったか、そのイベントは自動印刷の対象ではありません。自動印刷されるのは[自動印刷](#automatic-printing)の 4 つのイベントだけです。それ以外は、**印刷**または手動ルートを使ってください。

### エラーメッセージ

| メッセージ | 原因 | 対処 |
| - | - | - |
| 「Print jobs already exist for … …」（…の印刷ジョブはすでに存在します） | 同じ元のドキュメントの自動ジョブが 30 秒以内に作成されたため、この重複は破棄された。 | 別のコピーが必要なら**再印刷**を使う。再印刷は重複排除されない。 |
| 「Rendering failed: …」（レンダリングに失敗しました：…） | 内容を生成できなかった。多くの場合、ZPL ラベルが ZPL の寸法のないメディアサイズにルーティングされた、または PDF 専用のかんばんカードが ZPL 専用のプリンターに送られた。 | ルートのメディアサイズと形式を確認する。 |
| 「Printer delivery could not be confirmed. This job will not be sent again automatically.」（プリンターへの配信を確認できませんでした。このジョブは自動的には再送されません。） | エンドポイントが時間内に応答しなかった、または結果を記録できなかった。 | プリンターを確認する。何も印刷されていなければ、ジョブ一覧から再印刷する。 |
| 「Print job not found: …」/「The print job has no valid stored content.」（印刷ジョブが見つかりません／印刷ジョブに有効な保存済みコンテンツがありません） | 配信がジョブまたはその内容を読み込めなかった。後者は、レンダリングが完了しなかったことを意味する。 | ジョブ一覧でジョブのステータスとエラーを確認する。 |
| 「No printer is assigned to this print job; nothing was sent.」（この印刷ジョブにプリンターが割り当てられていません。何も送信されませんでした。） | プリンターのなかったジョブに対して再印刷が要求された。 | ロケーションとコンテキストにプリンターを割り当ててから、もう一度印刷する。 |
| 「Print failed (…)」（印刷に失敗しました（…）） | エンドポイントが HTTP エラーを返した。コードはメッセージに含まれる。通常は、プリンターがオフライン、`printerUrl` が間違っている、`apiKey` がない、または無効。 | ルートの**テスト**アクションで到達性を確認する。 |
| 「Test print is only supported for ZPL label printers with a media size configured.」（テスト印刷は、メディアサイズが設定された ZPL ラベルプリンターでのみサポートされます。） | PDF ルート、またはメディアサイズのない ZPL ルートで**テスト**を使用した。 | メディアサイズのある ZPL ルートだけをテストする。 |
| 「Cannot reprint a job with no content」/「Cannot reprint a job that is still generating」（内容のないジョブは再印刷できません／生成中のジョブは再印刷できません） | 再印刷は元のレンダリング済みの内容をコピーするが、このジョブはレンダリングされなかった。 | 元のジョブを解決するか、元のドキュメントからもう一度印刷する。 |

## 関連項目

**会社設定**

デフォルトの製品ラベルサイズと、その他の全社共通の印刷デフォルト。

[Open](https://docs.alforse.com/ja/docs/reference/company-settings.md)

**在庫とロケーション**

保管ユニットのラベルと、ほとんどの印刷ジョブが表す追跡対象エンティティ。

[Open](https://docs.alforse.com/ja/docs/reference/inventory.md)

**トレーサビリティ**

製品ラベルに記載されるシリアル番号とバッチ番号。

[Open](https://docs.alforse.com/ja/docs/reference/traceability.md)

**かんばん**

補充用のビンと、それ用に印刷される PDF カード。

[Open](https://docs.alforse.com/ja/docs/reference/kanban.md)


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