Hướng dẫn dành cho nhà phát triển

Xác thực

Tạo khóa API trong bảng điều khiển tại Cài đặt, API và webhook. Khóa bắt đầu bằng ss_live_, thuộc một không gian làm việc và có thể giới hạn ở một số dự án. Gửi khóa dưới dạng bearer token trong mọi yêu cầu:

curl https://www.amaposta.com/api/v1/me \
  -H "Authorization: Bearer ss_live_…"

Phản hồi cho biết tên khóa, các phạm vi và không gian làm việc. Mỗi khóa có một hoặc nhiều phạm vi:

Mỗi khóa có thể gửi 120 yêu cầu mỗi phút. Vượt giới hạn này, bạn nhận 429 với mã rate_limited; hãy đợi một lát rồi thử lại.

Dự án và kênh

Bài viết nằm trong dự án. Liệt kê các dự án khóa của bạn có thể thấy, rồi các kênh trong một dự án. Bạn cần ID kênh để nhắm đến kênh đó hoặc ghi đè văn bản của kênh.

curl https://www.amaposta.com/api/v1/projects \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/channels \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

Kênh có provider (youtube, instagram, tiktok, x, facebook, custom hoặc sandbox), status (active, expiring, needs_reconnect, error hoặc disabled) và các loại bài viết mà kênh supports.

Tải nội dung đa phương tiện lên

Ảnh và video được tải lên một lần cho mỗi dự án và có thể dùng trong số lượng bài viết không giới hạn. Có ba cách nhập.

Tải lên trực tiếp

Gửi tệp dưới dạng dữ liệu biểu mẫu multipart trong trường có tên file. Phù hợp nhất cho tệp tối đa vài trăm MB.

curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/media \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -F "[email protected]"

Tải lên có chữ ký sẵn cho tệp lớn

Yêu cầu URL tải lên, PUT dữ liệu trực tiếp vào bộ lưu trữ, sau đó báo cho Amaposta rằng bạn đã hoàn tất.

# 1. Ask for an upload URL. The response is {"media": { … }, "upload_url": "…"}
curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/media/uploads \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "batch-142.mp4", "content_type": "video/mp4", "size_bytes": 48213844}'

# 2. Upload the bytes to upload_url
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --upload-file batch-142.mp4

# 3. Finish the upload
curl -X POST https://www.amaposta.com/api/v1/media/$MEDIA_ID/complete \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

Nhập từ URL

Cung cấp URL công khai để Amaposta tải tệp xuống trong nền. Bạn cũng có thể bỏ qua bước này và truyền media_url khi tạo bài viết.

curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/media/import \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://cdn.example.com/batch-142.mp4"}'

Mỗi lần tải lên trả về đối tượng đa phương tiện. status chuyển từ pending sang processing rồi ready (hoặc failed, kèm error). Sau khi xử lý, đối tượng có width, height, duration_ms và hình thu nhỏ. Thăm dò GET /api/v1/media/{id} hoặc lắng nghe webhook media.ready. url trả về có chữ ký và có hiệu lực trong 12 giờ.

Tạo bài viết

POST /api/v1/projects/{project_id}/posts tạo một bài viết với một lượt gửi cho mỗi kênh. Amaposta điều chỉnh cho từng nền tảng: tiêu đề chỉ được gửi đến nơi có trường tiêu đề, hashtag trở thành thẻ trên YouTube và văn bản trong bài ở nơi khác.

curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/posts \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: episode-142" \
  -d @- <<'JSON'
{
  "kind": "video",
  "title": "How we roast a batch in 12 minutes",
  "description": "From green beans to first crack. We filmed one batch start to finish.",
  "hashtags": ["coffee", "behindthescenes"],
  "media_url": "https://cdn.example.com/batch-142.mp4",
  "cover_url": "https://cdn.example.com/batch-142-cover.jpg",
  "overrides": {
    "<x-channel-id>": {
      "description": "Batch 142 is out: green beans to first crack in 12 minutes."
    },
    "<youtube-channel-id>": {
      "options": { "privacy": "unlisted" }
    }
  },
  "schedule": { "mode": "queue" },
  "external_ref": "episode-142",
  "metadata": {
    "pipeline": { "name": "nightly-cut", "run": "2026-10-17" }
  }
}
JSON

Trường

Phản hồi là bài viết, bao gồm một mục trong deliveries cho mỗi kênh.

Thử lại an toàn

Mạng có thể làm mất yêu cầu. Gửi tiêu đề Idempotency-Key khi tạo bài viết; lần thử lại với cùng khóa sẽ trả về bài viết từ lần thử đầu thay vì tạo bài thứ hai. Dùng giá trị ổn định từ phía bạn, như ID công việc hoặc tập. Khóa được cắt còn 200 ký tự.

Lên lịch và đăng

Lên lịch bản nháp, đăng ngay, thêm vào hàng đợi hoặc gỡ khỏi lịch bằng POST /api/v1/posts/{post_id}/schedule.

curl https://www.amaposta.com/api/v1/posts/$POST_ID/schedule \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "at", "at": "2026-10-20T07:00:00Z"}'

• atĐăng vào thời gian đã cho, tối đa hai năm tới.
• nowĐăng ngay lập tức.
• queueChọn khung giờ đăng trống tiếp theo cho các kênh của bài viết trong 12 tuần tới.
• unscheduleChuyển bài viết về bản nháp.

Trước khi lên lịch, các bước kiểm tra tương tự như trong trình soạn thảo sẽ chạy. Nếu một bước thất bại, yêu cầu trả về 400 kèm thông báo như Khắc phục trước khi lên lịch: YouTube cần tiêu đề. Việc lên lịch cần phạm vi posts:publish hoặc dự án có bật phê duyệt; trong trường hợp đó, bài viết chờ trong hộp thư xét duyệt.

Đọc bài viết và lượt gửi

Liệt kê bài viết của dự án, lọc theo status (các trạng thái cách nhau bằng dấu phẩy, hoặc inbox, queue hay history), khoảng from/to, limit và offset. Phản hồi là {"items": […], "total": n}.

curl "https://www.amaposta.com/api/v1/projects/$PROJECT_ID/posts?status=queue" \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

curl https://www.amaposta.com/api/v1/posts/$POST_ID \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

Bài viết có status tổng thể (draft, in_review, changes_requested, ready, scheduled, publishing, published, partial hoặc failed) và một lượt gửi cho mỗi kênh:

"deliveries": [
  {
    "id": "0192b7d4-…",
    "channel_id": "0192b7a1-…",
    "status": "published",
    "url": "https://www.youtube.com/watch?v=…",
    "error": null,
    "published_at": "2026-10-20T07:00:41Z"
  },
  {
    "id": "0192b7d4-…",
    "channel_id": "0192b7a9-…",
    "status": "failed",
    "url": null,
    "error": {
      "code": "endpoint_unavailable",
      "message": "Your endpoint returned 503 Service Unavailable",
      "hint": "Amaposta will retry with backoff."
    },
    "published_at": null
  }
]

Trạng thái lượt gửi là pending, scheduled, publishing, processing, published, failed và cancelled. DELETE /api/v1/posts/{post_id} xóa một bài viết.

Lỗi

Mọi lỗi có cùng cấu trúc: đối tượng error với code ổn định, message có thể hiển thị cho người dùng và đôi khi có fields (thông báo cho từng trường) cùng hint.

{
  "error": {
    "code": "validation",
    "message": "Please fix the highlighted fields.",
    "fields": {
      "kind": "Use text, image or video."
    }
  }
}

Webhook

Thêm điểm cuối trong Cài đặt, API và webhook, chọn sự kiện bạn muốn và sao chép bí mật ký. Amaposta gửi JSON bằng POST đến URL của bạn cho mỗi sự kiện. Mọi phản hồi ngoài 2xx hoặc không phản hồi trong vòng 15 giây đều được thử lại với thời gian chờ tăng dần; điểm cuối liên tục gặp lỗi sẽ bị tắt và quản trị viên được thông báo.

POST /your/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Amaposta-Webhooks/1.0
X-Amaposta-Event: post.published
X-Amaposta-Event-Id: 0192b7e0-…
X-Amaposta-Signature: t=1792479641,v1=5f2b0c…

{
  "id": "0192b7e0-…",
  "type": "post.published",
  "created_at": "2026-10-20T07:00:41Z",
  "project_id": "0192a3f1-…",
  "data": {
    "post_id": "0192b7c8-…",
    "delivery_id": "0192b7d4-…",
    "channel_id": "0192b7a1-…",
    "provider": "youtube",
    "external_id": "…",
    "url": "https://www.youtube.com/watch?v=…"
  }
}

Xác minh chữ ký

X-Amaposta-Signature là t=<unix seconds>,v1=<hex>, trong đó v1 là HMAC_SHA256(secret, t + "." + body) tính trên phần thân yêu cầu thô. Hãy tự tính, so sánh trong thời gian hằng định và từ chối dấu thời gian cũ để ngăn tấn công phát lại.

import crypto from "node:crypto";

// rawBody: the request body exactly as received (string or Buffer).
export function verifySignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}

import hashlib
import hmac
import time


def verify_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", "0"))
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Kênh API tùy chỉnh đăng đến một điểm cuối HTTPS do bạn vận hành: CMS, công cụ bản tin hoặc nền tảng Amaposta chưa hỗ trợ. Kênh xuất hiện trên lịch, được kiểm tra, phê duyệt và thử lại như mọi kênh khác. Khi đăng bài, Amaposta gửi một yêu cầu POST cho mỗi lượt gửi:

POST /amaposta/publish HTTP/1.1
Authorization: Bearer <your API key>
Content-Type: application/json
Idempotency-Key: 0192b7d4-…
X-Amaposta-Delivery: 0192b7d4-…
X-Amaposta-Signature: t=1792479600,v1=9ac41e…

{
  "id": "0192b7d4-…",
  "type": "post.publish",
  "created_at": "2026-10-20T07:00:00Z",
  "content": {
    "kind": "video",
    "title": "How we roast a batch in 12 minutes",
    "text": "From green beans to first crack. We filmed one batch start to finish.",
    "hashtags": ["coffee", "behindthescenes"],
    "media": {
      "url": "https://…",
      "content_type": "video/mp4",
      "size_bytes": 48213844,
      "width": 1080,
      "height": 1920,
      "duration_ms": 58000,
      "filename": "batch-142.mp4"
    },
    "cover": null,
    "options": {}
  },
  "post": {
    "id": "0192b7c8-…",
    "external_ref": "episode-142",
    "scheduled_at": "2026-10-20T07:00:00Z",
    "metadata": {
      "pipeline": { "name": "nightly-cut" }
    }
  },
  "project": { "id": "0192a3f1-…", "name": "Spring launch" },
  "channel": { "id": "0192b7a9-…", "name": "api.example.com" }
}

Authorization

Khóa API của bạn. Tên tiêu đề và tiền tố (mặc định là Bearer) được đặt trên kênh.

Idempotency-Key

ID lượt gửi. Lần thử lại của cùng lượt gửi dùng cùng khóa để bạn có thể bỏ qua công việc đã làm.

X-Amaposta-Delivery

ID lượt gửi được nhắc lại để ghi nhật ký.

X-Amaposta-Signature

Được ký như webhook, bằng bí mật ký riêng của kênh.

Cách phản hồi

• 2xxĐã đăng. Có thể trả về {"id": "…", "url": "…"} để liên kết xuất hiện trên bài viết.
• 401, 403Khóa bị từ chối. Kênh được đánh dấu cần kết nối lại và quản trị viên được thông báo. Không dùng các mã này cho chữ ký sai.
• 5xx, 408, 429Tạm thời. Amaposta thử lại với thời gian chờ tăng dần.
• 4xx khácBài viết được đánh dấu thất bại kèm thông báo của bạn, để ai đó có thể khắc phục và nhấn Thử lại.

app.post("/amaposta/publish", express.raw({ type: "application/json" }), async (req, res) => {
  const signature = req.get("X-Amaposta-Signature") ?? "";
  if (!verifySignature(req.body, signature, process.env.AMAPOSTA_SIGNING_SECRET)) {
    return res.status(400).json({ message: "Bad signature" });
  }
  const delivery = JSON.parse(req.body);
  const item = await publishToYourSystem(delivery.content, req.get("Idempotency-Key"));
  res.json({ id: item.id, url: item.url });
});

Điểm cuối của bạn phải truy cập được từ internet; không theo chuyển hướng. Khi bạn kết nối kênh, Amaposta kiểm tra bằng GET đến URL tình trạng nếu bạn đã đặt, hoặc yêu cầu OPTIONS đến điểm cuối.

Kênh thử nghiệm hoạt động như kênh thật nhưng không có gì rời khỏi Amaposta. Dùng kênh này để xây dựng và kiểm thử toàn bộ tích hợp: bài viết được lên lịch, phát sóng, đăng hoặc thất bại và kích hoạt cùng các webhook. Kênh thử nghiệm miễn phí ở mọi gói và không tính vào giới hạn kênh.

Chọn cách hoạt động khi bạn thêm kênh:

• Luôn thành côngMọi bài viết đều được đăng.
• Thỉnh thoảng thất bạiXem lỗi và thử lại mà không phải chờ sự cố thật.
• Luôn thất bạiKiểm thử cách xử lý post.failed của bạn.
• Kết nối đã hết hạnXem cảnh báo và liên kết kết nối lại hiển thị thế nào khi quyền truy cập hết hạn.

X tính phí mỗi lệnh gọi API, bao gồm cả mỗi lần đăng bài, cho ứng dụng dành cho nhà phát triển thực hiện lệnh gọi đó và trừ phí từ tín dụng trả trước của ứng dụng. Vì vậy, bạn kết nối X qua ứng dụng dành cho nhà phát triển X của riêng mình: thiết lập một lần cho mỗi không gian làm việc, rồi kết nối bao nhiêu tài khoản X tùy thích. Mỗi tài khoản đăng nhập trên X và phí đăng bài được trừ từ tín dụng của ứng dụng của bạn.

1. Đăng nhập tại console.x.com bằng tài khoản X sẽ sở hữu ứng dụng, chẳng hạn tài khoản của đại lý của bạn, rồi tạo ứng dụng.
2. Mở User authentication settings của ứng dụng và nhập:
   • App permissionsRead and write
   • Type of AppWeb App, Automated App or Bot
   • Callback URI / Redirect URLhttps://www.amaposta.com/oauth/x/callback
   • Website URLTrang web của bạn

   Sau đó lưu lại. Chỉ loại ứng dụng này mới được cấp mã bí mật máy khách mà Amaposta dùng để đăng nhập.

3. Sao chép OAuth 2.0 Client ID và Client Secret mà X hiển thị sau khi lưu. Không dùng API Key, API Key Secret hay Bearer Token: chúng dành cho các kiểu truy cập khác. X chỉ hiển thị mã bí mật một lần.
4. Mua tín dụng API trong bảng điều khiển X. Tự động nạp tiền giúp tiếp tục đăng bài khi tín dụng sắp hết; giới hạn chi tiêu giúp kiểm soát chi phí. Khi hết tín dụng, X sẽ từ chối đăng bài cho đến khi bạn nạp thêm.
5. Trong Amaposta, mở mục Kênh của dự án, chọn Kết nối kênh rồi chọn X. Dán ID máy khách và mã bí mật máy khách, tiếp tục đến X, đăng nhập bằng tài khoản cần kết nối rồi cho phép truy cập.

Thông tin hữu ích

• Ứng dụng được lưu cho toàn bộ không gian làm việc và mã bí mật được mã hóa. Mọi tài khoản X khác đều có thể kết nối chỉ bằng một lần nhấp từ bất kỳ dự án nào.
• Các kênh tiếp tục dùng ứng dụng đã được dùng để kết nối ban đầu. Khi kết nối lại một kênh, kể cả qua liên kết kết nối lại dành cho khách hàng, ứng dụng đó sẽ được dùng lại; khách hàng của bạn không bao giờ nhìn thấy ứng dụng này.
• Để đổi ứng dụng, chọn “Dùng ứng dụng khác” khi kết nối X. Nếu tạo lại Client Secret, hãy nhập giá trị mới tại đó rồi kết nối lại các kênh X của bạn.
• Bảng điều khiển X chỉ cấp token cho tài khoản sở hữu ứng dụng. Để kết nối tài khoản của khách hàng, bạn cần đăng nhập qua ứng dụng của mình; với tài khoản của chính bạn, việc nhập token thủ công vẫn hoạt động.