--- sidebar: order: 1 title: API HTTP description: 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ể [#create-a-scoped-api-key] Trong [Cài đặt Influence](https://influence.so/sign-in?next=%2Fapp%2Fsettings%2Faccount%23settings-developer), 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 [#discover-tools-and-make-a-read] Đặ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. ```sh 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 [#request-paths] | 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 [#prepare-and-confirm-actions] 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`. 1. 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. 2. 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`. 3. 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](/vi/developers/mcp#prepare-finished-content). 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](/vi/help/ai-assistants#scheduling-allowance) á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 [#handle-errors-and-uncertain-results] 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 [#upload-media] Ư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](/vi/help/media): 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](/vi/api-reference) hoặc [tải đặc tả OpenAPI](/specs/influence.openapi.json).