テプラ WebAPI SDK（テプラクリエイター）でハマったことを全部書く

社内の在庫管理 Web アプリからキングジムのテプラ SR-R7900P に QR ラベルや連番ラベルを印刷する仕組みを作りました。公式の「テプラクリエイター WebAPI SDK」を使ったのですが、リファレンスだけでは分からない挙動（特にカット制御）でだいぶハマったので、実機で確かめた仕様とハマりどころをまとめます。

前提: WebAPI SDK の構成

テプラクリエイター（SPC10 の後継の Windows アプリ）のインストーラには「WebAPI 用通信モジュール」が同梱されていて、これを入れると localhost:29108 に REST サーバが立ちます。Web アプリはこう繋がります:

ブラウザ（公式 JS SDK: tepraprint.js）
  → WebAPI 通信モジュール（http://localhost:29108・REST）
  → テプラ プリンタドライバ（Windows）
  → テプラ本体（USB / LAN）

印刷を実行できるのは通信モジュールが動いている PC のブラウザだけ（localhost 限定）。サーバー側からは印刷できないので、うちは「中継PC」を 1 台置く構成にしました。
JS SDK は top-level const でグローバルを定義する素の <script> です。モジュール化されていないので、そのまま使うなら window への橋渡しを足すと扱いやすいです。

印刷方式は 2 系統ある

doPrint(printParameter, printFile) の printFile に何を渡すかで方式が変わります。

方式	入力	特徴
画像方式	`{ imageFile }`	1 画像 = 1 ラベル = 1 ジョブ。レイアウトは canvas で自由に作れる
テンプレ流し込み	`{ templateFile, csvFile }`	テプラクリエイターで作った .lw1 テンプレの枠に CSV を流し込む。1 ジョブで複数ラベル

うちは「ラベルの見た目をアプリ側で完全に制御したい」ので画像方式に統一しました。テンプレ（.lw1）はブラウザから File として渡せるので中継PCへの事前配置は不要ですが、テンプレ自体の作成にはテプラクリエイター（Windows アプリ）が必要です。

この選択がのちのカット制御のハマりに直結します（後述）。

画像方式の勘所

解像度は機器の整数倍で

SR-R7900P は 360dpi（約 14.2 ドット/mm）。これより低い解像度で画像を作るとドライバ側で拡大され、感熱印字は白黒 2 値なのでアンチエイリアスの中間色が潰れて文字がガタつきます。うちは 720dpi 相当（1mm ≈ 28.3px）で作っています。

高さ=テープ幅、幅=可変

画像の高さをテープ幅に対応させ、printParameter.stretchImage = true で拡縮させると、「高さ固定・長さは内容次第」というテプラらしいラベルになります。

背景は必ず白で塗る

**透明 PNG のまま渡すと黒く印字される機種があります。**canvas なら最初に白で fillRect してから描き始めます。

QR コードはセル=整数ピクセルで自前描画

qrcode ライブラリの toCanvas は指定サイズに合わせて拡縮するため、セル（モジュール）幅が端数になり、印字したときにモジュールの太さがばらつきます。QR のモジュール配列を取得して 1 セル = 整数ピクセルで fillRect する方が、どの倍率でも角のきれいな QR になります。

テープ ID は必ず指定する

printParameter.tape（TepraPrintTapeID）を指定しないと 18mm 扱いになり、実際に入っているテープと違うと確認メッセージが出ます。

そして TepraPrintTapeID を眺めると、通常幅（4〜36mm、50/100mm）のほかに特殊カートリッジの専用 ID が並んでいます:

_24MMCABLE / _36MMCABLE — ケーブル表示ラベル（セルフラミネート。SV24KN 等）
_24MMINDEX — インデックスラベル
_36MMLABEL1 — カットラベル（ダイカット）
_100MMLABEL — 宛名ラベル
DC_TURNTELL01〜04 — PANDUIT 回転ラベル（Ø3.0〜9.9）
DC_SELFLAMI01〜04 — PANDUIT セルフラミネート（Ø2.0〜12.2）

同じ 24mm 幅でも、ケーブル表示ラベルに通常テープの ID で送ると「テープが違う」確認が出ます。逆に言うと、専用 ID を送れば特殊カートリッジも WebAPI から普通に印刷できます。

ちなみにケーブル表示ラベル SV24KN は 24mm 幅のうち白い印字部が 8mmで、残り 16mm は巻き付け用の透明部。画像方式なら「8mm の帯の中にだけ描く」画像を作れば対応できます。

【本題】カット制御が直感と違う

一番ハマったのがここです。連番ラベル（001, 002, …）を 1 本のテープに連続印刷して、ラベル間はハーフカット・最後だけフルカットにしたかったのですが、なかなかそうならない。

カット関連のパラメータは 3 つ:

printParameter.tapeCut     // TepraPrintTapeCut: EACH_LABEL / AFTER_JOB / NOT_CUT
printParameter.halfCut     // bool
printParameter.halfCutContinuous  // bool

画像方式は 1 ラベル = 1 ジョブなので「ジョブ内のラベル間」という概念がありません。SR-R7900P での実測（全パターン検証済み）はこうなりました:

指定	実機挙動
`NOT_CUT`（halfCut 問わず）	境界に何も入らない。全部つながって出てくる
`AFTER_JOB`（halfCut 問わず）	ジョブ末尾でフルカット。`halfCut: true` を立てても無視される
`EACH_LABEL` + `halfCut: true`	これもフルカット。`halfCut` は効かない

結論①: 単一ラベルのジョブでハーフカットは撃てない

「tapeCut でカットの場所、halfCut でカットの種類（ハーフ/フル）を決める」という素直なモデルではなく、単一ラベルのジョブで選べるのはフルカットするか・しないかだけでした。

結論②: テンプレ流し込みでも（AFTER_JOB + halfCut では）ダメだった

「ジョブ内に複数ラベルがあれば halfCut が効くはず」と考えて、流し込み枠 1 つの .lw1 テンプレ + CSV（{ templateFile, csvFile }）で連番 12 枚を 1 ジョブにまとめて実験しました。結果:

CSV の流し込み印字そのものは成功（ブラウザで生成した CSV がそのまま差し込まれる）
しかし halfCut: true + halfCutContinuous: false + tapeCut: AFTER_JOB では、レコード間に何も入らず 1 本のつながったテープで出力

つまりこの組み合わせでは、流し込みジョブ内のラベル間にもハーフカットは入りませんでした。未検証で残っているのはジョブ内での tapeCut: EACH_LABEL + halfCut: true（ドライバの「ラベル毎にハーフカット」の本命候補）ですが、うちはここで実験を打ち切り、「1 枚ずつフルカット」運用で確定にしました。テープ数 cm のロスと引き換えに、canvas 自由レイアウトの画像方式に一本化できるメリットのほうが大きかったです。

もし EACH_LABEL + halfCut を流し込みジョブで試した方がいたら、結果をコメントで教えてください。

確認ダイアログはジョブごとに出る（既定値に注意）

連続印刷したら1 ラベルごとに確認ダイアログが出て地獄になりました。原因は既定値:

パラメータ	既定	内容
`displayTapeWidth`	true	テープ幅確認メッセージ。ジョブごとに出る
`displayPrintSetting`	true	印刷設定確認メッセージ
`displayError`	true	エラー表示（これは true のままが無難）
`priorityPrintSetting`	false	true で印刷パラメータをカートリッジ設定より優先

連続印刷では displayTapeWidth を最初の 1 枚だけ true（テープ間違い検知用）、2 枚目以降は false にすると快適です。

ネットワークプリンタのオンライン検知

テプラを LAN 接続にすると、電源断や LAN 切断でも Windows のスプーラがジョブを受け付けてしまうため、「印刷したのに何も出ない」という見え方になります。SDK に checkPrinterOnline があるので、印刷前に呼んでオフラインなら即エラーにするのがおすすめです。

その他、存在を知っておくと便利な API

doTapeFeed() / doTapeCut() — テープ送り / テープ送り+フルカット。ハーフカットを単発で撃つ API はありません
getImportFrame(templateFile) — テンプレの流し込み枠一覧
getMargin(tape, templateFile) — 余白の取得
fetchPrinterStatus() — 装着中のテープ幅・種類の検出、ハーフカット可否等の TapeOption
ジョブ制御 — progressOfPrint / cancelPrint / pauseOfPrint / resumeOfPrint

まとめ

WebAPI SDK は「localhost の通信モジュールへの REST ラッパー」。素の JS なのでモダンな構成に組み込むなら一工夫
画像方式は自由度最強だが 1 ラベル = 1 ジョブになり、ハーフカットが撃てない（フルカット or カットなしの二択）
ハーフカットが要るならテンプレ流し込み方式で 1 ジョブに複数ラベルをまとめる
displayTapeWidth の既定 true に注意（連続印刷でダイアログ地獄）
テープ ID は必ず指定。特殊カートリッジ（ケーブル表示・カットラベル・PANDUIT）も専用 ID で印刷できる
透明 PNG は黒く出る機種がある。背景は白で塗る

同じところでハマる人が減りますように。