Dành cho lập trình viên & reseller

Like3s API — hai chuẩn, một hạ tầng.

Tích hợp Like3s vào hệ thống của bạn theo cách phù hợp nhất. v1 là REST API hiện đại; v2 tuân thủ chuẩn SMM Panel — chuyển từ panel cũ chỉ cần đổi URL.

Giới thiệuv1

Like3s API v1 là REST hiện đại — JSON, Bearer API key, HTTP status có ý nghĩa. Phù hợp khi bạn xây dự án mới, mobile app, hoặc tích hợp lâu dài. Mặc định trả VND; gửi header Accept-Currency: USD để nhận USD (quy đổi theo tỷ giá thực).

Base URL

api.like3s.vn

HTTPS bắt buộc · TLS 1.2+

Prefix

/api/v1

REST · JSON · UTF-8

Rate limit

120 / phút

20.000 / ngày mỗi API key

Pagination

Cursor-based

Orders & transactions

POSThttps://api.like3s.vn/api/v1/orders

Xác thực

Mọi request phải đính kèm Bearer API key trong header Authorization. Key được tạo tại Dashboard → API Keys; mỗi key gắn với một tài khoản, có thể giới hạn theo IP và scope.

Headers chuẩn

Authorization:   Bearer 3kQp7xN2hVfL8mYwB1tRzAcEgUjK5sDoXrM4nPiF
Content-Type:    application/json
Accept:          application/json
Accept-Currency: VND                                       // optional · VND | USD · mặc định VND
Idempotency-Key: a8d3f1e2-b4c5-6789-0123-456789abcdef     // optional cho POST /orders
                                                           // BẮT BUỘC cho POST /orders/bulk và /orders/{id}/refill

Không bao giờ commit API key vào git. Key là chuỗi ngẫu nhiên 40 ký tự base62 (A–Z, a–z, 0–9), không prefix. Hệ thống chỉ lưu SHA-256 hash — mất key thì phải rotate (cấp key mới).

Tiền tệ & quy đổi

Mặc định, mọi field tiền (balance, rate, charge, refunded) trả về VND. Gửi header Accept-Currency: USD để nhận USD — backend quy đổi từ VND theo tỷ giá nội bộ (cập nhật 4 giờ một lần).

Ví dụ

GET /api/v1/account/balance
Accept-Currency: USD

// → { "balance": 51.2345, "currency": "USD" }

GET /api/v1/account/balance
// (không header)

// → { "balance": 1286420, "currency": "VND" }

Field currency luôn xuất hiện trong response — kiểm tra field này thay vì giả định đơn vị.

Mã lỗi & HTTP status

v1 dùng HTTP status codes chuẩn. Body lỗi luôn có cấu trúc { code, message }.

Status	Code	Ý nghĩa
200	OK	Request thành công, body chứa resource.
400	INVALID_STATUS · VALIDATION	Body sai format hoặc query param không hợp lệ.
401	UNAUTHORIZED	API key thiếu / sai / bị revoke.
402	INSUFFICIENT_BALANCE	Số dư ví không đủ để hold tiền đơn.
404	NOT_FOUND	Order / service / variant không tồn tại hoặc không thuộc tài khoản.
409	IDEMPOTENCY_CONFLICT	`Idempotency-Key` đã dùng cho request khác.
422	SERVICE_UNAVAILABLE	Service tạm ngưng — thử lại sau hoặc chọn variant tương đương.
429	RATE_LIMITED	Vượt rate limit. Đọc header `Retry-After`.
500	INTERNAL_ERROR	Lỗi server. Đã log & cảnh báo on-call.

Error body · ví dụ

{
  "code":    "INSUFFICIENT_BALANCE",
  "message": "Số dư ví 12.400 ₫ — đơn yêu cầu 95.000 ₫."
}

Rate limit

Mỗi API key có giới hạn 120 request / phút và 20.000 request / ngày. Tài khoản reseller có thể nâng cao hơn khi liên hệ. Khi vượt giới hạn, server trả 429 Too Many Requests kèm header Retry-After.

Mọi response thành công đều kèm header dưới để client throttle proactively — không cần đoán quota còn lại:

Response headers

X-RateLimit-Limit:     120          // quota tối đa trong window 1 phút
X-RateLimit-Remaining: 118          // còn lại trong window hiện tại
X-RateLimit-Reset:     1747387260   // epoch seconds tới đầu window kế tiếp

Giảm X-RateLimit-Remaining mỗi khi gần 0 và pause cho đến X-RateLimit-Reset — rẻ hơn nhiều so với bị 429 rồi retry.

Danh sách platforms

Trả về tất cả platform khả dụng (Facebook, Instagram, TikTok, YouTube, Twitter, Shopee...). Dùng để build menu chọn hoặc filter ở phía client.

GET/api/v1/platforms

Request

curl

curl "https://api.like3s.vn/api/v1/platforms" \
  -H "Authorization: Bearer 3kQp7xN2hVfL8mYwB1tRzAcEgUjK5sDoXrM4nPiF"

Response

200 OK

Body

[
  {
    "id":      1,
    "code":    "FACEBOOK",
    "slug":    "facebook",
    "name":    "Facebook",
    "iconUrl": "https://cdn.like3s.vn/platforms/facebook.svg"
  },
  {
    "id":      2,
    "code":    "INSTAGRAM",
    "slug":    "instagram",
    "name":    "Instagram",
    "iconUrl": "https://cdn.like3s.vn/platforms/instagram.svg"
  }
  // ...
]

Danh sách services

Trả về toàn bộ "service" khả dụng — mỗi service tương ứng một variant đặt được. Field id chính là giá trị bạn truyền vào service khi tạo đơn.

GET/api/v1/services

Request

Example

curl "https://api.like3s.vn/api/v1/services" \
  -H "Authorization: Bearer 3kQp7xN2hVfL8mYwB1tRzAcEgUjK5sDoXrM4nPiF"

Response

200 OK

Body

[
  {
    "id":        103,                          // variantId · dùng làm "service" khi POST /orders
    "packageId": 27,
    "name":      "FB Like bài viết — Gói cơ bản",
    "type":      "DEFAULT",                    // service-type
    "category":  "Gói cơ bản",                 // tên package
    "rate":      21000,                        // giá cho 1000 đơn vị
    "min":       100,
    "max":       50000,
    "refill":    true,
    "currency":  "VND"
  }
  // ...
]

Field	Kiểu	Bắt buộc	Mô tả
`id`	integer	Không	ID variant. Dùng làm `service` khi POST /orders.
`packageId`	integer	Không	Package chứa variant này (nhiều variant có thể chung 1 package).
`name`	string	Không	Tên hiển thị (gộp `packageName` + `variantLabel`).
`type`	string	Không	Service-type: `DEFAULT`, `MINUTES`, `REACTIONS_SINGLE`, `SUBSCRIPTION`, ...
`category`	string	Không	Tên package — gom variant theo nhóm trong UI.
`rate`	number	Không	Giá cho 1000 đơn vị, theo currency yêu cầu.
`min / max`	integer	Không	Khoảng `quantity` được phép.
`refill`	boolean	Không	Service có hỗ trợ bù không (auto-monitor trong 30 ngày).
`currency`	string	Không	`VND` mặc định, hoặc `USD` nếu gửi `Accept-Currency: USD`.

Chi tiết một service

GET/api/v1/services/{id}

Lấy chi tiết một variant theo id. Response shape giống endpoint list. Trả 404 nếu variant không tồn tại / không khả dụng.

Service theo slug

GET/api/v1/services/by-slug/{slug}

Resolve service theo slug — khớp URL FE /dich-vu/{slug}. Trả về service kèm tất cả packages và variants nested — đủ để render form đặt đơn trong 1 round-trip.

Request

curl

curl "https://api.like3s.vn/api/v1/services/by-slug/tang-like-bai-viet-facebook" \
  -H "Authorization: Bearer 3kQp7xN2hVfL8mYwB1tRzAcEgUjK5sDoXrM4nPiF"

Response

200 OK

Body

{
  "id":               12,
  "slug":             "tang-like-bai-viet-facebook",
  "name":             "Tăng like bài viết Facebook",
  "platformCode":     "FACEBOOK",
  "platformSlug":     "facebook",
  "descriptionShort": "Like Việt thật, an toàn, giữ lâu.",
  "defaultPackageId": 27,
  "packages": [
    {
      "id":               27,
      "serviceId":        12,
      "name":             "Gói cơ bản",
      "descriptionShort": "Like Việt mix, giao 100/giờ",
      "type":             "DEFAULT",
      "unitLabel":        "like",
      "allowScheduled":   true,
      "variants": [
        {
          "id":     103,
          "label":  null,
          "rate":   21000,
          "min":    100,
          "max":    50000,
          "refill": true,
          "cancel": true,
          "data":   {}
        }
      ]
    },
    {
      "id":               28,
      "serviceId":        12,
      "name":             "Gói premium",
      "descriptionShort": "Like Việt 100%, giữ ≥ 30 ngày",
      "type":             "DEFAULT",
      "unitLabel":        "like",
      "allowScheduled":   true,
      "variants": [
        { "id": 104, "label": null, "rate": 49000, "min": 50, "max": 20000, "refill": true, "cancel": true, "data": {} }
      ]
    }
  ]
}

Variant DEFAULT có data: {}. MINUTES/REACTIONS_SINGLE có discriminator trong data (vd { "duration_min": 60 }, { "reaction": "LIKE" }) — copy nguyên vào typeData khi POST /orders.

Package theo id

GET/api/v1/packages/{id}

Lấy 1 package kèm variants nested. Phù hợp khi bạn đã lưu packageId từ trước (vd từ /services/by-slug) và muốn fetch lại không cần slug.

Response

200 OK

Body

{
  "id":               27,
  "serviceId":        12,
  "name":             "Gói cơ bản",
  "descriptionShort": "Like Việt mix, giao 100/giờ",
  "type":             "DEFAULT",
  "unitLabel":        "like",
  "allowScheduled":   true,
  "variants": [
    {
      "id":     103,
      "label":  null,
      "rate":   21000,
      "min":    100,
      "max":    50000,
      "refill": true,
      "cancel": true,
      "data":   {}
    }
  ]
}

Tài khoản & số dư

Hai endpoint để đọc thông tin tài khoản gắn với API key đang dùng — đầy đủ hoặc chỉ số dư.

GET/api/v1/account

200 OK

Response · GET /api/v1/account

{
  "id":       42,
  "email":    "[email protected]",
  "balance":  1286420,        // số dư khả dụng (đã trừ hold)
  "currency": "VND"
}

GET/api/v1/account/balance

Phiên bản gọn nhẹ — chỉ trả số dư khả dụng.

200 OK

Response · GET /api/v1/account/balance

{
  "balance":  1286420,
  "currency": "VND"
}

balance đã trừ phần đang hold cho đơn chưa hoàn tất — đây là số tiền bạn thực sự có thể dùng để tạo đơn mới.

Giao dịch ví

GET/api/v1/account/transactions

Lịch sử giao dịch ví của tài khoản — sự kiện ngữ nghĩa (DEPOSIT / SPEND / REFUND / BONUS / ADJUSTMENT), KHÔNG phải raw ledger. Mỗi sự kiện có title + description đã build sẵn để bạn render thẳng vào UI mà không cần parse reference.

Query parameters

Field	Kiểu	Bắt buộc	Mô tả
`cursor`	string	Không	Cursor opaque từ `nextCursor` response trước. Bỏ qua / để trống cho trang đầu.
`limit`	integer	Không	Số item / trang. Mặc định `50`, tối đa `200`.

Response

200 OK

Body

{
  "items": [
    {
      "id":           8472,
      "code":         "TXN-0008472",
      "kind":         "SPEND",
      "status":       "SUCCESS",
      "amount":       -21000,
      "balanceAfter": 1265420,
      "currency":     "VND",
      "title":        "Đặt đơn FB Like bài viết — Gói cơ bản #48294",
      "description":  "1.000 like · 21,00 ₫/like · facebook.com/like3s/posts/123",
      "orderId":      48294,
      "createdAt":    "2026-05-16T10:42:18+07:00"
    },
    {
      "id":           8401,
      "code":         "TXN-0008401",
      "kind":         "DEPOSIT",
      "status":       "SUCCESS",
      "amount":       500000,
      "balanceAfter": 1286420,
      "currency":     "VND",
      "title":        "Nạp tiền vào ví",
      "description":  "Vietcombank · Nội dung: NAP1234567",
      "orderId":      null,
      "createdAt":    "2026-05-15T22:15:03+07:00"
    }
  ],
  "nextCursor": "MjAyNi0wNS0xNVQyMjoxNTowMyswNzowMHw4NDAx"
}

Field	Kiểu	Bắt buộc	Mô tả
`kind`	string	Không	`DEPOSIT` (nạp) · `SPEND` (đặt đơn) · `REFUND` (hoàn) · `BONUS` (thưởng) · `ADJUSTMENT` (CSKH điều chỉnh).
`status`	string	Không	`SUCCESS` · `PENDING` · `FAILED`. Phase 1 luôn `SUCCESS`.
`amount`	number	Không	Số tiền giao dịch (có dấu — âm khi trừ). Theo currency yêu cầu.
`balanceAfter`	number	Không	Số dư khả dụng sau giao dịch — khớp `GET /account/balance`.
`title / description`	string	Không	Caption tiếng Việt đã build sẵn — render thẳng vào UI.
`orderId`	integer \| null	Không	Khi `kind = SPEND \| REFUND`: id đơn liên quan, dùng để correlate với `GET /orders/{id}`.
`nextCursor`	string \| null	Không	Truyền vào `?cursor=` để lấy trang kế. `null` = hết.

Hệ thống chỉ trả các sự kiện người dùng thấy — bước wallet nội bộ (capture hold thành debit) được ẩn để feed thuần ngữ nghĩa. balanceAfter luôn là số dư khả dụng (đã trừ tiền đang hold cho đơn chưa hoàn tất).

Tạo đơn mới

Endpoint quan trọng nhất. Hỗ trợ Idempotency-Key để retry an toàn — request trùng key sẽ trả về đơn cũ thay vì tạo đơn mới.

POST/api/v1/orders

Body parameters

Field	Kiểu	Bắt buộc	Mô tả
`service`	integer	Có	ID variant lấy từ `GET /api/v1/services`.
`link`	string	Có	URL công khai của bài viết / kênh / video. Tối đa 1000 ký tự.
`quantity`	integer	Có	Số lượng cần tăng. Phải nằm trong khoảng `[min, max]` của service.
`typeData`	object	Không	Discriminator phụ thuộc `type`: `{ "reaction": "LIKE" }` cho REACTIONS_SINGLE, `{ "duration_min": 60 }` cho MINUTES. Bỏ trống với DEFAULT.
`startTime`	string (ISO-8601)	Không	Đặt lịch chạy trong tương lai. `null` = chạy ngay.

Request

Example

curl "https://api.like3s.vn/api/v1/orders" \
  -X POST \
  -H "Authorization: Bearer 3kQp7xN2hVfL8mYwB1tRzAcEgUjK5sDoXrM4nPiF" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a8d3f1e2-b4c5-6789-..." \
  -d '{
    "service":  103,
    "link":     "https://facebook.com/like3s/posts/123",
    "quantity": 1000
  }'

Response

200 OK

Body

{
  "id":            48294,
  "service":       103,
  "link":          "https://facebook.com/like3s/posts/123",
  "quantity":      1000,
  "charge":        21000,                     // VND · đã hold khỏi ví
  "refunded":      0,
  "currency":      "VND",
  "status":        "PENDING",
  "startCount":    null,
  "remains":       1000,
  "failureReason": null,
  "createdAt":     "2026-05-16T10:42:18+07:00"
}

Tạo đơn hàng loạt

POST/api/v1/orders/bulk

Tạo 1-50 đơn cùng lúc chung một service, quantity, typeData, startTime — chỉ links là danh sách. Phù hợp khi cần đẩy cùng dịch vụ cho nhiều bài viết / kênh.

Idempotency-Key bắt buộc. Replay cùng key trả về batch cũ; gọi lại với cùng key nhưng số link khác → 409 IDEMPOTENCY_CONFLICT. Atomic ở bước tạo: nếu một link fail (vd số dư không đủ cho đơn thứ 35) thì toàn batch rollback — không có đơn nào được lưu.

Body parameters

Field	Kiểu	Bắt buộc	Mô tả
`service`	integer	Có	ID variant — áp dụng cho mọi link.
`links`	array<string>	Có	1-50 link. Mỗi link tối đa 1000 ký tự. Link trùng nhau trong batch → `DUPLICATE_LINK`.
`quantity`	integer	Có	Quantity áp dụng cho mọi đơn trong batch.
`typeData`	object	Không	Discriminator service-type (xem POST /orders). Áp cho mọi đơn.
`startTime`	string (ISO-8601)	Không	Đặt lịch chạy cho mọi đơn. null = chạy ngay.

Request

curl

curl "https://api.like3s.vn/api/v1/orders/bulk" \
  -X POST \
  -H "Authorization: Bearer 3kQp7xN2hVfL8mYwB1tRzAcEgUjK5sDoXrM4nPiF" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: batch-2026-05-16-001" \
  -d '{
    "service":  103,
    "links": [
      "https://facebook.com/like3s/posts/1",
      "https://facebook.com/like3s/posts/2",
      "https://facebook.com/like3s/posts/3"
    ],
    "quantity": 500
  }'

Response

200 OK

Body

{
  "orders": [
    { "id": 48311, "service": 103, "link": "https://facebook.com/like3s/posts/1",
      "quantity": 500, "charge": 10500, "refunded": 0, "currency": "VND",
      "status": "PENDING", "startCount": null, "remains": 500,
      "failureReason": null, "createdAt": "2026-05-16T10:50:02+07:00" },
    { "id": 48312, "service": 103, "link": "https://facebook.com/like3s/posts/2",
      "quantity": 500, "charge": 10500, "refunded": 0, "currency": "VND",
      "status": "PENDING", "startCount": null, "remains": 500,
      "failureReason": null, "createdAt": "2026-05-16T10:50:02+07:00" },
    { "id": 48313, "service": 103, "link": "https://facebook.com/like3s/posts/3",
      "quantity": 500, "charge": 10500, "refunded": 0, "currency": "VND",
      "status": "PENDING", "startCount": null, "remains": 500,
      "failureReason": null, "createdAt": "2026-05-16T10:50:02+07:00" }
  ],
  "totalCharge": 31500,
  "currency":    "VND"
}

Thứ tự orders giữ y request.links (index ↔ index). Sau khi tạo, mỗi đơn xử lý độc lập — 1 đơn provider từ chối chỉ đơn đó FAILED + auto refund, các đơn khác không bị kéo theo.

Danh sách đơn

GET/api/v1/orders

Lấy danh sách đơn của tài khoản — cursor pagination để xuyên qua dữ liệu dài hiệu quả (orders partition theo tháng nên offset đắt). Sort cố định mới nhất trước.

Query parameters

Field	Kiểu	Bắt buộc	Mô tả
`cursor`	string	Không	Cursor opaque từ `nextCursor` response trước. Bỏ qua cho trang đầu.
`limit`	integer	Không	Số item / trang. Mặc định `50`, tối đa `200`.
`status`	string	Không	Lọc theo trạng thái (uppercase): `PENDING`, `PROCESSING`, `IN_PROGRESS`, `COMPLETED`, `PARTIAL`, `CANCELED`, `FAILED`.

Response

200 OK

Body

{
  "items": [
    {
      "id":          48294,
      "service":     103,
      "link":        "https://facebook.com/like3s/posts/123",
      "quantity":    1000,
      "charge":      21000,
      "refunded":    0,
      "currency":    "VND",
      "status":      "PROCESSING",
      "startCount":  128,
      "remains":     358,
      "failureReason": null,
      "createdAt":   "2026-05-16T10:42:18+07:00"
    }
    // ...
  ],
  "nextCursor": "MjAyNi0wNS0xNlQwOToxNTozMCswNzowMHw0ODI2OA"
}

nextCursor là string opaque — đừng parse. Truyền lại nguyên vẹn vào ?cursor= cho trang kế. Khi nextCursor = null, bạn đã hết dữ liệu.

Chi tiết đơn

GET/api/v1/orders/{id}

Lấy chi tiết một đơn theo id. Response shape giống item trong list. Trả 404 nếu đơn không thuộc tài khoản.

200 OK

Response

{
  "id":            48294,
  "service":       103,
  "link":          "https://facebook.com/like3s/posts/123",
  "quantity":      1000,
  "charge":        21000,
  "refunded":      0,
  "currency":      "VND",
  "status":        "IN_PROGRESS",
  "startCount":    128,
  "remains":       358,
  "failureReason": null,
  "createdAt":     "2026-05-16T10:42:18+07:00"
}

Field	Kiểu	Bắt buộc	Mô tả
`status`	string	Không	`PENDING` · `PROCESSING` · `IN_PROGRESS` · `COMPLETED` · `PARTIAL` · `CANCELED` · `FAILED`
`startCount`	integer \| null	Không	Số liệu tại thời điểm bắt đầu xử lý (null khi chưa chạy).
`remains`	integer	Không	Số lượng còn lại chưa giao.
`charge`	number	Không	Số tiền đã hold/trừ khỏi ví (theo currency yêu cầu).
`refunded`	number	Không	Phần đã hoàn lại ví khi đơn PARTIAL / CANCELED / FAILED.
`failureReason`	string \| null	Không	Lý do hệ thống khi đơn FAILED.

Huỷ đơn

POST/api/v1/orders/{id}/cancel

Yêu cầu huỷ đơn. Đơn chuyển trạng thái sang CANCELED (hoặc PARTIAL nếu đã giao một phần). Phần chưa giao được hoàn về ví.

200 OK

Response

{
  "id":            48294,
  "service":       103,
  "link":          "https://facebook.com/like3s/posts/123",
  "quantity":      1000,
  "charge":        21000,
  "refunded":      18900,           // phần chưa giao hoàn về ví
  "currency":      "VND",
  "status":        "CANCELED",
  "startCount":    128,
  "remains":       900,
  "failureReason": null,
  "createdAt":     "2026-05-16T10:42:18+07:00"
}

Huỷ là yêu cầu — đơn có thực sự huỷ được hay không phụ thuộc trạng thái xử lý. Đơn đã chạy gần xong có thể tiếp tục đến khi hoàn tất.

Yêu cầu refill

POST/api/v1/orders/{id}/refill

Yêu cầu chạy lại đơn đã COMPLETED hoặc PARTIAL — phù hợp khi like/follow tụt sau khi giao. Chỉ áp dụng cho variant có refill: true và còn trong thời hạn bảo hành (snapshot tại thời điểm tạo đơn).

Idempotency-Key bắt buộc. Reuse cùng key trả về request cũ — an toàn khi client retry. Rate limit 24h per đơn: gọi liên tục cùng order chỉ 1 refill request mỗi 24 giờ.

Request

curl

curl "https://api.like3s.vn/api/v1/orders/48294/refill" \
  -X POST \
  -H "Authorization: Bearer 3kQp7xN2hVfL8mYwB1tRzAcEgUjK5sDoXrM4nPiF" \
  -H "Idempotency-Key: refill-48294-001"

Response

200 OK

Body

{
  "id":            48294,
  "service":       103,
  "link":          "https://facebook.com/like3s/posts/123",
  "quantity":      1000,
  "charge":        21000,
  "refunded":      0,
  "currency":      "VND",
  "status":        "COMPLETED",
  "startCount":    128,
  "remains":       0,
  "failureReason": null,
  "createdAt":     "2026-05-16T10:42:18+07:00"
}

Order status không đổi — refill request được tạo song song; hệ thống xử lý async qua worker. Refill miễn phí trong thời hạn bảo hành (không trừ ví).

Code	Ý nghĩa
REFILL_NOT_SUPPORTED	Variant không hỗ trợ refill (refill: false).
WARRANTY_EXPIRED	Đã hết thời hạn bảo hành (snapshot khi tạo đơn).
REFILL_IN_PROGRESS	Đã có refill request đang xử lý cho đơn này — đợi xử lý xong.
REFILL_RATE_LIMITED	Đã yêu cầu refill cho đơn này trong 24h vừa qua.
INVALID_STATUS	Chỉ áp dụng cho đơn COMPLETED hoặc PARTIAL.

Sắp ra mắt

Các capability dưới đang phát triển — endpoint cụ thể và shape có thể thay đổi trước khi GA.

Feature	Ý nghĩa
Webhooks (order events)	Subscribe order.created / processing / progress / completed / partial / failed — HMAC-SHA256 ký request. Config qua Dashboard, không qua API.
Scope-based API keys	Giới hạn key theo scope (services:read / orders:create / account:read) — hiện key có full quyền tài khoản.
SDK chính thức	TypeScript, Python, PHP — auto-gen từ OpenAPI spec.