API HTTP

Xác thực, khám phá công cụ và xác nhận thay đổi qua API HTTP hiện có.

Gửi yêu cầu API sản phẩm đến địa chỉ gốc Influence đáng tin cậy, như https://influence.so. Miền tài liệu không nhận yêu cầu API sản phẩm. Dùng đúng các đường dẫn bên dưới, không kèm tham số truy vấn.

Tạo khóa API có phạm vi quyền cụ thể

Trong Cài đặt Influence, mở Ứng dụng và tự động hóa → Khóa API. Chọn các quyền cần thiết và thời điểm hết hạn. Lưu khóa chỉ hiển thị 1 lần trong kho bí mật dưới tên PUBLISH_API_TOKEN. Gửi khóa trong Authorization: Bearer …; không đưa vào URL, nội dung yêu cầu hay trò chuyện. Thu hồi khi không còn cần.

Khám phá công cụ và đọc tài khoản

Đặt PUBLISH_API_URL thành địa chỉ gốc đáng tin cậy. Các ví dụ này giả định tiến trình đã có PUBLISH_API_TOKEN. accountList cần integrations:read; làm theo các trường phân trang để lấy các trang tiếp theo.

export PUBLISH_API_URL="https://influence.so"
curl "$PUBLISH_API_URL/api/v1/tools" \
  -H "Authorization: Bearer $PUBLISH_API_TOKEN"

curl "$PUBLISH_API_URL/api/v1/tools/accountList/call" \
  -H "Authorization: Bearer $PUBLISH_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"input":{}}'

Đường dẫn yêu cầu

Phương thức	Đường dẫn	Mục đích
`GET`	`/api/v1/tools`	Liệt kê công cụ khả dụng cho thông tin xác thực này.
`POST`	`/api/v1/tools/{tool}/call`	Gọi công cụ không cần xác nhận, bao gồm tiếp tục lần tải lên đã được cấp quyền.
`POST`	`/api/v1/tools/{tool}/prepare`	Chuẩn bị chính xác thao tác ghi mà chưa thực hiện.
`POST`	`/api/v1/tools/{tool}/confirm`	Xác nhận thao tác ghi đã chuẩn bị.
`POST`	`/api/v1/media/import`	Xác nhận lần tải ảnh nhị phân nhỏ đã chuẩn bị.

Yêu cầu JSON cho công cụ dùng Content-Type: application/json và phần nội dung chỉ chứa input: {"input":{…}}. Lấy lược đồ đầu vào của từng công cụ từ danh mục công cụ hiện tại.

Chuẩn bị và xác nhận hành động

Dùng trường confirmation trong danh mục: thao tác đọc thường không cần xác nhận, nhưng làm mới Thông tin phân tích cần xác nhận dù là thao tác đọc. Tra cứu phần tải lên, hoàn tất và hủy tiếp tục lần tải lên đã được cấp quyền qua /call.

Gửi chính xác đầu vào nghiệp vụ đến /prepare. Phản hồi thành công có status: "confirmation_required", confirmationCapability, expiresAt, inputDigest và summary tùy chọn.
Trước khi hết hạn, gửi cùng đầu vào đến /confirm. Đặt giá trị xác nhận được trả về trong X-Publish-Confirmation và khóa mới do bên gọi tạo trong Idempotency-Key.
Giữ đầu vào, giá trị xác nhận và khóa cùng nhau. Sau lần xác nhận bị gián đoạn hoặc chưa rõ kết quả, dùng lại cả 3 cho cùng yêu cầu đó. Đừng chuẩn bị bản thay thế để khôi phục kết quả chưa rõ.

Khóa chống lặp chứa 16–200 ký tự thuộc A–Z, a–z, 0–9, ., _, : và -. Các giá trị xác nhận là bí mật cần được coi là giá trị nguyên khối. Khóa gửi đến /call hoặc /prepare không giữ chỗ cho thao tác ghi đã xác nhận.

Xác nhận ở lớp truyền tải khác với phê duyệt đăng. Với việc đăng hoặc đổi lịch, trình bày toàn bộ yêu cầu xem lại hiện tại: tài khoản, văn bản, cài đặt, bản xem trước hoặc liên kết ảnh và video thực tế, thời gian lên lịch và múi giờ. Ứng dụng khách có thể báo lời phê duyệt mới, rõ ràng của con người bằng approval: "approved" cho yêu cầu xem lại bài đăng văn bản, ảnh và video trên mạng xã hội đủ điều kiện; không được tự đặt sự đồng ý hay coi bước chuẩn bị là phê duyệt. Influence ghi nhận đây là lời phê duyệt do ứng dụng khách báo lại. Thẻ nhúng được hỗ trợ hoặc bước xem lại khi đã đăng nhập ghi nhận hành động riêng của con người.

TikTok Direct chấp nhận lựa chọn và sự đồng ý rõ ràng trong trò chuyện qua quy trình xem lại. Lưu đầy đủ lựa chọn bằng campaignReview, rồi nhận lời phê duyệt mới cho yêu cầu xem lại đã cập nhật trước khi thực hiện. Thẻ xem lại là tùy chọn. Lên lịch API/CLI thông thường không dùng hạn mức lên lịch bằng AI; hạn mức riêng cho MCP và Influence IQ áp dụng theo các quy trình đó, kể cả khi yêu cầu xem lại AI đã lưu được phê duyệt sau này trong Influence. Các yêu cầu khác của gói và nhà cung cấp vẫn áp dụng. Đọc biên nhận đã lưu trước khi hành động tiếp; needs_review cần được đối chiếu làm rõ, không phải gửi thêm lần nữa.

Xử lý lỗi và kết quả chưa chắc chắn

Kiểm tra cả trạng thái HTTP và nội dung phản hồi. Công cụ thành công trả về {"ok":true,"toolName":"…","output":{…}}. Lỗi công cụ trả về {"ok":false,"toolName":"…","error":{"code":"…","message":"…","retryable":false}} và có thể đi kèm HTTP 200. Lỗi truyền tải dùng {"error":{"code":"…","message":"…","retryable":false}} mà không có ok hoặc toolName.

401 nghĩa là cần xác thực; kiểm tra hết hạn hoặc thu hồi. Thiếu quyền cần được cấp quyền phù hợp, không phải gửi yêu cầu lặp lại. 503 có thể nghĩa là dịch vụ không khả dụng hoặc yêu cầu lên lịch khác đang cập nhật không gian làm việc. Dùng mã lỗi và hướng dẫn thử lại được trả về; đừng tự động thực hiện lại hành động đăng. Hết thời gian chờ không chứng minh thao tác ghi thất bại: giữ dữ liệu xác nhận và đọc trạng thái hiện tại trước khi gửi lại. Được chấp nhận, đã lên lịch và đã đăng là những kết quả khác nhau.

Tải tệp đa phương tiện lên

Ưu tiên uploadMedia của SDK hoặc media:upload của CLI cho tệp cục bộ. Chúng dùng cùng công cụ tải lên multipart và giữ clientKey ổn định để thử lại. Chỉ kết quả đã sẵn sàng có assetId mới có thể được đính kèm. Với liên kết HTTPS được phép dùng, dùng mediaImport với url và name tùy chọn. Tham chiếu tệp thực của nền tảng chủ dùng đối tượng file riêng; URL công khai không cần mã tệp nền tảng chủ tự đặt. Đường dẫn tệp cục bộ không phải URL tải xuống. Xem giới hạn tệp đa phương tiện: nhập video qua HTTPS có giới hạn 250 MiB, ngay cả khi MP4 đã sẵn sàng lớn hơn được phép tải trực tiếp lên.

POST /api/v1/media/import hỗ trợ cách truyền ảnh nhỏ hiện có: chuẩn bị mediaImport với bộ mô tả tải lên chính xác, rồi gửi cùng các byte đó dưới dạng application/octet-stream. Kèm X-Publish-Confirmation, Idempotency-Key và X-Publish-Upload chứa bộ mô tả JSON đã mã hóa URI. Các byte phải khớp kích thước và SHA-256 trong bộ mô tả. Cách truyền này có giới hạn 3 MiB; dùng trình hỗ trợ tải lên cho tệp lớn hơn được hỗ trợ. Tải lên không bao giờ phê duyệt việc đăng.

Xem tài liệu tham chiếu API hoặc tải đặc tả OpenAPI.