Tài liệu API

Truy cập lập trình đến số ảo, đơn hàng và số dư tài khoản.

Khuyến nghị

Bắt đầu với SDK chính thức

Dùng SDK TypeScript/JavaScript hoặc Python cho tích hợp mới. Cả hai SDK mặc định dùng API công khai /v2, giữ idempotency key qua các lần retry an toàn, cung cấp typed errors và giữ vòng đời OTP nhất quán.

OpenAPI Hướng dẫn AI Mã nguồn SDK

Tạo an toàn

Tạo đơn hàng bằng product_id cho một ô mức giá chính xác và ổn định, hoặc bằng catalog_product_id, operator_id tùy chọn, min_price/max_price và khóa idempotency để các lệnh gọi trả phí có định tuyến an toàn khi thử lại.

catalog_product_idmax_priceIdempotency-Key

Dùng OTP

Chờ OTP, gửi mã trong app đích, rồi gọi finish để đóng order.

waitForOtpwait_for_otpfinish

Chỉ resend khi cần

Sau khi resend, chờ mã mới bằng afterCode trong TypeScript hoặc after_code trong Python.

can_resendresend_available_at

import { SmscodeClient, OtpTimeoutError } from "@smscode/sdk";

const client = new SmscodeClient({ token: process.env.SMSCODE_TOKEN! });

let orderId: number | undefined;

try {
  const created = await client.orders.create({
    catalog_product_id: Number(process.env.SMSCODE_CATALOG_PRODUCT_ID),
    max_price: "0.50",
    quantity: 1,
  });

  const order = created.orders[0]!;
  orderId = order.id;
  const first = await client.orders.waitForOtp(orderId, { timeoutMs: 120_000 });

  console.log(first.otpCode); // Gửi mã này trong app đích.
  await client.orders.finish(orderId);
} catch (err) {
  if (err instanceof OtpTimeoutError && orderId !== undefined) {
    const current = await client.orders.get(orderId);
    if (current.can_cancel) await client.orders.cancel(orderId);
  }
  throw err;
}

import os

from smscode import OtpTimeoutError, SmscodeClient

with SmscodeClient(token=os.environ["SMSCODE_TOKEN"]) as client:
    created = client.orders.create(
        catalog_product_id=int(os.environ["SMSCODE_CATALOG_PRODUCT_ID"]),
        max_price="0.50",
        quantity=1,
    )

    order = created.orders[0]
    order_id = int(order["id"])

    try:
        first = client.orders.wait_for_otp(order_id, timeout_ms=120_000)
        print(first.otp_code)  # Gửi mã này trong app đích.
        client.orders.finish(order_id)
    except OtpTimeoutError:
        current = client.orders.get(order_id)
        if current["can_cancel"]:
            client.orders.cancel(order_id)
        raise

Dùng can_resend và resend_available_at cho timing resend. Timestamp resend cấp thấp là nội bộ và không phải field response công khai.

Tong Quan

Tất cả trường tiền tệ trên API /v1 đều bằng IDR (Rupiah Indonesia), dưới dạng số nguyên — ví dụ "price": 15000 và "balance": 500000 nghĩa là Rp 15.000 và Rp 500.000. Để có bản chiếu USD-native của cùng một sổ cái, hãy chuyển sang API v2 bằng nút chuyển phiên bản ở trên.

⟩Xác thực

Tất cả yêu cầu API đều yêu cầu Bearer token. Tạo token từ Cài đặt tài khoản trong bảng điều khiển, sau đó đính kèm vào mỗi yêu cầu:

Authorization:Bearer YOUR_API_TOKEN

Yêu cầu không có token hợp lệ sẽ nhận phản hồi 401 UNAUTHORIZED.

⟩URL cơ sở

Tất cả đường dẫn endpoint bên dưới tương đối với:

https://api.smscode.gg/v1

⟩Định dạng phản hồi

Mọi phản hồi trả về JSON với cấu trúc nhất quán. Tất cả phản hồi bao gồm header x-request-id để gỡ lỗi.

Thành công
{
  "success": true,
  "data": { ... }
}

Lỗi
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message"
  }
}

GET/catalog/countries

Trả về danh sách tất cả quốc gia có sẵn.

Tham số

Không có

Ví dụ yêu cầu

curl -s https://api.smscode.gg/v1/catalog/countries \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v1/catalog/countries", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/catalog/countries",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": [
    {
      "id": 6,
      "code": "ID",
      "name": "Indonesia",
      "dial_code": "+62",
      "emoji": "🇮🇩",
      "active": true
    }
  ]
}

GET/catalog/services

Trả về danh sách dịch vụ (nền tảng) có sẵn. Có thể lọc theo quốc gia.

Tham số truy vấn

Tên	Kiểu	Bắt buộc	Mô tả
`country_id`	integer	Không	Lọc dịch vụ có sẵn cho quốc gia này

Ví dụ yêu cầu

curl -s "https://api.smscode.gg/v1/catalog/services?country_id=7" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v1/catalog/services?country_id=7", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/catalog/services",
    params={"country_id": 7},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": [
    {
      "id": 3,
      "code": "wa",
      "name": "WhatsApp",
      "active": true
    }
  ]
}

GET/catalog/operators

Trả về các nhà mạng có thể chọn cho một quốc gia + dịch vụ. Nếu cả nhà mạng thật và tồn kho Any đều khả dụng, phản hồi sẽ có một dòng Any với operator_id null; nếu không có sản phẩm theo nhà mạng, danh sách sẽ rỗng.

Tham số truy vấn

Tên	Kiểu	Bắt buộc	Mô tả
`country_id`	integer	Có	ID quốc gia
`platform_id`	integer	Có	ID nền tảng/dịch vụ

Ví dụ yêu cầu

curl -s "https://api.smscode.gg/v1/catalog/operators?country_id=7&platform_id=3" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const params = new URLSearchParams({
  country_id: "7", platform_id: "3",
});
const res = await fetch(`https://api.smscode.gg/v1/catalog/operators?${params}`, {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/catalog/operators",
    params={"country_id": 7, "platform_id": 3},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": [
    {
      "operator_id": null,
      "code": "any",
      "name": "Any",
      "local_name": null
    },
    {
      "operator_id": 433,
      "code": "axis",
      "name": "AXIS (XL Axiata)",
      "local_name": "AXIS (XL Axiata)"
    }
  ]
}

GET/catalog/products

Trả về danh sách phân trang các sản phẩm khả dụng. Lọc theo quốc gia, nền tảng và tùy chọn theo nhà mạng.

Tham số truy vấn

Tên	Kiểu	Bắt buộc	Mô tả
`country_id`	integer	Không	Lọc theo ID quốc gia
`platform_id`	integer	Không	Lọc theo ID nền tảng/dịch vụ
`operator_id`	integer	Không	ID nhà mạng tùy chọn từ /catalog/operators. Bỏ qua đối với sản phẩm Any.
`sort`	string	Không	Thứ tự sắp xếp: price_asc (mặc định), price_desc, available_asc, available_desc, name_asc, name_desc
`limit`	integer	Không	Số kết quả mỗi trang (1-10.000, mặc định 1.000)
`page`	integer	Không	Số trang (tối thiểu 1, mặc định 1)

Ví dụ yêu cầu

curl -s "https://api.smscode.gg/v1/catalog/products?country_id=7&platform_id=3&limit=10&page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const params = new URLSearchParams({
  country_id: "7", platform_id: "3", limit: "10", page: "1",
});
const res = await fetch(`https://api.smscode.gg/v1/catalog/products?${params}`, {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/catalog/products",
    params={"country_id": 7, "platform_id": 3, "limit": 10, "page": 1},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": [
    {
      "id": 142,
      "name": "WhatsApp Indonesia",
      "country_id": 7,
      "platform_id": 3,
      "catalog_product_id": 87,
      "operator_id": null,
      "operator_name": null,
      "available": 42,
      "price": 15000,
      "active": true
    }
  ],
  "meta": { "page": 1, "limit": 10, "count": 1 }
}

GET/catalog/exchange-rate

Trả về tỷ giá hối đoái USD/IDR hiện tại được dùng để chuyển đổi tiền tệ.

Tham số truy vấn

Tên	Kiểu	Bắt buộc	Mô tả
`pair`	string	Không	Cặp tiền tệ (mặc định: USD/IDR)

Ví dụ yêu cầu

curl -s "https://api.smscode.gg/v1/catalog/exchange-rate?pair=USD/IDR" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v1/catalog/exchange-rate?pair=USD/IDR", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/catalog/exchange-rate",
    params={"pair": "USD/IDR"},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "pair": "USD/IDR",
    "base_currency": "USD",
    "quote_currency": "IDR",
    "rate": 16250
  }
}

GET/balance

Trả về số dư tài khoản của người dùng đã xác thực.

Tham số

Không có

Ví dụ yêu cầu

curl -s https://api.smscode.gg/v1/balance \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v1/balance", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/balance",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "currency": "IDR",
    "balance": 500000
  }
}

GET/orders

Trả về danh sách đơn hàng của người dùng đã xác thực, sắp xếp theo mới nhất. Hỗ trợ lọc theo trạng thái và phân trang qua offset.

Tham số truy vấn

Tên	Kiểu	Bắt buộc	Mô tả
`limit`	integer	Không	Số kết quả tối đa (1-100, mặc định 20)
`offset`	integer	Không	Số kết quả bỏ qua (mặc định 0)
`status`	string	Không	Lọc theo trạng thái: ACTIVE, OTP_RECEIVED, COMPLETED, CANCELED, EXPIRED (không phân biệt hoa thường)

Ví dụ yêu cầu

curl -s "https://api.smscode.gg/v1/orders?limit=5&status=ACTIVE" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const params = new URLSearchParams({
  limit: "5", status: "ACTIVE", offset: "0",
});
const res = await fetch(`https://api.smscode.gg/v1/orders?${params}`, {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/orders",
    params={"limit": 5, "status": "ACTIVE", "offset": 0},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": [
    {
      "id": 1001,
      "status": "ACTIVE",
      "created_at": "2026-02-25T10:00:00+00:00",
      "product_id": 142,
      "catalog_product_id": 87,
      "phone_number": "+6281234567890",
      "amount": 15000,
      "otp_code": null,
      "otp_received_at": null,
      "expires_at": "2026-02-25T10:20:00+00:00",
      "canceled_at": null,
      "failed_reason": null,
      "operator_id": null,
      "operator_name": null
    }
  ]
}

GET/orders/{id}

Trả về một đơn hàng theo ID. Chỉ trả về đơn hàng của người dùng đã xác thực.

Tham số đường dẫn

Tên	Kiểu	Bắt buộc	Mô tả
`id`	integer	Có	Mã đơn hàng (tham số đường dẫn)

Ví dụ yêu cầu

curl -s https://api.smscode.gg/v1/orders/1001 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v1/orders/1001", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/orders/1001",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "id": 1001,
    "status": "OTP_RECEIVED",
    "created_at": "2026-02-25T10:00:00+00:00",
    "product_id": 142,
    "catalog_product_id": 87,
    "phone_number": "+6281234567890",
    "amount": 15000,
    "otp_code": "123456",
    "otp_received_at": "2026-02-25T10:05:00+00:00",
    "expires_at": "2026-02-25T10:20:00+00:00",
    "canceled_at": null,
    "failed_reason": null,
    "operator_id": null,
    "operator_name": null
  }
}

GET/orders/active

Liệt kê tất cả đơn hàng đang hoạt động (ACTIVE + OTP_RECEIVED). Sử dụng để theo dõi cập nhật trạng thái OTP.

Tham số

Không có

Ví dụ yêu cầu

curl -s https://api.smscode.gg/v1/orders/active \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v1/orders/active", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/orders/active",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": [
    {
      "id": 1001,
      "status": "OTP_RECEIVED",
      "otp_code": null,
      "otp_message": "Confirm your login: https://example.com/confirm",
      "sms_revision": 1,
      "otp_received_at": "2026-02-25T10:05:00+00:00",
      "expires_at": "2026-02-25T10:20:00+00:00",
      "failed_reason": null
    },
    {
      "id": 1002,
      "status": "ACTIVE",
      "otp_code": null,
      "otp_message": null,
      "sms_revision": 0,
      "otp_received_at": null,
      "expires_at": "2026-02-25T10:50:00+00:00",
      "failed_reason": null
    }
  ]
}

POST/orders/create

Tạo đơn hàng số ảo mới. Tự động trừ số dư. Hỗ trợ header Idempotency-Key tùy chọn để tránh tạo đơn trùng lặp khi thử lại do lỗi mạng.

Nội dung yêu cầu

Tên	Kiểu	Bắt buộc	Mô tả
`product_id`	integer	Không	ID sản phẩm của ô mức giá chính xác và ổn định để đặt trực tiếp. Chỉ gửi MỘT trong hai: giá trị này hoặc catalog_product_id, không gửi cả hai.
`catalog_product_id`	integer	Không	ID umbrella quốc gia+nền tảng cho đặt hàng có định tuyến. Máy chủ chọn một mức giá hiện tại phù hợp. Gửi giá trị này hoặc product_id.
`operator_id`	integer	Không	ID nhà mạng tùy chọn từ /catalog/operators. Chỉ hợp lệ với catalog_product_id; bỏ qua đối với Any.
`min_price`	integer	Không	Giá sàn tùy chọn. Số nguyên IDR. Chỉ hợp lệ với catalog_product_id.
`max_price`	integer	Không	Giá trần tùy chọn. Số nguyên IDR. Chỉ hợp lệ với catalog_product_id.
`prefer_provider`	string	Không	Mã nhà cung cấp tùy chọn được ưu tiên khi các ưu đãi ngang nhau.
`policy`	string	Không	Chính sách định tuyến tùy chọn, chỉ hợp lệ khi dùng catalog_product_id. Giá trị: cheapest (mặc định) chọn ưu đãi tốt có giá thấp nhất; best_success xếp hạng các ưu đãi theo tỷ lệ giao thành công gần đây trước. best_success chấm điểm mỗi nhà cung cấp theo tỷ lệ đơn nhận được OTP trong 30 ngày trọn vẹn gần nhất, theo dải 10%, và chỉ tính một nhà cung cấp khi họ có ít nhất 20 đơn trong khoảng đó — nhà cung cấp dưới ngưỡng này hoặc chưa có lịch sử được coi là trung tính, nên các ưu đãi mới không bao giờ bị bỏ rơi (tùy chọn; tín hiệu khởi đầu ở mức trung tính). Khi prefer_provider cũng được đặt, nhà cung cấp ưu tiên vẫn được xếp trước.
`quantity`	integer	Không	Số lượng (1-100, mặc định 1)

Truyền header Idempotency-Key để thử lại an toàn mà không tạo đơn trùng lặp. Key có thể chứa chữ cái, chữ số, dấu gạch ngang và gạch dưới (A-Z a-z 0-9 _ -), tối đa 128 ký tự; key không hợp lệ sẽ bị từ chối với 422 VALIDATION_ERROR. Thử lại với cùng key và cùng body sẽ phát lại kết quả ban đầu (bao gồm failed_count khi thành công một phần). Lần thử lại đã đến nhà cung cấp nhưng thất bại sẽ được ghi lại và phát lại đúng lỗi đó — hãy dùng key MỚI để thử lại. Lỗi không có tác dụng phụ (không đủ số dư, không có ưu đãi khả dụng) sẽ giải phóng key, nên bạn có thể nạp tiền và thử lại với cùng key. Dùng lại một key với body khác sẽ trả về 422 IDEMPOTENCY_KEY_REUSED, và yêu cầu vẫn đang xử lý với key đó sẽ trả về 409 REQUEST_IN_PROGRESS. Trường failed_reason trong phản hồi create luôn là null — nó chỉ được điền khi poll/liệt kê đơn hàng.

Ví dụ yêu cầu

curl -s -X POST https://api.smscode.gg/v1/orders/create \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{"product_id":142,"quantity":1}'

# Or route by catalog_product_id — the server picks a current tier.
# product_id is the stable exact tier-slot id. catalog_product_id is the
# country+platform umbrella for routed ordering. Optional min_price/max_price
# bound the tier; operator_id scopes to a carrier from /catalog/operators.
# Pass EITHER product_id OR catalog_product_id.
curl -s -X POST https://api.smscode.gg/v1/orders/create \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-124" \
  -d '{"catalog_product_id":87,"min_price":12000,"max_price":20000,"operator_id":433}'

const res = await fetch("https://api.smscode.gg/v1/orders/create", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
    "Idempotency-Key": "unique-request-id-123",
  },
  body: JSON.stringify({ product_id: 142, quantity: 1 }),
});
const data = await res.json();

import requests

res = requests.post("https://api.smscode.gg/v1/orders/create",
    json={"product_id": 142, "quantity": 1},
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Idempotency-Key": "unique-request-id-123",
    })
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": 1002,
        "status": "ACTIVE",
        "product_id": 142,
        "catalog_product_id": 87,
        "amount": 15000,
        "phone_number": "+6281234567891",
        "otp_code": null,
        "otp_received_at": null,
        "expires_at": "2026-02-25T10:50:00+00:00",
        "failed_reason": null,
        "operator_id": null,
        "operator_name": null
      }
    ],
    "failed_count": 0
  }
}

POST/orders/cancel

Hủy đơn hàng đang hoạt động. Phí thuê sẽ được hoàn vào số dư tài khoản.

Nội dung yêu cầu

Tên	Kiểu	Bắt buộc	Mô tả
`id`	integer	Có	Mã đơn hàng cần hủy

Ví dụ yêu cầu

curl -s -X POST https://api.smscode.gg/v1/orders/cancel \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":1001}'

const res = await fetch("https://api.smscode.gg/v1/orders/cancel", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ id: 1001 }),
});
const data = await res.json();

import requests

res = requests.post("https://api.smscode.gg/v1/orders/cancel",
    json={"id": 1001},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "order_id": 1001,
    "status": "CANCELED",
    "refund_amount": 15000,
    "new_balance": 515000
  }
}

POST/orders/finish

Đánh dấu đơn hàng đã hoàn thành sau khi nhận OTP. Giải phóng số ngay lập tức thay vì đợi hết hạn.

Nội dung yêu cầu

Tên	Kiểu	Bắt buộc	Mô tả
`id`	integer	Có	Mã đơn hàng cần hoàn thành

Ví dụ yêu cầu

curl -s -X POST https://api.smscode.gg/v1/orders/finish \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":1001}'

const res = await fetch("https://api.smscode.gg/v1/orders/finish", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ id: 1001 }),
});
const data = await res.json();

import requests

res = requests.post("https://api.smscode.gg/v1/orders/finish",
    json={"id": 1001},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "order_id": 1001,
    "status": "COMPLETED"
  }
}

POST/orders/resend

Yêu cầu nền tảng gửi lại SMS đến số đã thuê. Không phải tất cả nền tảng đều hỗ trợ gửi lại — kiểm tra trường resent trong phản hồi.

Nội dung yêu cầu

Tên	Kiểu	Bắt buộc	Mô tả
`id`	integer	Có	Mã đơn hàng cần gửi lại SMS

Ví dụ yêu cầu

curl -s -X POST https://api.smscode.gg/v1/orders/resend \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":1001}'

const res = await fetch("https://api.smscode.gg/v1/orders/resend", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ id: 1001 }),
});
const data = await res.json();

import requests

res = requests.post("https://api.smscode.gg/v1/orders/resend",
    json={"id": 1001},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "order_id": 1001,
    "status": "ACTIVE",
    "resent": true
  }
}

POST/orders/reactivate

Kích hoạt lại một số đã hoàn tất — đặt lại chính số đó để nhận thêm một mã xác minh khác mà không cần thuê số mới. Chỉ đơn hàng đã hoàn tất có số hỗ trợ kích hoạt lại mới đủ điều kiện (kiểm tra can_reactivate trên đơn hàng, hoặc xem trước bằng reactivate-options). Đơn con được kích hoạt lại là một đơn hàng MỚI, được trả về theo cùng định dạng như create; số dư bị trừ tự động.

Nội dung yêu cầu

Tên	Kiểu	Bắt buộc	Mô tả
`id`	integer	Có	Đơn hàng đã hoàn tất cần kích hoạt lại.
`max_price`	integer	Không	Trần chi phí tùy chọn. Số nguyên IDR. Việc kích hoạt lại sẽ bị từ chối với 422 VALIDATION_ERROR nếu chi phí hiện tại vượt quá mức này.

Giống như create, đây là một thao tác thay đổi tiền — hãy truyền header Idempotency-Key để thử lại an toàn (một create và một reactivate không bao giờ xung đột trên cùng một key). Dùng lại một key với body khác sẽ trả về 422 IDEMPOTENCY_KEY_REUSED, và một yêu cầu vẫn đang xử lý với key đó sẽ trả về 409 REQUEST_IN_PROGRESS. Một số không thể kích hoạt lại sẽ trả về 409 CONFLICT; số dư quá thấp sẽ trả về 409 INSUFFICIENT_BALANCE.

Ví dụ yêu cầu

curl -s -X POST https://api.smscode.gg/v1/orders/reactivate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-901" \
  -d '{"id":1001,"max_price":20000}'

const res = await fetch("https://api.smscode.gg/v1/orders/reactivate", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
    "Idempotency-Key": "unique-request-id-901",
  },
  body: JSON.stringify({ id: 1001, max_price: 20000 }),
});
const data = await res.json();

import requests

res = requests.post("https://api.smscode.gg/v1/orders/reactivate",
    json={"id": 1001, "max_price": 20000},
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Idempotency-Key": "unique-request-id-901",
    })
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": 1044,
        "status": "ACTIVE",
        "product_id": 142,
        "catalog_product_id": 87,
        "amount": 15000,
        "phone_number": "+6281234567890",
        "otp_code": null,
        "otp_received_at": null,
        "expires_at": "2026-02-25T11:20:00+00:00",
        "failed_reason": null,
        "operator_id": null,
        "operator_name": null
      }
    ],
    "failed_count": 0
  }
}

GET/orders/{id}/reactivate-options

Xem trước chi phí kích hoạt lại ngay lúc này. Chỉ đọc — không tiêu tốn Idempotency-Key nào và không tạo ra gì. Trả về chi phí dưới dạng số nguyên IDR. Chỉ khả dụng cho đơn hàng đã hoàn tất có số hỗ trợ kích hoạt lại.

Tham số đường dẫn

Tên	Kiểu	Bắt buộc	Mô tả
`id`	integer	Có	Mã đơn hàng cần xem trước chi phí kích hoạt lại (tham số đường dẫn).

Ví dụ yêu cầu

curl -s https://api.smscode.gg/v1/orders/1001/reactivate-options \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v1/orders/1001/reactivate-options", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/orders/1001/reactivate-options",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "cost": 15000
  }
}

GET/webhook

Trả về cấu hình webhook notification hiện tại của bạn.

Tham số

Không có

Ví dụ yêu cầu

curl -s https://api.smscode.gg/v1/webhook \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v1/webhook", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/webhook",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "webhook_url": "https://example.com/webhook",
    "webhook_secret": "a1b2c3d4e5f6..."
  }
}

PATCH/webhook

Cập nhật URL webhook và/hoặc secret. Secret được tự động tạo khi bạn đặt URL lần đầu. Gửi chuỗi rỗng để xóa. URL phải sử dụng HTTPS.

Nội dung yêu cầu

Tên	Kiểu	Bắt buộc	Mô tả
`webhook_url`	string	Không	URL HTTPS để nhận sự kiện webhook (chuỗi rỗng để xóa)
`webhook_secret`	string	Không	Secret chia sẻ cho chữ ký HMAC-SHA256 (tự động tạo nếu bỏ qua lần đặt đầu tiên)

Cần ít nhất một trường.

Ví dụ yêu cầu

curl -s -X PATCH https://api.smscode.gg/v1/webhook \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url":"https://example.com/webhook"}'

const res = await fetch("https://api.smscode.gg/v1/webhook", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ webhook_url: "https://example.com/webhook" }),
});
const data = await res.json();

import requests

res = requests.patch("https://api.smscode.gg/v1/webhook",
    json={"webhook_url": "https://example.com/webhook"},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "webhook_url": "https://example.com/webhook",
    "webhook_secret": "a1b2c3d4e5f6..."
  }
}

POST/webhook/test

Gửi sự kiện thử nghiệm đến URL webhook đã cấu hình. Trả về mã trạng thái HTTP từ máy chủ của bạn. Hữu ích để kiểm tra endpoint hoạt động trước khi vận hành chính thức.

Tham số

Không có

Ví dụ yêu cầu

curl -s -X POST https://api.smscode.gg/v1/webhook/test \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v1/webhook/test", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.post("https://api.smscode.gg/v1/webhook/test",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "status_code": 200
  }
}

⟩Thông báo Webhook

Cấu hình URL webhook để nhận thông báo đẩy theo thời gian thực cho các sự kiện đơn hàng thay vì polling. Đây là phương pháp được khuyến nghị cho bot script.

Sự kiện

Sự kiện	Kích hoạt
`order.otp_received`	Đã nhận SMS mới; mã phân tích có thể là null
`order.completed`	Đơn hàng đã hoàn thành (thủ công hoặc khi hết hạn)
`order.expired`	Đơn hàng hết hạn trước khi nhận SMS (đã hoàn tiền)
`order.canceled`	Đơn hàng bị hủy bởi người dùng (đã hoàn tiền)

Mỗi SMS mới phát ra event này. otp_code có thể là null khi otp_message hiện diện. Nhiều event SMS có thể đến không theo thứ tự; dùng sms_revision để bỏ qua cặp tổng hợp cũ hơn.

Dữ liệu

Nội dung POST webhook
{
  "event": "order.otp_received",
  "timestamp": "2026-02-25T12:00:00+00:00",
  "data": {
    "order_id": 1001,
    "phone_number": "+628123456789",
    "otp_code": null,
    "otp_message": "Confirm your login: https://example.com/confirm",
    "sms_revision": 1,
    "product_id": 142,
    "catalog_product_id": 87,
    "country": "Indonesia",
    "platform": "WhatsApp"
  }
}

Xác minh chữ ký

Mỗi yêu cầu webhook bao gồm header X-Webhook-Signature chứa chữ ký HMAC-SHA256 của nội dung yêu cầu, sử dụng webhook_secret làm khóa:

X-Webhook-Signature:sha256={HMAC-SHA256(body, webhook_secret)}

Xác minh chữ ký này trên máy chủ để đảm bảo yêu cầu là xác thực. Gửi theo kiểu fire-and-forget với timeout 3 giây và không thử lại.

⟩Giới hạn tốc độ

Yêu cầu API được giới hạn tốc độ theo nhóm endpoint. Vượt quá giới hạn trả về 429 Too Many Requests với header Retry-After cho biết số giây cần đợi.

Nhóm endpoint	Giới hạn	Cửa sổ
Danh mục (quốc gia, dịch vụ, sản phẩm, tỷ giá)	5.000 yêu cầu	60 giây
Số dư	600 yêu cầu	60 giây
Đọc đơn hàng (danh sách, chi tiết, hoạt động)	5.000 yêu cầu	60 giây
Tạo đơn hàng	3.000 yêu cầu	60 giây
Hủy đơn hàng	1.000 yêu cầu	60 giây
Thao tác đơn hàng (hoàn thành, gửi lại)	1.000 yêu cầu	60 giây
Cấu hình webhook (xem, cập nhật)	600 yêu cầu	60 giây
Thử webhook	10 yêu cầu	60 giây

⟩Mã lỗi

Phản hồi lỗi bao gồm một trong các mã sau trong error.code:

Mã	HTTP	Mô tả
`UNAUTHORIZED`	401	Thiếu hoặc API token không hợp lệ
`FORBIDDEN`	403	Truy cập bị từ chối
`NOT_FOUND`	404	Không tìm thấy tài nguyên (đơn hàng, tỷ giá, v.v.)
`CONFLICT`	409	Yêu cầu trùng lặp hoặc xung đột tài nguyên
`INSUFFICIENT_BALANCE`	409	Số dư không đủ để tạo đơn hàng
`VALIDATION_ERROR`	422	Tham số yêu cầu không hợp lệ
`RATE_LIMIT_EXCEEDED`	429	Quá nhiều yêu cầu (kiểm tra header `Retry-After`)
`INTERNAL_ERROR`	500	Lỗi máy chủ nội bộ
`PROVIDER_ERROR`	422	Nhà cung cấp SMS thượng nguồn từ chối yêu cầu. Khi tạo đơn thất bại, lỗi có thể kèm `details`: `cause_counts` (đơn dùng `product_id` cũ — bảng đếm nhóm theo nguyên nhân) hoặc `attempts` (đơn dùng `catalog_product_id` — kết quả từng lần thử), với các giá trị `ok`, `no_numbers`, `insufficient_balance`, `price_rejected`, `provider_unavailable`, `provider_account_balance`, `provider_error`.
`NO_OFFER_AVAILABLE`	422	Không có ưu đãi đang hoạt động nào khớp với sản phẩm và chính sách được yêu cầu (giới hạn giá, tình trạng còn hàng).
`CANCEL_TOO_EARLY`	409	Đơn hàng quá mới để hủy — hãy đợi 2 phút
`REQUEST_IN_PROGRESS`	409	Một yêu cầu tạo đơn với idempotency key này vẫn đang được xử lý
`IDEMPOTENCY_KEY_REUSED`	422	Idempotency key này đã được dùng với một body yêu cầu khác
`SERVICE_UNAVAILABLE`	503	Dịch vụ tạm thời không khả dụng (bảo trì)

Tong Quan

Tất cả trường tiền tệ trên API /v2 đều bằng USD, được trả về dưới dạng đối tượng tiền tệ — { "amount": "0.92", "currency": "USD", "canonical_amount": 15000, "canonical_currency": "IDR" }. amount là một chuỗi thập phân; canonical_amount là giá trị sổ cái IDR chính xác (dùng nó để đối soát). Tỷ giá USD/IDR rate được áp dụng được công bố một lần cho mỗi phản hồi trong meta.fx. v2 là bản chiếu USD tại thời điểm hiển thị trên cùng một sổ cái IDR như v1 — nó không bao giờ lưu trữ hay giao dịch USD.

Chuyển từ v1 sang v2

⟩Xác thực

Tất cả yêu cầu API đều yêu cầu Bearer token. Tạo token từ Cài đặt tài khoản trong bảng điều khiển, sau đó đính kèm vào mỗi yêu cầu:

Authorization:Bearer YOUR_API_TOKEN

Yêu cầu không có token hợp lệ sẽ nhận phản hồi 401 UNAUTHORIZED.

⟩URL cơ sở

Tất cả đường dẫn endpoint bên dưới tương đối với:

https://api.smscode.gg/v2

⟩Định dạng phản hồi

Mọi phản hồi trả về JSON với cấu trúc nhất quán. Tất cả phản hồi bao gồm header x-request-id để gỡ lỗi.

Thành công
{
  "success": true,
  "data": { ... }
}

Lỗi
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message"
  }
}

Lỗi v2: không có tỷ giá khả dụng (503)

503 Service Unavailable · Retry-After: 60

{
  "success": false,
  "error": { "code": "FX_RATE_UNAVAILABLE", "message": "USD/IDR exchange rate is unavailable" }
}

GET/catalog/countries

Trả về danh sách tất cả quốc gia có sẵn.

Tham số

Không có

Ví dụ yêu cầu

curl -s https://api.smscode.gg/v2/catalog/countries \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v2/catalog/countries", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v2/catalog/countries",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": [
    {
      "id": 6,
      "code": "ID",
      "name": "Indonesia",
      "dial_code": "+62",
      "emoji": "🇮🇩",
      "active": true
    }
  ]
}

Giống hệt v1 — chỉ đường dẫn gốc thay đổi (/v1 → /v2).

GET/catalog/services

Trả về danh sách dịch vụ (nền tảng) có sẵn. Có thể lọc theo quốc gia.

Tham số truy vấn

Tên	Kiểu	Bắt buộc	Mô tả
`country_id`	integer	Không	Lọc dịch vụ có sẵn cho quốc gia này

Ví dụ yêu cầu

curl -s "https://api.smscode.gg/v2/catalog/services?country_id=7" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v2/catalog/services?country_id=7", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v2/catalog/services",
    params={"country_id": 7},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": [
    {
      "id": 3,
      "code": "wa",
      "name": "WhatsApp",
      "active": true
    }
  ]
}

Giống hệt v1 — chỉ đường dẫn gốc thay đổi (/v1 → /v2).

GET/catalog/operators

Tham số truy vấn

Tên	Kiểu	Bắt buộc	Mô tả
`country_id`	integer	Có	ID quốc gia
`platform_id`	integer	Có	ID nền tảng/dịch vụ

Ví dụ yêu cầu

curl -s "https://api.smscode.gg/v2/catalog/operators?country_id=7&platform_id=3" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const params = new URLSearchParams({
  country_id: "7", platform_id: "3",
});
const res = await fetch(`https://api.smscode.gg/v2/catalog/operators?${params}`, {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v2/catalog/operators",
    params={"country_id": 7, "platform_id": 3},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": [
    {
      "operator_id": null,
      "code": "any",
      "name": "Any",
      "local_name": null
    },
    {
      "operator_id": 433,
      "code": "axis",
      "name": "AXIS (XL Axiata)",
      "local_name": "AXIS (XL Axiata)"
    }
  ]
}

Giống hệt v1 — chỉ đường dẫn gốc thay đổi (/v1 → /v2).

GET/catalog/products

Trả về danh sách phân trang các sản phẩm khả dụng. Lọc theo quốc gia, nền tảng và tùy chọn theo nhà mạng.

Tham số truy vấn

Tên	Kiểu	Bắt buộc	Mô tả
`country_id`	integer	Không	Lọc theo ID quốc gia
`platform_id`	integer	Không	Lọc theo ID nền tảng/dịch vụ
`operator_id`	integer	Không	ID nhà mạng tùy chọn từ /catalog/operators. Bỏ qua đối với sản phẩm Any.
`sort`	string	Không	Thứ tự sắp xếp: price_asc (mặc định), price_desc, available_asc, available_desc, name_asc, name_desc
`limit`	integer	Không	Số kết quả mỗi trang (1-10.000, mặc định 1.000)
`page`	integer	Không	Số trang (tối thiểu 1, mặc định 1)

Ví dụ yêu cầu

curl -s "https://api.smscode.gg/v2/catalog/products?country_id=7&platform_id=3&limit=10&page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const params = new URLSearchParams({
  country_id: "7", platform_id: "3", limit: "10", page: "1",
});
const res = await fetch(`https://api.smscode.gg/v2/catalog/products?${params}`, {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v2/catalog/products",
    params={"country_id": 7, "platform_id": 3, "limit": 10, "page": 1},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": [
    {
      "id": 142,
      "name": "WhatsApp Indonesia",
      "country_id": 7,
      "platform_id": 3,
      "catalog_product_id": 87,
      "operator_id": null,
      "operator_name": null,
      "available": 42,
      "price": { "amount": "0.9231", "currency": "USD", "canonical_amount": 15000, "canonical_currency": "IDR" },
      "active": true
    }
  ],
  "meta": { "page": 1, "limit": 10, "count": 1, "fx": { "pair": "USD/IDR", "rate": 16250, "rate_as_of": "2026-05-27T08:00:00+00:00" } }
}

v2: các trường tiền tệ là đối tượng tiền tệ USD và phản hồi mang theo một meta.fx { pair, rate, rate_as_of } duy nhất. rate là số IDR nguyên trên 1 USD, nên USD = canonical_amount / rate. Tổng dùng 2 chữ số thập phân; giá/hoàn tiền theo từng mục dùng 4. Một số tiền dương thực sự không bao giờ được làm tròn thành 0.00. rate_as_of là dấu thời gian RFC3339 của tỷ giá (dạng +00:00) hoặc null khi không có dấu thời gian được ghi lại.

Chỉ v2: nếu không có tỷ giá USD/IDR khả dụng, các endpoint tiền tệ trả về 503 FX_RATE_UNAVAILABLE kèm header Retry-After thay vì phần thân tiền tệ. v1 không bao giờ trả về điều này.

GET/catalog/exchange-rate

Trả về tỷ giá hối đoái USD/IDR hiện tại được dùng để chuyển đổi tiền tệ.

Tham số

Không có — v2 luôn trả về USD/IDR; tham số ?pair của v1 bị bỏ qua.

Ví dụ yêu cầu

curl -s "https://api.smscode.gg/v2/catalog/exchange-rate?pair=USD/IDR" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v2/catalog/exchange-rate?pair=USD/IDR", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v2/catalog/exchange-rate",
    params={"pair": "USD/IDR"},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": { "pair": "USD/IDR", "rate": 16250, "rate_as_of": "2026-05-27T08:00:00+00:00" }
}

v2: trả về { pair, rate, rate_as_of } (không có base_currency/quote_currency, không có lớp bọc meta — tỷ giá chính là dữ liệu). ?pair bị bỏ qua — v2 luôn trả về USD/IDR (v1 tôn trọng ?pair). Trả về 503 FX_RATE_UNAVAILABLE nếu không có tỷ giá khả dụng.

GET/balance

Trả về số dư tài khoản của người dùng đã xác thực.

Tham số

Không có

Ví dụ yêu cầu

curl -s https://api.smscode.gg/v2/balance \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v2/balance", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v2/balance",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "balance": { "amount": "30.77", "currency": "USD", "canonical_amount": 500000, "canonical_currency": "IDR" }
  },
  "meta": { "fx": { "pair": "USD/IDR", "rate": 16250, "rate_as_of": "2026-05-27T08:00:00+00:00" } }
}

GET/orders

Trả về danh sách đơn hàng của người dùng đã xác thực, sắp xếp theo mới nhất. Hỗ trợ lọc theo trạng thái và phân trang qua offset.

Tham số truy vấn

Tên	Kiểu	Bắt buộc	Mô tả
`limit`	integer	Không	Số kết quả tối đa (1-100, mặc định 20)
`offset`	integer	Không	Số kết quả bỏ qua (mặc định 0)
`status`	string	Không	Lọc theo trạng thái: ACTIVE, OTP_RECEIVED, COMPLETED, CANCELED, EXPIRED (không phân biệt hoa thường)

Ví dụ yêu cầu

curl -s "https://api.smscode.gg/v2/orders?limit=5&status=ACTIVE" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const params = new URLSearchParams({
  limit: "5", status: "ACTIVE", offset: "0",
});
const res = await fetch(`https://api.smscode.gg/v2/orders?${params}`, {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v2/orders",
    params={"limit": 5, "status": "ACTIVE", "offset": 0},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": [
    {
      "id": 1001,
      "status": "ACTIVE",
      "created_at": "2026-02-25T10:00:00+00:00",
      "product_id": 142,
      "catalog_product_id": 87,
      "phone_number": "+6281234567890",
      "amount": { "amount": "0.9231", "currency": "USD", "canonical_amount": 15000, "canonical_currency": "IDR" },
      "otp_code": null,
      "otp_received_at": null,
      "expires_at": "2026-02-25T10:20:00+00:00",
      "canceled_at": null,
      "failed_reason": null,
      "operator_id": null,
      "operator_name": null
    }
  ],
  "meta": { "fx": { "pair": "USD/IDR", "rate": 16250, "rate_as_of": "2026-05-27T08:00:00+00:00" } }
}

GET/orders/{id}

Trả về một đơn hàng theo ID. Chỉ trả về đơn hàng của người dùng đã xác thực.

Tham số đường dẫn

Tên	Kiểu	Bắt buộc	Mô tả
`id`	integer	Có	Mã đơn hàng (tham số đường dẫn)

Ví dụ yêu cầu

curl -s https://api.smscode.gg/v2/orders/1001 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v2/orders/1001", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v2/orders/1001",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "id": 1001,
    "status": "OTP_RECEIVED",
    "created_at": "2026-02-25T10:00:00+00:00",
    "product_id": 142,
    "catalog_product_id": 87,
    "phone_number": "+6281234567890",
    "amount": { "amount": "0.9231", "currency": "USD", "canonical_amount": 15000, "canonical_currency": "IDR" },
    "otp_code": "123456",
    "otp_received_at": "2026-02-25T10:05:00+00:00",
    "expires_at": "2026-02-25T10:20:00+00:00",
    "canceled_at": null,
    "failed_reason": null,
    "operator_id": null,
    "operator_name": null
  },
  "meta": { "fx": { "pair": "USD/IDR", "rate": 16250, "rate_as_of": "2026-05-27T08:00:00+00:00" } }
}

GET/orders/active

Liệt kê tất cả đơn hàng đang hoạt động (ACTIVE + OTP_RECEIVED). Sử dụng để theo dõi cập nhật trạng thái OTP.

Tham số

Không có

Ví dụ yêu cầu

curl -s https://api.smscode.gg/v2/orders/active \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v2/orders/active", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v2/orders/active",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": [
    {
      "id": 1001,
      "status": "OTP_RECEIVED",
      "otp_code": null,
      "otp_message": "Confirm your login: https://example.com/confirm",
      "sms_revision": 1,
      "otp_received_at": "2026-02-25T10:05:00+00:00",
      "expires_at": "2026-02-25T10:20:00+00:00",
      "failed_reason": null
    },
    {
      "id": 1002,
      "status": "ACTIVE",
      "otp_code": null,
      "otp_message": null,
      "sms_revision": 0,
      "otp_received_at": null,
      "expires_at": "2026-02-25T10:50:00+00:00",
      "failed_reason": null
    }
  ]
}

v2: endpoint này không mang tiền tệ — nó không trả về amount cũng không trả về meta.fx (cùng cấu trúc như v1, dưới /v2).

POST/orders/create

Tạo đơn hàng số ảo mới. Tự động trừ số dư. Hỗ trợ header Idempotency-Key tùy chọn để tránh tạo đơn trùng lặp khi thử lại do lỗi mạng.

Nội dung yêu cầu

Tên	Kiểu	Bắt buộc	Mô tả
`product_id`	integer	Không	ID sản phẩm của ô mức giá chính xác và ổn định để đặt trực tiếp. Chỉ gửi MỘT trong hai: giá trị này hoặc catalog_product_id, không gửi cả hai.
`catalog_product_id`	integer	Không	ID umbrella quốc gia+nền tảng cho đặt hàng có định tuyến. Máy chủ chọn một mức giá hiện tại phù hợp. Gửi giá trị này hoặc product_id.
`operator_id`	integer	Không	ID nhà mạng tùy chọn từ /catalog/operators. Chỉ hợp lệ với catalog_product_id; bỏ qua đối với Any.
`min_price`	string	Không	Giá sàn tùy chọn. Chuỗi thập phân USD (ví dụ "0.30"). Chỉ hợp lệ với catalog_product_id.
`max_price`	string	Không	Giá trần tùy chọn. Chuỗi thập phân USD (ví dụ "0.50"). Chỉ hợp lệ với catalog_product_id.
`prefer_provider`	string	Không	Mã nhà cung cấp tùy chọn được ưu tiên khi các ưu đãi ngang nhau.
`policy`	string	Không	Chính sách định tuyến tùy chọn, chỉ hợp lệ khi dùng catalog_product_id. Giá trị: cheapest (mặc định) chọn ưu đãi tốt có giá thấp nhất; best_success xếp hạng các ưu đãi theo tỷ lệ giao thành công gần đây trước. best_success chấm điểm mỗi nhà cung cấp theo tỷ lệ đơn nhận được OTP trong 30 ngày trọn vẹn gần nhất, theo dải 10%, và chỉ tính một nhà cung cấp khi họ có ít nhất 20 đơn trong khoảng đó — nhà cung cấp dưới ngưỡng này hoặc chưa có lịch sử được coi là trung tính, nên các ưu đãi mới không bao giờ bị bỏ rơi (tùy chọn; tín hiệu khởi đầu ở mức trung tính). Khi prefer_provider cũng được đặt, nhà cung cấp ưu tiên vẫn được xếp trước.
`quantity`	integer	Không	Số lượng (1-100, mặc định 1)

Ví dụ yêu cầu

curl -s -X POST https://api.smscode.gg/v2/orders/create \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{"catalog_product_id":87,"min_price":"0.30","max_price":"0.50","operator_id":433,"quantity":1}'

const res = await fetch("https://api.smscode.gg/v2/orders/create", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
    "Idempotency-Key": "unique-request-id-123",
  },
  body: JSON.stringify({
    catalog_product_id: 87,
    min_price: "0.30",
    max_price: "0.50",
    operator_id: 433,
    quantity: 1,
  }),
});
const data = await res.json();

import requests

res = requests.post("https://api.smscode.gg/v2/orders/create",
    json={
        "catalog_product_id": 87,
        "min_price": "0.30",
        "max_price": "0.50",
        "operator_id": 433,
        "quantity": 1,
    },
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Idempotency-Key": "unique-request-id-123",
    })
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": 1002,
        "status": "ACTIVE",
        "product_id": 142,
        "catalog_product_id": 87,
        "amount": { "amount": "0.9231", "currency": "USD", "canonical_amount": 15000, "canonical_currency": "IDR" },
        "phone_number": "+6281234567891",
        "otp_code": null,
        "otp_received_at": null,
        "expires_at": "2026-02-25T10:50:00+00:00",
        "failed_reason": null,
        "operator_id": null,
        "operator_name": null
      }
    ],
    "failed_count": 0
  },
  "meta": { "fx": { "pair": "USD/IDR", "rate": 16250, "rate_as_of": "2026-05-27T08:00:00+00:00" } }
}

POST/orders/cancel

Hủy đơn hàng đang hoạt động. Phí thuê sẽ được hoàn vào số dư tài khoản.

Nội dung yêu cầu

Tên	Kiểu	Bắt buộc	Mô tả
`id`	integer	Có	Mã đơn hàng cần hủy

Ví dụ yêu cầu

curl -s -X POST https://api.smscode.gg/v2/orders/cancel \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":1001}'

const res = await fetch("https://api.smscode.gg/v2/orders/cancel", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ id: 1001 }),
});
const data = await res.json();

import requests

res = requests.post("https://api.smscode.gg/v2/orders/cancel",
    json={"id": 1001},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "order_id": 1001,
    "status": "CANCELED",
    "refund_amount": { "amount": "0.9231", "currency": "USD", "canonical_amount": 15000, "canonical_currency": "IDR" },
    "new_balance": { "amount": "31.69", "currency": "USD", "canonical_amount": 515000, "canonical_currency": "IDR" }
  },
  "meta": { "fx": { "pair": "USD/IDR", "rate": 16250, "rate_as_of": "2026-05-27T08:00:00+00:00" } }
}

POST/orders/finish

Đánh dấu đơn hàng đã hoàn thành sau khi nhận OTP. Giải phóng số ngay lập tức thay vì đợi hết hạn.

Nội dung yêu cầu

Tên	Kiểu	Bắt buộc	Mô tả
`id`	integer	Có	Mã đơn hàng cần hoàn thành

Ví dụ yêu cầu

curl -s -X POST https://api.smscode.gg/v2/orders/finish \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":1001}'

const res = await fetch("https://api.smscode.gg/v2/orders/finish", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ id: 1001 }),
});
const data = await res.json();

import requests

res = requests.post("https://api.smscode.gg/v2/orders/finish",
    json={"id": 1001},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "order_id": 1001,
    "status": "COMPLETED"
  }
}

Giống hệt v1 — chỉ đường dẫn gốc thay đổi (/v1 → /v2).

POST/orders/resend

Yêu cầu nền tảng gửi lại SMS đến số đã thuê. Không phải tất cả nền tảng đều hỗ trợ gửi lại — kiểm tra trường resent trong phản hồi.

Nội dung yêu cầu

Tên	Kiểu	Bắt buộc	Mô tả
`id`	integer	Có	Mã đơn hàng cần gửi lại SMS

Ví dụ yêu cầu

curl -s -X POST https://api.smscode.gg/v2/orders/resend \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":1001}'

const res = await fetch("https://api.smscode.gg/v2/orders/resend", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ id: 1001 }),
});
const data = await res.json();

import requests

res = requests.post("https://api.smscode.gg/v2/orders/resend",
    json={"id": 1001},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "order_id": 1001,
    "status": "ACTIVE",
    "resent": true
  }
}

Giống hệt v1 — chỉ đường dẫn gốc thay đổi (/v1 → /v2).

POST/orders/reactivate

Nội dung yêu cầu

Tên	Kiểu	Bắt buộc	Mô tả
`id`	integer	Có	Đơn hàng đã hoàn tất cần kích hoạt lại.
`max_price`	string	Không	Trần chi phí tùy chọn. Chuỗi thập phân USD (ví dụ "0.50"). Việc kích hoạt lại sẽ bị từ chối với 422 VALIDATION_ERROR nếu chi phí hiện tại vượt quá mức này.

Ví dụ yêu cầu

curl -s -X POST https://api.smscode.gg/v2/orders/reactivate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-901" \
  -d '{"id":1001,"max_price":"0.50"}'

const res = await fetch("https://api.smscode.gg/v2/orders/reactivate", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
    "Idempotency-Key": "unique-request-id-901",
  },
  body: JSON.stringify({ id: 1001, max_price: "0.50" }),
});
const data = await res.json();

import requests

res = requests.post("https://api.smscode.gg/v2/orders/reactivate",
    json={"id": 1001, "max_price": "0.50"},
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Idempotency-Key": "unique-request-id-901",
    })
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": 1044,
        "status": "ACTIVE",
        "product_id": 142,
        "catalog_product_id": 87,
        "amount": { "amount": "0.9231", "currency": "USD", "canonical_amount": 15000, "canonical_currency": "IDR" },
        "phone_number": "+6281234567890",
        "otp_code": null,
        "otp_received_at": null,
        "expires_at": "2026-02-25T11:20:00+00:00",
        "failed_reason": null,
        "operator_id": null,
        "operator_name": null
      }
    ],
    "failed_count": 0
  },
  "meta": { "fx": { "pair": "USD/IDR", "rate": 16250, "rate_as_of": "2026-05-27T08:00:00+00:00" } }
}

GET/orders/{id}/reactivate-options

Xem trước chi phí kích hoạt lại ngay lúc này. Chỉ đọc — không tiêu tốn Idempotency-Key nào và không tạo ra gì. Trả về chi phí dưới dạng đối tượng tiền tệ USD kèm biên nhận FX. Chỉ khả dụng cho đơn hàng đã hoàn tất có số hỗ trợ kích hoạt lại.

Tham số đường dẫn

Tên	Kiểu	Bắt buộc	Mô tả
`id`	integer	Có	Mã đơn hàng cần xem trước chi phí kích hoạt lại (tham số đường dẫn).

Ví dụ yêu cầu

curl -s https://api.smscode.gg/v2/orders/1001/reactivate-options \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v2/orders/1001/reactivate-options", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v2/orders/1001/reactivate-options",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "cost": { "amount": "0.9231", "currency": "USD", "canonical_amount": 15000, "canonical_currency": "IDR" }
  },
  "meta": { "fx": { "pair": "USD/IDR", "rate": 16250, "rate_as_of": "2026-05-27T08:00:00+00:00" } }
}

GET/webhook

Trả về cấu hình webhook notification hiện tại của bạn.

Tham số

Không có

Ví dụ yêu cầu

curl -s https://api.smscode.gg/v2/webhook \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v2/webhook", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v2/webhook",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "webhook_url": "https://example.com/webhook",
    "webhook_secret": "a1b2c3d4e5f6..."
  }
}

Giống hệt v1 — chỉ đường dẫn gốc thay đổi (/v1 → /v2).

PATCH/webhook

Cập nhật URL webhook và/hoặc secret. Secret được tự động tạo khi bạn đặt URL lần đầu. Gửi chuỗi rỗng để xóa. URL phải sử dụng HTTPS.

Nội dung yêu cầu

Tên	Kiểu	Bắt buộc	Mô tả
`webhook_url`	string	Không	URL HTTPS để nhận sự kiện webhook (chuỗi rỗng để xóa)
`webhook_secret`	string	Không	Secret chia sẻ cho chữ ký HMAC-SHA256 (tự động tạo nếu bỏ qua lần đặt đầu tiên)

Cần ít nhất một trường.

Ví dụ yêu cầu

curl -s -X PATCH https://api.smscode.gg/v2/webhook \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url":"https://example.com/webhook"}'

const res = await fetch("https://api.smscode.gg/v2/webhook", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ webhook_url: "https://example.com/webhook" }),
});
const data = await res.json();

import requests

res = requests.patch("https://api.smscode.gg/v2/webhook",
    json={"webhook_url": "https://example.com/webhook"},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "webhook_url": "https://example.com/webhook",
    "webhook_secret": "a1b2c3d4e5f6..."
  }
}

Giống hệt v1 — chỉ đường dẫn gốc thay đổi (/v1 → /v2).

POST/webhook/test

Tham số

Không có

Ví dụ yêu cầu

curl -s -X POST https://api.smscode.gg/v2/webhook/test \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v2/webhook/test", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.post("https://api.smscode.gg/v2/webhook/test",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Ví dụ phản hồi

200 OK

{
  "success": true,
  "data": {
    "status_code": 200
  }
}

Giống hệt v1 — chỉ đường dẫn gốc thay đổi (/v1 → /v2).

⟩Thông báo Webhook

Cấu hình URL webhook để nhận thông báo đẩy theo thời gian thực cho các sự kiện đơn hàng thay vì polling. Đây là phương pháp được khuyến nghị cho bot script.

Sự kiện

Sự kiện	Kích hoạt
`order.otp_received`	Đã nhận SMS mới; mã phân tích có thể là null
`order.completed`	Đơn hàng đã hoàn thành (thủ công hoặc khi hết hạn)
`order.expired`	Đơn hàng hết hạn trước khi nhận SMS (đã hoàn tiền)
`order.canceled`	Đơn hàng bị hủy bởi người dùng (đã hoàn tiền)

Dữ liệu

Nội dung POST webhook
{
  "event": "order.otp_received",
  "timestamp": "2026-02-25T12:00:00+00:00",
  "data": {
    "order_id": 1001,
    "phone_number": "+628123456789",
    "otp_code": null,
    "otp_message": "Confirm your login: https://example.com/confirm",
    "sms_revision": 1,
    "product_id": 142,
    "catalog_product_id": 87,
    "country": "Indonesia",
    "platform": "WhatsApp"
  }
}

Xác minh chữ ký

Mỗi yêu cầu webhook bao gồm header X-Webhook-Signature chứa chữ ký HMAC-SHA256 của nội dung yêu cầu, sử dụng webhook_secret làm khóa:

X-Webhook-Signature:sha256={HMAC-SHA256(body, webhook_secret)}

Xác minh chữ ký này trên máy chủ để đảm bảo yêu cầu là xác thực. Gửi theo kiểu fire-and-forget với timeout 3 giây và không thử lại.

⟩Giới hạn tốc độ

Yêu cầu API được giới hạn tốc độ theo nhóm endpoint. Vượt quá giới hạn trả về 429 Too Many Requests với header Retry-After cho biết số giây cần đợi.

Nhóm endpoint	Giới hạn	Cửa sổ
Danh mục (quốc gia, dịch vụ, sản phẩm, tỷ giá)	5.000 yêu cầu	60 giây
Số dư	600 yêu cầu	60 giây
Đọc đơn hàng (danh sách, chi tiết, hoạt động)	5.000 yêu cầu	60 giây
Tạo đơn hàng	3.000 yêu cầu	60 giây
Hủy đơn hàng	1.000 yêu cầu	60 giây
Thao tác đơn hàng (hoàn thành, gửi lại)	1.000 yêu cầu	60 giây
Cấu hình webhook (xem, cập nhật)	600 yêu cầu	60 giây
Thử webhook	10 yêu cầu	60 giây

⟩Mã lỗi

Phản hồi lỗi bao gồm một trong các mã sau trong error.code:

Mã	HTTP	Mô tả
`UNAUTHORIZED`	401	Thiếu hoặc API token không hợp lệ
`FORBIDDEN`	403	Truy cập bị từ chối
`NOT_FOUND`	404	Không tìm thấy tài nguyên (đơn hàng, tỷ giá, v.v.)
`CONFLICT`	409	Yêu cầu trùng lặp hoặc xung đột tài nguyên
`INSUFFICIENT_BALANCE`	409	Số dư không đủ để tạo đơn hàng
`VALIDATION_ERROR`	422	Tham số yêu cầu không hợp lệ
`RATE_LIMIT_EXCEEDED`	429	Quá nhiều yêu cầu (kiểm tra header `Retry-After`)
`INTERNAL_ERROR`	500	Lỗi máy chủ nội bộ
`PROVIDER_ERROR`	422	Nhà cung cấp SMS thượng nguồn từ chối yêu cầu. Khi tạo đơn thất bại, lỗi có thể kèm `details`: `cause_counts` (đơn dùng `product_id` cũ — bảng đếm nhóm theo nguyên nhân) hoặc `attempts` (đơn dùng `catalog_product_id` — kết quả từng lần thử), với các giá trị `ok`, `no_numbers`, `insufficient_balance`, `price_rejected`, `provider_unavailable`, `provider_account_balance`, `provider_error`.
`NO_OFFER_AVAILABLE`	422	Không có ưu đãi đang hoạt động nào khớp với sản phẩm và chính sách được yêu cầu (giới hạn giá, tình trạng còn hàng).
`CANCEL_TOO_EARLY`	409	Đơn hàng quá mới để hủy — hãy đợi 2 phút
`REQUEST_IN_PROGRESS`	409	Một yêu cầu tạo đơn với idempotency key này vẫn đang được xử lý
`IDEMPOTENCY_KEY_REUSED`	422	Idempotency key này đã được dùng với một body yêu cầu khác
`SERVICE_UNAVAILABLE`	503	Dịch vụ tạm thời không khả dụng (bảo trì)
`FX_RATE_UNAVAILABLE`	503	Tỷ giá hối đoái USD/IDR không khả dụng (các endpoint tiền tệ v2) — trả về `503` kèm header `Retry-After`.

v1 → v2

⟩Chuyển từ v1 sang v2

v1 phục vụ IDR; v2 phục vụ USD. Cả hai phiên bản cùng tồn tại vĩnh viễn — không có việc ngừng hỗ trợ. Chọn một phiên bản cho mỗi tích hợp; đừng trộn lẫn đường dẫn gốc. v2 giống hệt v1 ngoại trừ cách biểu diễn tiền tệ.

Khía cạnh	v1 · IDR	v2 · USD
Trường tiền tệ	IDR nguyên, vd. `15000`	Đối tượng tiền tệ `{ amount, currency, canonical_amount, canonical_currency }`
`meta.fx`	Không có	Bắt buộc trên mọi phản hồi mang tiền tệ
Tiền tệ	IDR	USD (cố định trong mã)
`FX_RATE_UNAVAILABLE`	—	`503` + `Retry-After` mới khi không có tỷ giá khả dụng
Độ chính xác	—	Tổng 2 chữ số, giá/hoàn tiền 4 chữ số, làm tròn lên với số dương
`GET /catalog/exchange-rate`	`{pair, base_currency, quote_currency, rate}`; tôn trọng `?pair`	`{pair, rate, rate_as_of}`; `?pair` bị bỏ qua (chỉ USD/IDR)

Ví dụ song song

GET/balance

v1
{
  "success": true,
  "data": {
    "currency": "IDR",
    "balance": 500000
  }
}

v2
{
  "success": true,
  "data": {
    "balance": { "amount": "30.77", "currency": "USD", "canonical_amount": 500000, "canonical_currency": "IDR" }
  },
  "meta": { "fx": { "pair": "USD/IDR", "rate": 16250, "rate_as_of": "2026-05-27T08:00:00+00:00" } }
}

GET/catalog/products

v1
{
  "success": true,
  "data": [
    {
      "id": 142,
      "name": "WhatsApp Indonesia",
      "country_id": 7,
      "platform_id": 3,
      "catalog_product_id": 87,
      "operator_id": null,
      "operator_name": null,
      "available": 42,
      "price": 15000,
      "active": true
    }
  ],
  "meta": { "page": 1, "limit": 10, "count": 1 }
}

v2
{
  "success": true,
  "data": [
    {
      "id": 142,
      "name": "WhatsApp Indonesia",
      "country_id": 7,
      "platform_id": 3,
      "catalog_product_id": 87,
      "operator_id": null,
      "operator_name": null,
      "available": 42,
      "price": { "amount": "0.9231", "currency": "USD", "canonical_amount": 15000, "canonical_currency": "IDR" },
      "active": true
    }
  ],
  "meta": { "page": 1, "limit": 10, "count": 1, "fx": { "pair": "USD/IDR", "rate": 16250, "rate_as_of": "2026-05-27T08:00:00+00:00" } }
}

product_id là ID ô mức giá SMSCode ổn định. Hãy lưu nó khi bạn muốn đặt đúng mức giá đó; giá và độ khả dụng có thể thay đổi ngay trên cùng một dòng. catalog_product_id là umbrella quốc gia+nền tảng ổn định cho đặt hàng có định tuyến; dùng với operator_id, min_price, max_price, prefer_provider và policy tùy chọn khi bạn muốn máy chủ chọn một mức giá hiện tại phù hợp.

POST/orders/cancel

v1
{
  "success": true,
  "data": {
    "order_id": 1001,
    "status": "CANCELED",
    "refund_amount": 15000,
    "new_balance": 515000
  }
}

v2
{
  "success": true,
  "data": {
    "order_id": 1001,
    "status": "CANCELED",
    "refund_amount": { "amount": "0.9231", "currency": "USD", "canonical_amount": 15000, "canonical_currency": "IDR" },
    "new_balance": { "amount": "31.69", "currency": "USD", "canonical_amount": 515000, "canonical_currency": "IDR" }
  },
  "meta": { "fx": { "pair": "USD/IDR", "rate": 16250, "rate_as_of": "2026-05-27T08:00:00+00:00" } }
}

Danh sách kiểm tra khi chuyển đổi

Đổi đường dẫn gốc /v1 → /v2.
Phân tích các trường tiền tệ dưới dạng đối tượng — đọc amount như một chuỗi thập phân; currency là "USD".
Để đối soát sổ cái, dùng canonical_amount (IDR chính xác); số tiền USD amount là bản chiếu tại thời điểm hiển thị và rate được công bố một lần trong meta.fx.
Xử lý FX_RATE_UNAVAILABLE (503) mới — thử lại sau Retry-After. v1 không bao giờ trả về điều này.

⟩Bắt đầu với SDK chính thức

Tạo an toàn

Dùng OTP

Chỉ resend khi cần

⟩Tong Quan

⟩Xác thực

⟩URL cơ sở

⟩Định dạng phản hồi

Tham số

Ví dụ yêu cầu

Ví dụ phản hồi

Tham số truy vấn

Ví dụ yêu cầu

Ví dụ phản hồi

Tham số truy vấn

Ví dụ yêu cầu

Ví dụ phản hồi

Tham số truy vấn

Ví dụ yêu cầu

Ví dụ phản hồi

Tham số truy vấn

Ví dụ yêu cầu

Ví dụ phản hồi

Tham số

Ví dụ yêu cầu

Ví dụ phản hồi

Tham số truy vấn

Ví dụ yêu cầu

Ví dụ phản hồi

Tham số đường dẫn

Ví dụ yêu cầu

Ví dụ phản hồi

Tham số

Ví dụ yêu cầu

Ví dụ phản hồi

Nội dung yêu cầu

Ví dụ yêu cầu

Ví dụ phản hồi

Nội dung yêu cầu

Ví dụ yêu cầu

Ví dụ phản hồi

Nội dung yêu cầu

Ví dụ yêu cầu

Ví dụ phản hồi

Nội dung yêu cầu

Ví dụ yêu cầu

Ví dụ phản hồi

Nội dung yêu cầu

Ví dụ yêu cầu

Ví dụ phản hồi

Tham số đường dẫn

Ví dụ yêu cầu

Ví dụ phản hồi

Tham số

Ví dụ yêu cầu

Ví dụ phản hồi

Nội dung yêu cầu

Ví dụ yêu cầu

Ví dụ phản hồi

Tham số

Ví dụ yêu cầu

Ví dụ phản hồi

⟩Thông báo Webhook

Sự kiện

Dữ liệu

Xác minh chữ ký

⟩Giới hạn tốc độ

⟩Mã lỗi

⟩Tong Quan

⟩Xác thực

⟩URL cơ sở

⟩Định dạng phản hồi

Lỗi v2: không có tỷ giá khả dụng (503)

Tham số

Ví dụ yêu cầu

Ví dụ phản hồi

Tham số truy vấn

Ví dụ yêu cầu

Ví dụ phản hồi

Tham số truy vấn

Bắt đầu với SDK chính thức

Tong Quan

Tong Quan