Профили 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.