TRAMTUONGTAC API Reference
API REST để tích hợp TRAMTUONGTAC vào ứng dụng của bạn. Xác thực qua Bearer token, tất cả request và response đều ở định dạng JSON. Endpoint ổn định, không có breaking change trong minor version.
Xác thực Bearer
Mọi request cần header Authorization: Bearer <token>. Token lấy từ endpoint /auth/token hoặc dashboard.
Rate limit
1.000 request / giờ cho mỗi API key. Header X-RateLimit-Remaining trả về số request còn lại.
Idempotency
Các endpoint POST quan trọng hỗ trợ header Idempotency-Key để tránh tạo trùng khi retry.
Lấy access token
Đổi API key và secret lấy access token có thời hạn. Token hết hạn sau 24 giờ, cần refresh bằng endpoint /auth/refresh hoặc lấy token mới.
Không bao giờ để lộ api_secret ở client-side. Chỉ gọi endpoint này từ server của bạn.
| Trường | Kiểu | Mô tả |
|---|---|---|
| api_keyrequired | string | API key của ứng dụng |
| api_secretrequired | string | Secret tương ứng |
| scopeoptional | string[] | Danh sách quyền cần cấp. Mặc định là toàn bộ quyền của key. |
curl -X POST https://api.TRAMTUONGTAC.app/v1/auth/token \ -H "Content-Type: application/json" \ -d '{ "api_key": "tk_live_a1b2c3d4e5f6", "api_secret": "sk_live_xxxxxxxxxxxx", "scope": ["tasks:read", "tasks:write", "credits:read"] }'
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 86400,
"scope": ["tasks:read", "tasks:write", "credits:read"]
}
Lấy danh sách nhiệm vụ
Trả về danh sách nhiệm vụ đang mở trên marketplace. Hỗ trợ filter theo nền tảng, loại nhiệm vụ, phần thưởng tối thiểu, và Trust Score tối thiểu của người tạo. Kết quả mặc định sắp xếp theo phần thưởng giảm dần.
| Tham số | Kiểu | Mô tả |
|---|---|---|
| platformoptional | string | Lọc theo nền tảng: facebook, instagram, tiktok, youtube, website |
| typeoptional | string | Loại nhiệm vụ: follow, like, comment, visit |
| min_rewardoptional | integer | Phần thưởng tối thiểu (Credits) |
| min_trustoptional | integer | Trust Score tối thiểu của người tạo (0–100) |
| sortoptional | string | Sắp xếp: reward_desc (mặc định), reward_asc, newest, ending_soon |
| pageoptional | integer | Trang, bắt đầu từ 1. Mặc định 1. |
| per_pageoptional | integer | Số item mỗi trang, tối đa 100. Mặc định 20. |
curl "https://api.TRAMTUONGTAC.app/v1/tasks?platform=facebook&min_reward=10&sort=reward_desc" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
{
"data": [
{
"id": "T-2101",
"platform": "facebook",
"type": "follow",
"title": "Theo dõi trang Facebook doanh nghiệp",
"reward": 12,
"slots_total": 50,
"slots_taken": 32,
"duration_seconds": 30,
"verification": "automatic",
"creator": {
"id": "U-1024",
"name": "Minh Anh",
"trust_score": 94
},
"expires_at": "2025-10-15T14:22:00Z",
"created_at": "2025-10-08T09:15:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 127,
"total_pages": 7
}
}
Chi tiết nhiệm vụ
Trả về thông tin chi tiết của một nhiệm vụ, bao gồm yêu cầu cụ thể, đường dẫn nội dung, danh sách các bước, và trạng thái xác minh.
| Tham số | Kiểu | Mô tả |
|---|---|---|
| task_idrequired | string | ID nhiệm vụ, dạng T-XXXX |
{
"id": "T-2101",
"platform": "facebook",
"type": "follow",
"title": "Theo dõi trang Facebook doanh nghiệp",
"description": "Nhấn theo dõi trang, giữ trạng thái tối thiểu 30 giây.",
"content_url": "https://facebook.com/minhanh.studio",
"reward": 12,
"slots_total": 50,
"slots_taken": 32,
"duration_seconds": 30,
"verification": "automatic",
"steps": [
{ "order": 1, "text": "Mở liên kết Facebook" },
{ "order": 2, "text": "Nhấn theo dõi" },
{ "order": 3, "text": "Giữ ít nhất 30 giây" }
],
"notes": ["Không hủy theo dõi trong 24 giờ"],
"creator": { "id": "U-1024", "name": "Minh Anh", "trust_score": 94 },
"expires_at": "2025-10-15T14:22:00Z",
"created_at": "2025-10-08T09:15:00Z"
}
Nhận nhiệm vụ
Nhận một nhiệm vụ và chiếm một suất. Sau khi nhận thành công, hệ thống bắt đầu đếm thời hạn 24 giờ cho user hoàn thành.
Endpoint này hỗ trợ header Idempotency-Key. Nếu bạn retry cùng key trong 24 giờ, hệ thống sẽ trả về kết quả của lần gọi đầu tiên thay vì tạo lượt nhận mới.
| Trường | Kiểu | Mô tả |
|---|---|---|
| account_idrequired | string | ID tài khoản MXH đã cấu hình dùng để làm nhiệm vụ |
{
"assignment_id": "A-5032",
"task_id": "T-2101",
"account_id": "ACC-201",
"status": "in_progress",
"expires_at": "2025-10-09T14:22:00Z",
"reward": 12
}
Hoàn thành nhiệm vụ
Gửi xác nhận đã hoàn thành nhiệm vụ. Hệ thống sẽ xác minh tự động (nếu có thể) hoặc đưa vào hàng đợi xác minh thủ công. Kết quả thường có trong vài phút cho xác minh tự động, tối đa 24 giờ cho xác minh thủ công.
| Trường | Kiểu | Mô tả |
|---|---|---|
| assignment_idrequired | string | ID lượt nhận, lấy từ response của /accept |
| proof_urloptional | string | Link ảnh chụp xác minh (nếu xác minh không tự động được) |
| noteoptional | string | Ghi chú thêm cho người tạo nhiệm vụ (tối đa 500 ký tự) |
curl -X POST https://api.TRAMTUONGTAC.app/v1/tasks/T-2101/complete \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 6f8a9c2e-4b1d-4a5e-8c7f-9d2e3a1b5c4f" \ -d '{ "assignment_id": "A-5032", "proof_url": "https://imgur.com/abc123", "note": "Đã theo dõi trang và giữ 45 giây" }'
{
"submission_id": "SUB-8801",
"assignment_id": "A-5032",
"status": "verifying",
"verification_type": "automatic",
"estimated_time_seconds": 180,
"reward_pending": 12
}
Trả về 202 Accepted vì xác minh là tiến trình bất đồng bộ. Để nhận kết quả, polling endpoint GET /submissions/{submission_id} hoặc đăng ký webhook task.verified.
{
"submission_id": "SUB-8801",
"status": "verified",
"verified_at": "2025-10-09T11:30:45Z",
"credits_awarded": 12,
"new_balance": 272
}
Nhiệm vụ của tôi
Trả về danh sách nhiệm vụ user đã nhận, chia theo trạng thái: in_progress, verifying, completed, rejected.
| Tham số | Kiểu | Mô tả |
|---|---|---|
| statusoptional | string | Lọc theo trạng thái. Không truyền để lấy tất cả. |
| fromoptional | ISO date | Lọc từ ngày (VD: 2025-10-01) |
| tooptional | ISO date | Lọc đến ngày |
{
"data": [
{
"assignment_id": "A-5032",
"task_id": "T-2101",
"title": "Theo dõi trang Facebook doanh nghiệp",
"platform": "facebook",
"reward": 12,
"status": "verifying",
"accepted_at": "2025-10-09T11:15:00Z",
"completed_at": "2025-10-09T11:28:00Z",
"expires_at": "2025-10-10T11:15:00Z"
}
],
"summary": {
"in_progress": 3,
"verifying": 2,
"completed": 48,
"rejected": 1
}
}
Tạo nhiệm vụ mới
Mở một nhiệm vụ mới cho nội dung của bạn. Credits sẽ bị trừ ngay khi nhiệm vụ được tạo. Suất chưa làm sẽ được hoàn lại khi nhiệm vụ hết hạn.
Tổng chi phí = slots × reward + phí nền tảng 2%. Bạn cần có đủ Credits trong số dư. Kiểm tra số dư qua endpoint GET /me/balance trước khi tạo.
| Trường | Kiểu | Mô tả |
|---|---|---|
| platformrequired | string | Nền tảng: facebook, instagram, tiktok, youtube, website |
| typerequired | string | Loại nhiệm vụ: follow, like, comment, visit |
| content_urlrequired | string | Đường dẫn nội dung cần tương tác |
| titlerequired | string | Tiêu đề nhiệm vụ (tối đa 80 ký tự) |
| descriptionoptional | string | Mô tả chi tiết yêu cầu (tối đa 300 ký tự) |
| slotsrequired | integer | Số suất, từ 1 đến 500 |
| rewardrequired | integer | Credits cho mỗi suất, từ 1 đến 100 |
| duration_daysoptional | integer | Thời hạn nhiệm vụ (3, 7, 14, 30). Mặc định 7. |
| min_trustoptional | integer | Trust Score tối thiểu của người nhận (mặc định 0) |
{
"id": "T-2150",
"status": "active",
"slots_total": 20,
"reward": 8,
"cost": {
"subtotal": 160,
"platform_fee": 3,
"total": 163
},
"new_balance": 97,
"expires_at": "2025-10-16T11:00:00Z"
}
Tạm dừng hoặc tiếp tục nhiệm vụ
Tạm dừng nhiệm vụ đang hoạt động hoặc tiếp tục nhiệm vụ đã tạm dừng. Không thể sửa các thông tin khác như tiêu đề, phần thưởng, số suất sau khi tạo.
| Trường | Kiểu | Mô tả |
|---|---|---|
| statusrequired | string | paused hoặc active |
{
"id": "T-2150",
"status": "paused",
"updated_at": "2025-10-09T11:45:00Z"
}
Thông tin tài khoản hiện tại
Trả về thông tin user của access token hiện tại, bao gồm Trust Score, huy hiệu, và các chỉ số tổng hợp.
{
"id": "U-1024",
"handle": "minhanh.studio",
"display_name": "Minh Anh",
"email": "minhanh.studio@gmail.com",
"email_verified": true,
"trust_score": 94,
"trust_tier": "excellent",
"balance": 260,
"stats": {
"tasks_completed": 128,
"tasks_created": 12,
"completion_rate": 0.98
},
"badges": ["top_contributor", "verified"],
"created_at": "2024-03-15T08:00:00Z"
}
Số dư Credits
Trả về số dư Credits hiện tại, chia thành ba loại: khả dụng, đang giữ (từ nhiệm vụ chưa hoàn thành), và đang chờ xác minh.
{
"available": 260,
"held": 163,
"pending": 24,
"total": 447,
"updated_at": "2025-10-09T11:00:00Z"
}
Lịch sử giao dịch Credits
Trả về danh sách giao dịch Credits: kiếm được từ nhiệm vụ, chi để tạo nhiệm vụ, hoàn tiền, nạp.
| Tham số | Kiểu | Mô tả |
|---|---|---|
| typeoptional | string | earn, spend, refund, topup |
| fromoptional | ISO date | Lọc từ ngày |
| tooptional | ISO date | Lọc đến ngày |
{
"data": [
{
"id": "TXN-9001",
"type": "earn",
"amount": 12,
"description": "Hoàn thành nhiệm vụ T-2101",
"created_at": "2025-10-09T11:30:00Z"
},
{
"id": "TXN-9000",
"type": "spend",
"amount": -163,
"description": "Tạo nhiệm vụ T-2150 (20 suất × 8 Credits)",
"created_at": "2025-10-09T11:00:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 127
}
}
Trust Score chi tiết
Trả về Trust Score tổng hợp và chi tiết 5 yếu tố cấu thành.
{
"score": 94,
"tier": "excellent",
"factors": {
"completion_rate": 98,
"on_time_response": 94,
"community_rating": 89,
"account_age": 96,
"dispute_history": 100
},
"trend_30d": +2,
"updated_at": "2025-10-09T11:00:00Z"
}
Danh sách tài khoản mạng xã hội đã cấu hình
Trả về danh sách các tài khoản mạng xã hội đã khai báo, kèm trạng thái xác minh và cờ active (dùng để làm nhiệm vụ).
{
"data": [
{
"id": "ACC-201",
"platform": "facebook",
"profile_url": "https://facebook.com/minhanh.studio",
"display_name": "Minh Anh Studio",
"verified": true,
"active": true,
"added_at": "2025-08-15T10:00:00Z"
}
]
}
Thêm tài khoản mạng xã hội
Khai báo một tài khoản mạng xã hội mới để dùng khi làm nhiệm vụ. Chỉ cần đường dẫn công khai và tên hiển thị — không bao giờ cần mật khẩu.
| Trường | Kiểu | Mô tả |
|---|---|---|
| platformrequired | string | Nền tảng: facebook, instagram, ... |
| profile_urlrequired | string | Đường dẫn hồ sơ công khai |
| display_namerequired | string | Tên hiển thị trên nền tảng đó |
{
"id": "ACC-205",
"platform": "instagram",
"profile_url": "https://instagram.com/minhanh.photo",
"display_name": "minhanh.photo",
"verified": false,
"verification_status": "pending",
"created_at": "2025-10-09T12:00:00Z"
}
Mở tranh chấp
Mở tranh chấp cho một nhiệm vụ bị từ chối oan, người tạo không phản hồi, hoặc nghi ngờ gian lận. Phải mở trong vòng 72 giờ kể từ khi nhiệm vụ kết thúc.
| Trường | Kiểu | Mô tả |
|---|---|---|
| task_idrequired | string | ID nhiệm vụ liên quan |
| reasonrequired | string | rejected_unfairly, creator_unresponsive, worker_not_completed, fraud_suspected, other |
| descriptionrequired | string | Mô tả chi tiết (tối thiểu 30, tối đa 1000 ký tự) |
| evidence_urlsoptional | string[] | Danh sách link ảnh bằng chứng (tối đa 5) |
{
"id": "DC-2100",
"task_id": "T-2015",
"status": "pending",
"estimated_resolution_days": 7,
"created_at": "2025-10-09T12:05:00Z"
}
Danh sách tranh chấp
Trả về danh sách tranh chấp user đã mở hoặc bị liên quan, kèm trạng thái và kết quả xử lý.
| Tham số | Kiểu | Mô tả |
|---|---|---|
| statusoptional | string | pending, reviewing, resolved, rejected |
{
"data": [
{
"id": "DC-2041",
"task_id": "T-2015",
"reason": "rejected_unfairly",
"status": "reviewing",
"opened_at": "2025-10-07T14:22:00Z",
"estimated_resolution_at": "2025-10-14T14:22:00Z"
}
],
"summary": {
"pending": 1,
"reviewing": 1,
"resolved": 5,
"rejected": 1
}
}
Mã lỗi HTTP
Mọi response lỗi đều có cấu trúc JSON: { "error": { "code": "...", "message": "..." } }. Dưới đây là các mã lỗi phổ biến nhất.
Retry-After.
{
"error": {
"code": "insufficient_balance",
"message": "Số dư không đủ để tạo nhiệm vụ. Cần 163 Credits, hiện có 97.",
"details": {
"required": 163,
"available": 97
}
}
}