Quy trình OAuth v2

Cài đặt

npm install --global @anakonn/ankk@0.5.1
ankk --version

Đăng nhập và chọn thương hiệu

ANKK v2 sử dụng tài khoản người dùng của bạn qua OAuth trên trình duyệt. Quyền hiện có áp dụng cho mọi yêu cầu. Kết nối ứng dụng không cấp thêm quyền với thương hiệu. Chọn thương hiệu khi làm việc; việc cấp quyền OAuth không chọn thương hiệu.

Dùng CLI 0.5.1 với Node.js 24 trở lên. ID máy khách công khai xác định ANKK CLI, không phải bí mật.

export ANKK_OAUTH_CLIENT_ID=ankk-cli-production

ankk --json auth login --environment production
ankk auth status --environment production --connection OAUTH_CONNECTION_ID
ankk --json brands list --environment production --connection OAUTH_CONNECTION_ID --all
ankk --json connections list --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --all

Thay mã định danh viết hoa bằng ID từ chính yêu cầu của bạn. ID kết nối OAuth chọn phiên đăng nhập. ID tài khoản SNS xác định đích đăng bài; nó khác cả kết nối OAuth lẫn ID tài khoản của nhà cung cấp. Dùng cùng môi trường và thương hiệu trong toàn bộ quy trình. Các ví dụ chỉ định rõ cả hai, kể cả khi bạn đã cấu hình thương hiệu mặc định cục bộ.

Nếu terminal không tự mở trình duyệt, dùng ankk auth login --environment production --device --no-open và làm theo hướng dẫn xác minh hiển thị. Token được lưu trong kho thông tin xác thực của hệ điều hành. Nếu kho này không khả dụng, hãy khôi phục trước khi đăng nhập; tuyệt đối không dán token vào cuộc trò chuyện hoặc lưu trong tệp JSON xuất bản.

Đọc hiệu suất và bài đăng đã lưu

ankk --json analytics get --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --from 2026-10-01T00:00:00Z --to 2026-10-02T00:00:00Z
ankk --json posts list --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --all

Chọn kỳ báo cáo thực tế. Bao gồm thời điểm bắt đầu và không bao gồm thời điểm kết thúc; dấu thời gian dùng UTC. Chuyển ngày giờ địa phương của người dùng sang UTC trước khi truy vấn. Thêm --sns-account SNS_ACCOUNT_ID để giới hạn kết quả cho một tài khoản.

Kết quả mô tả các dữ liệu quan sát đã lưu. Kiểm tra độ bao phủ và thời điểm quan sát trước khi so sánh các kỳ. Dữ liệu thiếu không phải là số không. Ảnh chụp trạng thái tài khoản mới nhất có thời điểm đo riêng và không nhất thiết là tổng của kỳ. Thông tin chuyên sâu Instagram cho kỳ chính xác tách biệt với các quan sát tích lũy. Thao tác đọc không khởi động thu thập từ nhà cung cấp. posts refresh là thao tác riêng cho dữ liệu bài đăng/bình luận, không phải yêu cầu làm mới phân tích.

Danh sách dùng con trỏ. --all lần theo các trang; dữ liệu có thể thay đổi trong lúc phân trang nên kết quả không phải ảnh chụp tại một thời điểm. Nếu con trỏ hết hạn, báo rõ kết quả chưa đầy đủ và chủ động bắt đầu danh sách mới, thay vì âm thầm ghép với các trang cũ.

Chuẩn bị tệp trước khi xuất bản

ankk --json media create-upload --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --file ./photo.jpg --idempotency-key UPLOAD_KEY
ankk --json media complete-upload MEDIA_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --idempotency-key INSPECTION_KEY --wait --wait-timeout 180
ankk --json media get MEDIA_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID

Lệnh đầu tiên đăng ký và truyền tệp. Lưu ID phương tiện ngay cả khi truyền thất bại hoặc phản hồi chưa chắc chắn. Lệnh thứ hai yêu cầu kiểm tra; chỉ dùng phương tiện khi trạng thái cuối cùng là ready. Các bước này không xuất bản. Có thể dùng lại phương tiện trong cùng thương hiệu. Hãy tải lên riêng cho thương hiệu khác.

Nếu chỉ URL tải lên hết hạn, dùng media refresh-upload MEDIA_ID với cùng môi trường, phiên đăng nhập và thương hiệu. URL mới không gia hạn thời hạn nghiệp vụ ban đầu hay thay thế tệp. Nội dung byte khác cần một lượt tải phương tiện mới. Xem URL truyền có chữ ký như thông tin xác thực và không đưa vào bản ghi trò chuyện được chia sẻ. Ứng dụng khách không truyền được tệp có thể dùng URL tiến trình trên trình duyệt được trả về, đăng nhập và chọn tệp, sau đó quay lại với cùng ID phương tiện để kiểm tra trạng thái sẵn sàng.

Xem lại và xuất bản

Xác nhận thương hiệu, tài khoản, toàn bộ văn bản, thứ tự các phần trong chuỗi bài, tệp đính kèm, tùy chọn nhà cung cấp và thời gian thực thi trước khi xuất bản nội dung do AI chuẩn bị. Phê duyệt đã có cho đúng ý định đó là đủ. Chỉ yêu cầu phân tích hoặc soạn nháp không phải là phê duyệt xuất bản.

Lưu đầu vào xuất bản ngay tối thiểu này dưới tên publish.json. Chọn tài khoản hỗ trợ tổ hợp văn bản và hình ảnh dự kiến; máy chủ sẽ kiểm tra lại khả năng hiện tại, trạng thái sẵn sàng của phương tiện và quyền.

{
  "scheduled_at": null,
  "targets": [
    {
      "sns_account_id": "SNS_ACCOUNT_ID",
      "text": "The exact text you approved",
      "media_ids": ["MEDIA_ID"]
    }
  ]
}

ankk --json contents publish --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --file publish.json --idempotency-key PUBLICATION_KEY

Chọn và lưu khóa duy nhất cho ý định này trước khi gửi. Dùng lại đúng khóa và nội dung yêu cầu sau phản hồi không chắc chắn, kể cả khi chuyển giữa API, CLI và MCP. Không tạo một lượt xuất bản khác chỉ vì kết nối hết thời gian. Cùng khóa nhưng đầu vào thay đổi sẽ gây xung đột. Khóa hết hạn không tạo công việc mới: kiểm tra kết quả cũ trước khi chủ động bắt đầu ý định mới.

Để đặt lịch, thay scheduled_at: null bằng thời điểm UTC trong tương lai đã được phê duyệt, ví dụ 2026-12-01T09:00:00Z. Thay ngày minh họa này trước khi dùng và xác minh nó vẫn ở tương lai. Đăng ký hoàn tất trả về một publish_operation_id riêng; điều đó không có nghĩa là các bài SNS đã lên lịch đã được xuất bản.

Theo dõi kết quả

ankk --json operations get OPERATION_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --wait --wait-timeout 180

Với xuất bản ngay, theo dõi ID thao tác được trả về. Với đặt lịch, theo dõi publish_operation_id vào thời điểm thực thi. Chờ là tùy chọn và diễn ra cục bộ. Mã thoát CLI 10 nghĩa là hết giới hạn chờ; mã thoát 130 nghĩa là việc chờ bị ngắt. Cả hai đều không hủy tác vụ trên máy chủ. Tiếp tục đọc cùng thao tác đó. Mã thoát 11 khi chờ cho biết kết quả cuối cùng thất bại, bị hủy hoặc thành công một phần; kiểm tra kết quả từng tài khoản. Truy vấn trạng thái thông thường có thể thoát với mã 0 trong khi báo thao tác thất bại, nên script cũng phải kiểm tra trạng thái phản hồi.

Báo cáo riêng từng tài khoản. Giữ nguyên các bài đã thành công và URL của chúng. Mảng posts có thứ tự chứa các bài đã được xác nhận trong chuỗi; riêng post_url đại diện có thể không mô tả toàn bộ chuỗi. Thiếu URL hoặc trạng thái chưa được giải quyết không chứng minh rằng nhà cung cấp chưa tạo gì. Giữ các kết quả đang đối soát và chưa rõ ở trạng thái chưa giải quyết cho đến khi tác vụ hiện có cung cấp bằng chứng.

Thay đổi lịch hoặc khôi phục sau lỗi

Đọc contents get CONTENT_ID với cùng môi trường, phiên đăng nhập và thương hiệu trước khi đổi nội dung hay thời gian. Truyền phiên bản hiện tại dưới dạng --expected-version. contents update sửa các đích đủ điều kiện chưa bắt đầu; contents reschedule đổi lịch UTC của chúng. Xung đột phiên bản yêu cầu đọc và xem lại, không được âm thầm ghi đè. contents cancel yêu cầu hủy; kiểm tra thao tác xuất bản được trả về đến khi xác nhận hủy. Việc thực thi có thể diễn ra trước khi hủy có hiệu lực.

Chỉ thử lại các tài khoản thất bại được chọn hiện đang được đánh dấu can_retry:

ankk --json contents retry ORIGINAL_OPERATION_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --accounts FAILED_SNS_ACCOUNT_ID --idempotency-key RETRY_KEY

Đây là ý định thực thi mới và cần khóa mới phù hợp cùng phê duyệt người dùng nếu chưa được bao gồm trong phê duyệt trước đó. Giữ khóa thử lại sau phản hồi chưa chắc chắn. Thử lại dùng nội dung đã lưu và chạy sớm nhất có thể; không bao giờ đăng lại các đích đã thành công hoặc chưa rõ kết quả. Để đặt lịch mới trong tương lai, contents duplicate chỉ trả về đầu vào có thể chỉnh sửa. Xem lại và gửi một lượt xuất bản mới đã được phê duyệt.

Loại bỏ mục hàng đợi thất bại đủ điều kiện sẽ ẩn chúng khỏi hàng đợi công việc; không xóa bài, xóa lịch sử thực thi hoặc thử lại bất kỳ việc gì. Hủy hàng loạt có thể trả về cả nhóm được chấp nhận và nhóm bị từ chối; theo dõi từng thao tác xuất bản được chấp nhận. Loại bỏ hàng loạt hoàn thành đồng bộ: kiểm tra nhóm đã loại bỏ và bị từ chối trong biên nhận, không chờ thao tác mới. Trong cả hai trường hợp, đọc toàn bộ biên nhận thay vì coi mã thoát là kết quả thành công toàn bộ hoặc thất bại toàn bộ.

Xử lý lỗi yêu cầu và ngắt kết nối

Đọc mã lỗi có cấu trúc, ID yêu cầu, ID thao tác nếu có, next_action và retry_at. Khôi phục xác thực phải quay lại thao tác ban đầu. Lỗi quyền cần quyền truy cập hợp lệ, không phải một giao diện khác. Phải tuân thủ giới hạn tần suất và hạn chế khả năng. Yêu cầu có thể thử lại không cho phép tạo lượt xuất bản mới hay khóa thay thế.

ankk auth logout --environment production --connection OAUTH_CONNECTION_ID

Đăng xuất báo riêng việc thu hồi trên máy chủ và xóa thông tin xác thực cục bộ. Nếu chưa xác nhận thu hồi trên máy chủ, hãy thu hồi kết nối cũ trong cài đặt ANKK hoặc qua một kết nối hợp lệ khác. Xóa kết nối OAuth không hủy các lượt xuất bản đã được chấp nhận hay xóa phương tiện thuộc thương hiệu.

Dùng MCP và Skills

MCP dùng OAuth người dùng tại https://api.ankk.app/mcp/v2. Ứng dụng chủ cần máy khách đã đăng ký; chỉ nhập URL chưa hoàn tất kết nối. Chưa có mục chính thức trong danh mục ChatGPT và Claude. Khi không có thẻ, dùng văn bản và kết quả có cấu trúc. Kiểm tra số liệu và thời điểm quan sát, không chỉ bản tóm tắt hội thoại.

Skills cung cấp quy trình, không cấp quyền hay thông tin xác thực. Cài thẻ ứng viên cố định dưới đây rồi kiểm tra thương hiệu, sự chấp thuận và kết quả cuối cùng.

npx skills add https://github.com/Anakonn/ankk-skills/tree/v0.1.0-rc.1 --skill ankk-analyze --skill ankk-publish