API TRA CỨU THẺ BẰNG SERIAL

API Tra cứu từ thông tin Serial thẻ cào ra được các thông tin mệnh giá thẻ, thẻ đã nạp cho đơn nào. Đây là nghiệp vụ bắt buộc phải có với các đơn vị gạch thẻ vào đơn

Hiện tại hoạt động với nhà mạng Vinaphone, Viettel

Sequent Diagram

Để kết nối đối tác cần cung cấp các thông tin sau để tiến hành kết nối :

Thông tin	Giải thích
IP	IP để kết nối API và truy cập được Dashboard

Các thông tin được cung cấp

Thông tin	Tác dụng
URI endpoint	Địa chỉ Api Endpoint để kết nối
Api-Key	Api key để xác thực request
CMS tra cứu	Link và Account tra cứu đối soát trên cms

Api Tra cứu Serial Thẻ cào

POST /v1/aio-telco-service/cards/check-serial

Api Tra cứu Serial , trả về thông tin thẻ cào ngay trong response ( đồng bộ)

Headers

Name	Value
Content-Type	application/json
Api-Key	Api được cấp riêng cho đối tác

Body

Json

Request Body

{
  "serial": "59550043197181",
  "type": 3
}

Giải thích các field

Name	Type	Bắt Buộc	Description
serial	string	Yes	Serial thẻ cào cần tra cứu
type	string	Yes	Mã Nhà Mạng. Viettel : 1 Vinaphone : 3 Mobifone : 2

Code ví dụ :

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://domain.com/v1/aio-telco-service/cards/check-serial',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "serial": "59550043197111",
  "type": 3
}',
  CURLOPT_HTTPHEADER => array(
    'api-key: xxx',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Python

Response

Kết quả trả về là JSON

Tra Cứu Thành Công

{
    "isCharge": true,
    "data": {
        "type": "Vinaphone",
        "serial": "59550043197183",
        "amount": 50000,
        "usedDate": "2025-10-11T15:18:35",
        "expiredDate": null,
        "used": true,
        "usedBy": "091*****57",
        "checkedBy": "",
        "comment": "Thẻ cào đã sử dụng"
    },
    "code": 0,
    "message": "Thành công"
}

Tra Cứu Thẻ Không Tồn Tại

Lỗi khác

Miêu tả các Field Json Trả về :

Field	Kiểu Dữ Liệu	Giải Thích
code	string	Mã trạng thái giao dịch : 0 : thành công 1 : lỗi liên quan đến tài khoàn
message	string	Miêu tả
isCharge	boolean	Trạng thái tra cứu ( có trừ tiền tài khoản trên hệ thống không)
data	string (json)	Thông tin thẻ cào tra cứu được ( nếu thẻ có tồn tại trên hệ thống của nhà mạng) "serial": "59550043197183", "amount": 50000, "usedDate": "2025-10-11T15:18:35", "expiredDate": null, "used": true, "usedBy": "091*****57", "checkedBy": "", "comment": "Thẻ cào đã sử dụng"