Об этом видео

Ответы в этом видео — настоящие ответы API, сокращённые. API-ключи и проверка файлов требуют платного аккаунта.

Расшифровка видео

1. 00:00Загружаем файл

   Загрузите CSV в /verify/file, а затем пусть webhook сообщит, когда всё готово. Bulk ограничен 50 адресами. Для всего, что больше, отправьте весь файл как multipart form data. Принимаются CSV, TXT и XLSX. email_column называет столбец для чтения. Если его не указать, он определится сам. Вот тестовый файл. Четыре строки и столбец source, который мы хотим сохранить в результатах. Загрузка не ждёт проверок. Она отвечает ID задачи и статусом pending. Также сообщает, какой столбец прочитала, сколько нашла строк и уникальных адресов. Как и сам API-ключ, файловые задачи доступны платным аккаунтам.

2. 00:43Отслеживаем задачу

   Чтобы проверить ход, сделайте GET на тот же путь с добавленным ID задачи. Тот же заголовок, без тела. При запросе сразу этот небольшой файл уже был в состоянии merging. Пока задача идёт, статус проходит этапы вроде preparing, pending, processing и merging. Прекратите опрос, когда увидите completed, completed with warning, failed или cancelled. Вот завершённая задача. Счётчики делят файл по статусам: один невалидный, один ролевой, один catch-all и один одноразовый. credits_used равно одному, а cache_hit_not_charged равно трём. Три строки были перепроверками. Эти адреса уже проверяли в этом аккаунте за последние 24 часа, а перепроверка в течение 24 часов не тарифицируется. В ответе две ссылки. download_url — стабильный путь API, его и нужно сохранить. direct_download_url — подписанная ссылка на хранилище, и она перестаёт работать в указанное время истечения.

3. 01:35Получаем результаты

   Вызовите results и сохраните вывод в файл. Без фильтров API перенаправляет на полный файл результатов, а dash 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.