TRAMTUONGTAC / Developers v1 · ổn định
API Reference Hướng dẫn SDK Changelog
REST API v1

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.

Base URL https://api.TRAMTUONGTAC.app/v1

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.

POST /auth/token

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.

CẢNH BÁO

Không bao giờ để lộ api_secret ở client-side. Chỉ gọi endpoint này từ server của bạn.

Request body
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.
Ví dụ request
cURL
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"]
  }'
Response 200 OK
application/json 200 OK
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": ["tasks:read", "tasks:write", "credits:read"]
}
GET /tasks

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.

Query parameters
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.
Ví dụ request
cURL
curl "https://api.TRAMTUONGTAC.app/v1/tasks?platform=facebook&min_reward=10&sort=reward_desc" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Response 200 OK
application/json 200 OK
{
  "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
  }
}
GET /tasks/{task_id}

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.

Path parameters
Tham số Kiểu Mô tả
task_idrequired string ID nhiệm vụ, dạng T-XXXX
Response 200 OK
application/json 200 OK
{
  "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"
}
POST /tasks/{task_id}/accept

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.

GHI CHÚ

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.

Request body
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ụ
Response 201 Created
application/json 201 Created
{
  "assignment_id": "A-5032",
  "task_id": "T-2101",
  "account_id": "ACC-201",
  "status": "in_progress",
  "expires_at": "2025-10-09T14:22:00Z",
  "reward": 12
}
POST /tasks/{task_id}/complete

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.

Request body
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ự)
Ví dụ request
cURL
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"
  }'
Response 202 Accepted
application/json 202 Accepted
{
  "submission_id": "SUB-8801",
  "assignment_id": "A-5032",
  "status": "verifying",
  "verification_type": "automatic",
  "estimated_time_seconds": 180,
  "reward_pending": 12
}
GHI CHÚ

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.

Polling kết quả
GET /submissions/SUB-8801
{
  "submission_id": "SUB-8801",
  "status": "verified",
  "verified_at": "2025-10-09T11:30:45Z",
  "credits_awarded": 12,
  "new_balance": 272
}
GET /me/tasks

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.

Query parameters
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
Response 200 OK
application/json 200 OK
{
  "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
  }
}
POST /tasks

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.

LƯU Ý

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.

Request body
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)
Response 201 Created
application/json 201 Created
{
  "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"
}
PATCH /tasks/{task_id}

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.

Request body
Trường Kiểu Mô tả
statusrequired string paused hoặc active
Response 200 OK
application/json 200 OK
{
  "id": "T-2150",
  "status": "paused",
  "updated_at": "2025-10-09T11:45:00Z"
}
GET /me

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.

Response 200 OK
application/json 200 OK
{
  "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"
}
GET /me/balance

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.

Response 200 OK
application/json 200 OK
{
  "available": 260,
  "held": 163,
  "pending": 24,
  "total": 447,
  "updated_at": "2025-10-09T11:00:00Z"
}
GET /me/transactions

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.

Query parameters
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
Response 200 OK
application/json 200 OK
{
  "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
  }
}
GET /me/trust-score

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.

Response 200 OK
application/json 200 OK
{
  "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"
}
GET /me/accounts

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ụ).

Response 200 OK
application/json 200 OK
{
  "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"
    }
  ]
}
POST /me/accounts

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.

Request body
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 đó
Response 201 Created
application/json 201 Created
{
  "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"
}
POST /disputes

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.

Request body
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)
Response 201 Created
application/json 201 Created
{
  "id": "DC-2100",
  "task_id": "T-2015",
  "status": "pending",
  "estimated_resolution_days": 7,
  "created_at": "2025-10-09T12:05:00Z"
}
GET /disputes

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ý.

Query parameters
Tham số Kiểu Mô tả
statusoptional string pending, reviewing, resolved, rejected
Response 200 OK
application/json 200 OK
{
  "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
  }
}
ERR Mã lỗi

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.

400
Bad Request Tham số không hợp lệ hoặc thiếu trường bắt buộc.
401
Unauthorized Token hết hạn, sai, hoặc thiếu header Authorization.
403
Forbidden Token không có quyền truy cập tài nguyên này.
404
Not Found Tài nguyên không tồn tại hoặc đã bị xoá.
409
Conflict Xung đột trạng thái, ví dụ nhiệm vụ đã hết suất hoặc đã nhận trước đó.
422
Unprocessable Entity Request đúng định dạng nhưng vi phạm business rule (VD: không đủ Credits).
429
Too Many Requests Vượt rate limit. Chờ theo header Retry-After.
500
Internal Server Error Lỗi hệ thống. Vui lòng retry sau vài giây.
Ví dụ response lỗi
application/json 422 Unprocessable Entity
{
  "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
    }
  }
}
Thành công