受信トレイまたは送信トレイのファクスをダウンロードする

受信文書または送信文書を選ぶ

この互換性維持用エンドポイントは、ご利用のアカウントに属するファクス文書を取得します。有効な MultiTEL API アカウントを使用し、設定済みの認証情報と IP 制限に従って HTTPS でアクセスしてください。ファクスの送信や再送は行いません。

これらの値はパスに指定します。ルートは /v3/fax_file/{type}/{id} です。fax_download にパスセグメントを追加したものではありません。受信文書のハッシュは、数値のレコード ID でも送信ジョブ ID でもありません。該当するメールボックスの一覧から識別子をコピーしてください。この識別子は認証の代わりにはなりません。

受信ファクスをダウンロードする

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --dump-header fax-response.headers --output fax-response.bin \
  https://api.multitel.net/v3/fax_file/inbound/c20ad4d76fe97759aa27a0c99bff6710

例のハッシュは、架空の受信トレイのレコード 12 を表しています。ご自身のレコードに対応する値の取得元は fax_inbox です。既存の受信レコードをダウンロードすると、そのレコードは閲覧済みになります。この変更はファイルが利用可能かどうかを確認する前に行われるため、ファイルが利用できないというエラーになっても、viewed が true に設定されたままになることがあります。閲覧状態を変更したくない場合は、受信ファクスの存在を調べるだけの目的でこのエンドポイントを使用しないでください。

この処理では、保存済みの PDF を優先します。それがなければ保存済みの TIFF を使用し、変換ツールが利用可能な場合は PDF への変換を試みます。変換できない場合、または変換時に処理対象の例外が発生した場合は、代わりに TIFF を返します。PDF だと決めつけず、返された Content-Type を必ず確認してください。

送信ファクスをダウンロードする

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --dump-header fax-response.headers --output fax-response.bin \
  https://api.multitel.net/v3/fax_file/outbound/0123456789abcdef0123456789abcdef

使用する uuid の取得元は fax_outbox です。この互換性維持用のダウンロードでは、保存済みの PDF のバイナリデータ、TIFF のバイナリデータ、利用可能な PDF ファイル、TIFF ファイル、元のソースファイルの順に優先します。この優先順位は、現在の送信用処理である fax_download とは異なります。新規連携で send_fax を使用する場合は、その現在のダウンロードフローを job_id パラメーターとともに使用してください。

元のソースファイルは、PDF や TIFF ではなく application/octet-stream として返されることがあります。添付ファイル名には元の拡張子が残る場合があります。この互換性維持用の送信文書ダウンロードでは、受信トレイのレコードを閲覧済みにしたり、ジョブの状態を変更したり、送信を作成したりすることはありません。

バイトデータとエラーを分けて処理する

成功時には、Content-Type、添付ファイルとしての Content-Disposition、Content-Length の各ヘッダーとともに、文書の生のバイトデータが返されます。Base64 のデータを格納した JSON のエンベロープではありません。例のようにヘッダーとバイトデータを別々に保存し、応答の種類を確認してから、ファイルに適切な名前を付けたり処理したりしてください。元のファイルの拡張子が許可されていても、文書が有効であることや変換済みであることは保証されません。

API コード 400 は、必須のパスの値が指定されていないか、type が無効であることを意味します。API コード 404 は、そのアカウントに属するレコードまたはそのファイルが利用できないことを意味します。エラーには通常の JSON の status/response エンベロープが使用され、HTTP 200 が返されることもあります。エラー本文を文書として開かないように、応答の Content-Type と JSON の status.code を確認してください。

プライバシーとファイルの可用性

ファクスには機密情報が含まれる場合があります。ダウンロードしたファイルは、意図した受信者だけがアクセスできる場所に保存し、文書全体のバイトデータをログに含めないでください。メールボックスにレコードが存在しても、そのファイルを引き続き利用できるとは限りません。ファイルの保存期間は定められておらず、過去に保存されたすべての文書について互換性が保証されているわけでもありません。