この動画について

この動画のレスポンスは、実際の API のレスポンスを短くしたものです。API キーとファイル検証には有料アカウントが必要です。

動画の文字起こし

1. 00:00ファイルをアップロードする

   CSV を /verify/file にアップロードし、完了したら Webhook で知らせてもらいます。Bulk は 50 アドレスまでです。それより大きいものは、ファイル全体を multipart フォームデータとして送ります。CSV、TXT、XLSX を受け付けます。email_column で、読み取る列を指定します。省略すると、自動で検出されます。これがテストファイルです。4 行と、結果にそのまま残したい source 列があります。アップロードは、チェックの完了を待ちません。タスク ID と pending のステータスを返します。どの列を読んだか、行数と一意のアドレス数がいくつあったかも返します。API キーと同じく、ファイルジョブは有料アカウント向けです。

2. 00:43ジョブを追跡する

   状況を確認するには、同じパスにタスク ID を付けて GET します。ヘッダーは同じで、ボディはありません。すぐに問い合わせたところ、この小さなファイルはすでに merging でした。実行中のステータスは、preparing、pending、processing、merging のように進みます。completed、completed with warning、failed、cancelled のどれかが出たら、問い合わせをやめます。これが完了したジョブです。件数は、ステータスごとにファイルを分けています。無効が 1、役割が 1、Catch-all が 1、使い捨てが 1 です。credits_used は 1 で、cache_hit_not_charged は 3 です。3 行は再チェックでした。それらのアドレスは、直近 24 時間以内にこのアカウントでチェック済みで、24 時間以内の再チェックには課金されません。リンクは 2 つ付いてきます。download_url は安定した API のパスなので、保存するのはこちらです。direct_download_url は署名付きのストレージリンクで、表示された有効期限を過ぎると使えなくなります。

3. 01:35結果を取得する

   results を呼び出して、出力をファイルに保存します。フィルターがなければ、API は全件の結果ファイルにリダイレクトし、curl の -L がそのリダイレクトをたどります。自分の列が、そのまま最初に来ます。そのあとに ev_ 列が、すべての行に続きます。status、score、reason などです。削除すべき行だけが欲しいなら、フィルターを追加します。フィルターは OR で組み合わされるので、これは無効または使い捨てを求めています。フィルターがあると、CSV はその場で作られて返されます。返ってくるのは 2 行、削除すべき行です。

4. 02:04Webhook を使う

   ポーリングでも動きますが、長いジョブではリクエストが多くなります。Webhook なら、向きが逆になります。BillionVerify は、ファイルジョブが完了または失敗したときに、自社のサーバーを呼び出します。登録は、/webhooks への POST で行います。HTTPS の URL と、受け取りたいイベントを指定します。イベントは 2 つ、file.completed と file.failed です。そのレスポンスには署名用のシークレットが含まれ、見られるのはこのときだけです。すぐに保存してください。各配信の確認に必要です。各配信は JSON の POST で、ヘッダーは 3 つ、イベント、タイムスタンプ、署名です。ボディには、イベントと時刻が入っています。data には、ジョブ ID、件数、使用したクレジット、ダウンロードリンクが入っています。

5. 02:44署名を確認する

   配信に基づいて動作する前に、署名を確認してください。タイムスタンプのヘッダー、ドット、生のボディをつなげます。それに対して、シークレットで HMAC-SHA256 を計算し、署名のヘッダーと比較します。ボディは、届いたとおりにハッシュします。パースして再エンコードした JSON は一致しません。また、古いタイムスタンプは拒否して、古いリクエストが再送されないようにします。流れ全体は短いものです。アップロードし、タスク ID を保存し、Webhook を待ち、安定したリンクから結果を取得します。

6. 03:11次のステップ

   ステータスの値、フィルター、Webhook のすべてのフィールドは、billionverify.com/docs/api-reference の API リファレンスにあります。アカウントを使う日は毎日 20 クレジットが無料で、月最大 600 クレジットまで利用できます。クレジットカードは不要です。billionverify.com から始めましょう。