FAXを送信する

送信前の確認

発信者番号として表示する権限のある番号を使用し、FAXの受信を予定している相手に送信してください。このリクエストにより実際の送信が作成され、料金が発生する可能性があります。ページ検出の結果をできるだけ安定させるには、あらかじめ用意したPDFまたはTIFFを使用してください。キューへの登録を示す応答は受付の確認であり、相手への到達を確認するものではありません。

有効化されたMultiTEL APIアカウントを使用してください。パスワード方式のアカウントではHTTP Basic認証の認証情報を、トークン方式のアカウントではBearerトークンを送信してください。アカウントの権限とIP制限は引き続き適用されます。内部ワーカーの認証情報は使用しないでください。

文書をアップロードする

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --form-string from_number=+12125550123 \
  --form-string to_number=+12125550124 \
  --form fax_file=@./document.pdf \
  https://api.multitel.net/v3/send_fax

JSON形式でも受け付けます。指定するのは Content-Type: application/json、同じ番号フィールドと任意のwebhook_url、さらに file_name と file_b64 です。file_b64には、data:という接頭辞を付けず、厳密なBase64形式でエンコードした文書のバイト列を格納します。有効なマルチパートのfax_fileがある場合は、そちらが優先されます。これはファイルのURLからファイルを取得するAPIではありません。

文書と送信リクエストの制限

アプリケーションが受け付ける文書は、デコード後のサイズが最大15,728,640バイト（15 MiB）で、拡張子がpdf、tif、tiff、jpg、jpeg、png、doc、docx、またはtxtのものです。許可された拡張子であっても、サービスがページ数を数えたりページを変換したりできるとは限りません。インフラ側のリクエスト上限はこれより低い場合があり、Base64を使用するとリクエストのサイズが増加します。

現在のアプリケーションでは、アカウントごとに、同じ送信先に対してキュー待機中または送信中のジョブは一件まで、直近一時間の同じ送信先への送信リクエストは五件まで、直近一時間の送信リクエスト全体は50件まで許可されます。レート制限の応答ではAPIコード429が使用されます。再試行する前に時間を置いてください。制限を回避しようとしないでください。

ジョブIDを保存する

HTTPの結果とJSONのstatus.codeの両方を確認してください。JSONで失敗を示す応答でも、HTTP 200で返される場合があります。成功したJSON応答にはstatusとresponseが含まれます。例では架空のデータを使用しています。

{
  "status": {
    "code": 200,
    "msg": "Fax queued"
  },
  "response": {
    "job_id": "0123456789abcdef0123456789abcdef"
  }
}

定期的に照会する対象は fax_status です。照会にはresponse.job_idを使用してください。送信リクエストへの応答が失われた場合は、再送信する前にポータルの送信トレイを確認してください。リクエストを繰り返すと、別々の送信が作成される可能性があります。このハンドラーでは、クライアント側で指定できる冪等性パラメーターは公開されていません。

エラーと残高確認

APIコードには、項目の不足、無効なコールバックURL、文書の受付拒否、またはページ検出の失敗を示す400、認証情報の欠如を示す401、FAXの見積料金とキュー待機中・送信中のジョブの見積料金の合計がアカウントの利用可能残高を超えたことを示す402、レート制限を示す429、送信準備処理の失敗を示す500があります。具体的な理由はstatus.msgを確認してください。

キューには送信前に見積料金が記録されます。受付、残高確認、またはこの見積もりを、課金の完了を確認するものと解釈しないでください。最終的な課金とコールバックの詳細については、引き続き検証が必要です。