TwexAPI で X エンゲージメントサービス注文を管理する方法
エンゲージメントサービス注文は、成長ハックとして扱うべきものではありません。承認、予算管理、監査ログ、そしてキャンペーンやプラットフォームに適用されるルールの理解が必要な運用リクエストです。
この記事では、TwexAPI のエンゲージメントサービス注文フローで使うエンドポイントを説明します。承認済み注文を POST /twitter/action で送信し、返された order_id を保存し、GET /twitter/action/order-status で配信状態を確認します。
注文前に確認すること
注文フォームを API 呼び出しにつなぐ前に、ガードレールを作ります。
- 対象アカウントまたはキャンペーンが承認済みであることを確認する。
- 関連するプラットフォームルール、顧客契約、社内ポリシーで許可されているか確認する。
- 社内承認 ID、予算責任者、キャンペーン理由を必須にする。
- 元の対象 URL、サービス、数量、依頼者、タイムスタンプを記録する。
- 注文送信と分析レポートを分け、paid activity と organic performance を混在させない。
なぜ許可されていて、誰が承認したのか説明できない場合は、自動化しないでください。
承認済み注文を送信する
POST リクエストを次の URL に送ります。
https://api.twexapi.io/twitter/actionリクエスト本文には 3 つのフィールドがあります。
| フィールド | 必須 | 説明 |
|---|---|---|
service | はい | エンドポイントが対応するサービス値。例: likes、retweets、views、bookmarks、followers。 |
link | はい | 対象 tweet または profile の完全な X/Twitter URL。 |
quantity | はい | 正の整数。送信前に自社の承認ルールで検証します。 |
curl --request POST \
--url https://api.twexapi.io/twitter/action \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"service": "views",
"link": "https://x.com/username/status/1234567890",
"quantity": 100
}'成功レスポンスは注文 ID を返します。
{
"code": 200,
"msg": "success",
"data": {
"order_id": 12345
}
}リクエストとレスポンス全体を、自社の注文テーブルに保存してください。order_id は後続のステータス確認で使うキーです。
注文ステータスを確認する
進捗確認にはステータスエンドポイントを使います。
GET https://api.twexapi.io/twitter/action/order-status?order_id=<order_id>curl --request GET \
--url 'https://api.twexapi.io/twitter/action/order-status?order_id=12345' \
--header 'Authorization: Bearer <token>'ステータスレスポンスには、order_id、start_count、fee、status などのフィールドが含まれることがあります。
{
"code": 200,
"msg": "success",
"data": {
"order_id": 12345,
"start_count": 0,
"fee": 1,
"status": "completed"
}
}pending、in_progress、partial、completed、failed は運用状態として扱います。ステータスエンドポイントが完了を示すまで、配信完了とみなさないでください。
承認メタデータ付き Python クライアント
次の例では API 呼び出しを小さく保ち、承認と監査のロジックをアプリケーション側に置きます。承認 ID を必須にし、各送信を JSONL に記録します。
1import json
2from datetime import datetime, timezone
3from pathlib import Path
4
5import requests
6
7TOKEN = "<your_bearer_token>"
8ORDER_URL = "https://api.twexapi.io/twitter/action"
9STATUS_URL = "https://api.twexapi.io/twitter/action/order-status"
10ORDER_LOG = Path("engagement-service-orders.jsonl")
11
12headers = {
13 "Authorization": f"Bearer {TOKEN}",
14 "Content-Type": "application/json",
15}
16
17ALLOWED_SERVICES = {"likes", "retweets", "views", "bookmarks", "followers"}
18
19def submit_order(service, link, quantity, approval_id, requester, reason):
20 if service not in ALLOWED_SERVICES:
21 raise ValueError(f"Unsupported service: {service}")
22 if not approval_id:
23 raise ValueError("approval_id is required")
24 if quantity <= 0:
25 raise ValueError("quantity must be positive")
26
27 payload = {
28 "service": service,
29 "link": link,
30 "quantity": quantity,
31 }
32
33 response = requests.post(ORDER_URL, headers=headers, json=payload, timeout=30)
34 response.raise_for_status()
35 body = response.json()
36 order_id = (body.get("data") or {}).get("order_id")
37
38 log_row = {
39 "approval_id": approval_id,
40 "requester": requester,
41 "reason": reason,
42 "submitted_at": datetime.now(timezone.utc).isoformat(),
43 "request": payload,
44 "response": body,
45 "order_id": order_id,
46 }
47 with ORDER_LOG.open("a", encoding="utf-8") as f:
48 f.write(json.dumps(log_row, ensure_ascii=False) + "\n")
49
50 return order_id
51
52def check_status(order_id):
53 response = requests.get(
54 STATUS_URL,
55 headers={"Authorization": f"Bearer {TOKEN}"},
56 params={"order_id": order_id},
57 timeout=30,
58 )
59 response.raise_for_status()
60 return response.json()
61
62order_id = submit_order(
63 service="views",
64 link="https://x.com/username/status/1234567890",
65 quantity=100,
66 approval_id="APPROVAL-2025-001",
67 requester="campaign-ops@example.com",
68 reason="Approved campaign operations request",
69)
70
71print(check_status(order_id))本番環境では、注文はローカル JSONL ではなくデータベースに保存し、このワークフローへのアクセスは承認済みオペレーターに限定します。
運用チェックリスト
各注文の前に次を確認します。
| チェック | 重要な理由 |
|---|---|
| 対象 URL が正しい | 誤った tweet や profile に送信するのを防ぐ。 |
| キャンペーンが承認済み | 費用発生前に責任の所在を明確にする。 |
| 数量が承認内容と一致 | 誤った過剰注文を防ぐ。 |
| サービス種別が許可済み | ワークフローをポリシー境界内に保つ。 |
| order ID を保存済み | ステータス確認やサポート連絡に必要。 |
| レポートにラベルがある | paid activity と organic analysis を分離する。 |
このチェックにより、マーケティング、財務、サポートチームにとって予期しない事態を減らせます。
ステータス追跡パターン
単純な polling job で、注文が終端状態になるまで status を更新できます。
1import time
2
3TERMINAL_STATUSES = {"completed", "failed"}
4
5def wait_for_terminal_status(order_id, poll_seconds=60, max_checks=30):
6 for _ in range(max_checks):
7 body = check_status(order_id)
8 status = (body.get("data") or {}).get("status")
9 print(f"order={order_id} status={status}")
10
11 if status in TERMINAL_STATUSES:
12 return body
13
14 time.sleep(poll_seconds)
15
16 raise TimeoutError(f"Order {order_id} did not reach a terminal status")polling 間隔は適切に保ちます。ステータス確認は運用を助けるためのもので、不要な負荷を増やすためのものではありません。
よくある落とし穴
- 承認記録なしで注文を送信する。
- paid と organic の指標を、ラベルなしで同じレポートに混ぜる。
- 失敗した送信を、注文が作成されたか確認せずに再試行する。
- 対象 URL を正規化せず、誤った場所に送信する。
partialをcompletedと扱う。- キャンペーン申請だけでよい人に、広すぎる API 権限を渡す。
まとめ
POST /twitter/action は、承認済みワークフローの最後のステップとしてだけ使います。リクエスト、レスポンス、承認メタデータ、order_id を保存し、GET /twitter/action/order-status でステータスを確認します。
技術的な API 呼び出しはシンプルです。本当に重要なのは、その周囲にある制御レイヤーです。検証、承認、監査性、明確なレポート境界を整えて運用しましょう。