Профили TikTok через API — расчёт, партия и экспорт

Интеграция состоит из отдельных запросов расчёта, запуска и чтения результата. Сохраняйте идентификатор партии у себя сразу после ответа 202, чтобы продолжить наблюдение после перезапуска вашего приложения.

Авторизация и исходный список

Создайте токен в кабинете и передавайте Authorization: Bearer sk_live_…. Для профильного потока нужны metadata:read и analyze:write. Подготовьте JSON с urls и mode="profile". Первую интеграцию проверьте на одной-двух собственных целях. Описание маршрутов находится в справочнике API.

Сначала получите расчёт

POST /api/v1/profiles/quote возвращает free, paid, reused, maximum_charge и tariff_version. Передайте те же urls вместе с одобренным maximum_charge и полученной версией тарифа в POST /api/v1/profile-batches. Расчёт сам по себе не запускает сбор. Изменившийся бесплатный остаток может потребовать нового подтверждения стоимости.

Сохраните ключ повтора

При запуске отправьте Idempotency-Key, например profile-import-2026-11-06-001. При сетевом обрыве повторите запрос с тем же телом и ключом. Сервер вернёт прежнюю партию. Другой список или другая одобренная стоимость требуют нового ключа. Конфликт ключа возвращается как ошибка 409.

Наблюдайте и выгружайте

Читайте GET /api/v1/profile-batches/{id} до конечного состояния, делая паузу между запросами. В rows используйте after и limit для последовательного чтения. После завершения доступен export?format=json или export?format=csv. POST /api/v1/profile-batches/{id}/cancel отменяет оставшуюся работу, сохраняя доставленные строки.

Обрабатывайте ошибки по уровню

401 требует входа, 402 — доступного лимита или кредитов, 409 — проверки ключа или расчёта, 422 — исправления входа, 429 — ожидания перед повтором. Внутри принятой партии смотрите status и error_code каждой строки. Итоговое списание связано с успешно доставленными карточками. Для проверки экспорта человеком пригодится руководство CSV.

Читайте также