關於本影片

本影片中的回應是真實的 API 回應，已做縮短。API 金鑰和文件驗證需要付費帳號。

影片文字稿

1. 00:00上傳文件

   把 CSV 上傳到 /verify/file，然後讓 webhook 在任務完成時通知你。Bulk 最多只能處理 50 個地址。更大的名單，就把整個文件作為 multipart 表單資料傳送。接受 CSV、TXT 和 XLSX。email_column 指定要讀取的欄。省略它，系統會自動識別。這是測試文件。四行，外加一個我們想在結果裡保留的 source 欄。上傳不會等待檢查完成。它會回傳一個任務 ID 和 pending 狀態。它還會告訴你讀取了哪一欄，以及找到多少行和多少個唯一地址。和 API 金鑰本身一樣，文件任務只對付費帳號開放。

2. 00:43追蹤任務

   要查看進度，對同一路徑加上任務 ID 傳送 GET。請求標頭相同，沒有請求本文。剛一詢問，這個小文件已經在合併了。執行期間，狀態會依次經過 preparing、pending、processing 和 merging 這樣的步驟。看到 completed、completed with warning、failed 或 cancelled 就不用再詢問了。這是已完成的任務。計數按狀態拆分文件：一個無效、一個角色、一個 Catch-all 和一個一次性。credits_used 是 1，cache_hit_not_charged 是 3。三行是複查。這些地址在過去 24 小時內已經在這個帳號上檢查過，24 小時內的複查不收費。隨結果附帶兩個連結。download_url 是穩定的 API 路徑，所以應該儲存這個。direct_download_url 是帶簽名的儲存連結，到所示的過期時間就會失效。

3. 01:35獲取結果

   呼叫 results 並把輸出儲存到文件。不帶篩選時，API 會重新導向到完整的結果文件，-L 參數會跟隨這次重新導向。你自己的欄位在最前面，保持不變。然後每一行後面跟著 ev_ 欄位，比如 status、score 和 reason。只需要要移除的行？加上篩選。多個篩選之間是 OR 關係，所以這裡請求的是無效或一次性。帶篩選時，CSV 會直接生成並回傳。回傳兩行，也就是要移除的那兩行。

4. 02:04使用 webhook

   輪詢可以用，但長任務意味著大量請求。webhook 把方向反過來：文件任務完成或失敗時，BillionVerify 會呼叫你的伺服器。用 POST 向 /webhooks 註冊一個。給它一個 HTTPS 網址和你想要的事件。有兩個：file.completed 和 file.failed。回應裡帶著一個簽名金鑰，而且只會顯示這一次。立刻儲存好。你需要用它來檢查每一次推送。每次推送都是一個 JSON POST，帶三個請求標頭：事件、時間戳和簽名。請求本文寫明事件和時間。它的 data 裡有任務 ID、計數、已用積分和下載連結。

5. 02:44檢查簽名

   在處理推送之前先檢查簽名。把時間戳請求標頭、一個點和原始請求本文拼在一起。用你的金鑰對它執行 HMAC-SHA256，再和簽名請求標頭比較。要對收到時的原始請求本文做雜湊。解析後再重新編碼的 JSON 是對不上的。還要拒絕過期的時間戳，這樣舊請求就無法被重放。所以整個流程很短：上傳，儲存任務 ID，等待 webhook，然後從穩定連結獲取結果。

6. 03:11下一步

   狀態值、篩選條件和每個 webhook 欄位都在 API 參考裡，地址是 billionverify.com/docs/api-reference。每天使用帳號可獲得 20 個免費積分，每月最多 600 個，無需信用卡。造訪 billionverify.com 開始使用。