リーダーでコンテンツを印刷する

リーダーの埋め込み型プリンターでコンテンツを印刷します。

Stripe Terminal を使用すると、レシート、チケット、その他の書類などのカスタムコンテンツをリーダーの埋め込み型プリンターで直接印刷できます。この機能は、白黒印刷が可能なサーマルプリンターを内蔵した Verifone V660p リーダーでのみ使用できます。

印刷コンテンツを生成する

実装は、画像ファイルとして印刷するコンテンツを生成する役割を担います。印刷でサポートされる形式は画像のみです。画像を取得したら、実装タイプのネイティブ画像表現に変換します (たとえば、サーバー駆動型の場合は画像ファイル、Android の場合はビットマップ)。

コンテンツのガイドライン

最良の結果を得るには、次の画像要件をお勧めします。

最大 384 ピクセル幅
白黒 (カラーなし)
文字または線の最も細い部分の幅が 2 ピクセル以上になるようにデザインし、印刷が明確で読みやすくなるようにします

メモ

リーダーを使用して印刷するために Stripe に送信するコンテンツに関しては、お客様が法的責任を負います。また、レシートが適用法に準拠していることを確認する必要があります。(i) 第三者の権利を侵害する、(ii) 適用法に違反する、または (iii) 好ましくない、攻撃的、欺瞞的、不正確、または有害な内容を含む素材を含むレシートを印刷することはできません。

コンテンツを印刷する

リーダーでコンテンツを印刷するには、print_contentエンドポイントを呼び出します。multipart/form-data 本文を PNG または JPEG 画像ファイルと一緒に送信します。アップロードするファイルは 100 KB を超えてはなりません。

メモ

このエンドポイントは、api.stripe.com ではなく files.stripe.com サブドメインに配置されます。

印刷結果を処理する

print_contentエンドポイントは、print コマンドがリーダーに正常に送信されると、更新済みの Readerオブジェクトで応答します。次の応答例を参照してください。

{
  "id": "tmr_FDOt2wlRZEdpd7",
  "object": "terminal.reader",
  "action": {
    "failure_code": null,
    "failure_message": null,
    "print_content": {
      "image": {
        "created_at": 1748971913,
        "filename": "image.png",
        "size": 15864,
        "type": "png"
      },
      "type": "image"
    },
    "status": "in_progress",
    "type": "print_content"
  },
  "device_sw_version": "",
  "device_type": "verifone_v660p",
  "ip_address": "0.0.0.0",
  "label": "Blue Rabbit",
  "last_seen_at": 1695166525506,
  "livemode": false,
  "location": "tml_FDOtHwxAAdIJOh",
  "metadata": {},
  "serial_number": "452-406-028",
  "status": "online"
}

action オブジェクトは、print_content アクションが in_progress であることを示します。print_content オブジェクトには、印刷中の画像に関する情報が含まれます。

エンドポイントは、検証エラー (ファイルが大きすぎる、サポートされていない形式など) に対して、次のような 400 ステータスコードと本文ですぐに応答します。

{
  "error": {
    "message": "The file you uploaded was too large. Please upload a file smaller than 100 KB",
    "param": "image",
    "request_log_url": "https://dashboard.stripe.com/...",
    "type": "invalid_request_error"
  }
}

Webhook イベント

When the print operation completes (either successfully or with an error), Stripe sends a request to your webhook endpoint.

Stripe は 2 つの Webhook イベントを送信して、print コマンドの結果をバックエンドに通知します。

terminal.reader.action_succeeded: print コマンドが成功しました。
terminal.reader.action_failed: 印刷コマンドが失敗しました。たとえば、印刷中にプリンターの用紙がなくなったり、詰まったりしました。

Webhook ペイロードにはイベントオブジェクトが含まれます。ここで、data.objectは更新された Readerオブジェクトです。

`terminal.reader.action_succeeded` イベント

terminal.reader.action_succeeded イベントの場合、data オブジェクトは次のようになります。

{
  "object": {
    "id": "tmr_FDOt2wlRZEdpd7",
    "object": "terminal.reader",
    "action": {
      "failure_code": null,
      "failure_message": null,
      "print_content": {
        "image": {
          "created_at": 1748971913,
          "filename": "image.png",
          "size": 15864,
          "type": "png"
        },
        "type": "image"
      },
      "status": "succeeded",
      "type": "print_content"
    },
    "device_deploy_group": "",
    "device_sw_version": "2.34.0.0",
    "device_type": "verifone_v660p",
    "ip_address": "10.244.38.93",
    "label": "test",
    "livemode": false,
    "location": "tml_GEPlmAJnZUoXI6",
    "metadata": {},
    "serial_number": "452-406-028",
    "software": null,
    "status": "online"
  },
  "previous_attributes": null
}

action.statusは succeeded に設定されます。この場合、action.failure_code と action.failure_message はどちらも null です。

`terminal.reader.action_failed` イベント

terminal.reader.action_failed イベントの場合、data オブジェクトは次のようになります。

{
  "object": {
    "id": "tmr_FDOt2wlRZEdpd7",
    "object": "terminal.reader",
    "action": {
      "failure_code": "reason_out_of_paper",
      "failure_message": "The printer is out of paper.",
      "print_content": {
        "image": {
          "created_at": 1748971913,
          "filename": "image.png",
          "size": 15864,
          "type": "png"
        },
        "type": "image"
      },
      "status": "failed",
      "type": "print_content"
    },
    "device_deploy_group": "",
    "device_sw_version": "2.34.0.0",
    "device_type": "verifone_v660p",
    "ip_address": "10.244.35.107",
    "label": "test",
    "livemode": false,
    "location": "tml_GEPlmAJnZUoXI6",
    "metadata": {},
    "serial_number": "452-406-028",
    "software": null,
    "status": "online"
  },
  "previous_attributes": null
}

action.statusは、failed に設定されます。failure_code フィールドには失敗の理由が含まれ、failure_message フィールドには失敗を説明する人間が読めるメッセージが含まれています。

failure_code フィールドに指定できる値は次のとおりです。

エラーの説明	失敗コード
プリンターは、現在印刷中です。	`printer_busy`
プリンターのロール紙が詰まっています。	`printer_paperjam`
プリンターの用紙が切れています。	`printer_out_of_paper`
プリンターのカバーまたはヘッドアセンブリが開いている。	`printer_cover_open`
一般的な印刷の失敗 (その他のエラーはすべてキャッチ)。	`printer_failure`

リーダーが印刷をサポートしていない場合、failure_code は printer_not_supported に設定され、print_contentエンドポイントが呼び出された直後にエラーが返されます。terminal.reader.action_failed イベントは送信されません。