🔍 CekTAG API Documentation

REST API untuk cek nama & tag pemilik nomor HP via GetContact

📑 Daftar Isi

Cara Mendapatkan API Key
Authentication
Base URL
Endpoints
Error Handling
Contoh Penggunaan (Python, JS, PHP, cURL)
Catatan Penting
FAQ

🚀 Cara Mendapatkan API Key

Ikuti langkah berikut untuk mendapatkan akses API:

Buka bot Telegram — cari @cekktagbot dan klik /start

Top up saldo minimal Rp 25.000 via QRIS (menu 💰 Top Up di bot)

Request API key — ketik /api di bot → klik 📝 Request API Key

Tunggu approval — admin akan review dan approve. Kamu akan dapat notifikasi + API key otomatis di chat

Mulai pakai! — gunakan API key di header Authorization setiap request

✅ Setelah approved, ketik /api kapan saja di bot untuk lihat API key, saldo, dan sisa kuota cek kamu.

🔑 Authentication

Semua request harus menyertakan API key di header:

Authorization: Bearer <API_KEY>

⚠️ Jangan share API key kamu. Satu key = satu akun. Semua pengecekan menggunakan saldo akun kamu. Jika bocor, reset via bot: /api → 🔄 Reset API Key (key lama langsung nonaktif).

📡 Base URL

https://apigetece.my.id

Semua endpoint dimulai dengan /api/v1/

📖 Endpoints

1. Cek Nomor Telepon

GET /api/v1/check?phone={nomor}

Cek nama dan tag pemilik nomor HP. Saldo akan terpotong jika nomor ditemukan.

Query Parameters:

Parameter	Tipe	Wajib	Keterangan
`phone`	string	✅	Nomor HP — format apa saja diterima: `08xxx`, `+628xxx`, `628xxx`

Contoh Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://apigetece.my.id/api/v1/check?phone=08123456789"

Response — Nomor Ditemukan (found):

{
  "success": true,
  "data": {
    "trxId": "CKTG-A1B2C3D4E5",
    "phone": "+628123456789",
    "status": "found",
    "name": "Nama Pemilik",
    "carrier": "Telkomsel",
    "tags": [
      { "tag": "Nama Kontak", "count": 5 },
      { "tag": "Toko Online", "count": 2 }
    ],
    "tagCount": 12,
    "tagsPrivate": false,
    "cost": 500,
    "balance": 24500
  }
}

Response — Nomor Tidak Ditemukan (not_found):

{
  "success": true,
  "data": {
    "trxId": "CKTG-X9Y8Z7W6V5",
    "phone": "+628123456789",
    "status": "not_found",
    "name": "",
    "carrier": "",
    "tags": [],
    "tagCount": 0,
    "tagsPrivate": false,
    "cost": 0,
    "balance": 25000
  }
}

💰 Not Found = Gratis! Jika nomor tidak ditemukan di GetContact, saldo kamu tidak dipotong (cost = 0). Kamu hanya bayar kalau hasilnya ketemu.

Penjelasan field response:

Field	Tipe	Keterangan
`trxId`	string	ID transaksi unik, bisa dipakai untuk recall hasil nanti
`phone`	string	Nomor yang dicek (format internasional +62xxx)
`status`	string	`"found"` atau `"not_found"`
`name`	string	Nama pemilik nomor (kosong jika not found)
`carrier`	string	Operator (Telkomsel, XL, Indosat, dll)
`tags`	array	List nama kontak yang disimpan orang lain, dengan jumlah orang (`count`)
`tagCount`	integer	Total jumlah tag
`tagsPrivate`	boolean	Apakah pemilik nomor mengaktifkan privasi tag
`cost`	integer	Biaya yang dipotong (0 jika not found)
`balance`	integer	Sisa saldo setelah pengecekan

2. Cek Saldo

GET /api/v1/balance

Lihat saldo kamu, harga per cek, dan estimasi jumlah cek yang bisa dilakukan.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://apigetece.my.id/api/v1/balance"

Response:

{
  "success": true,
  "data": {
    "balance": 25000,
    "price": 500,
    "checksAvailable": 50,
    "totalChecks": 120,
    "username": "johndoe"
  }
}

Field	Keterangan
`balance`	Saldo kamu saat ini (dalam Rupiah)
`price`	Harga per 1x pengecekan
`checksAvailable`	Estimasi berapa kali masih bisa cek (balance ÷ price)
`totalChecks`	Total pengecekan yang sudah pernah dilakukan
`username`	Username Telegram kamu

3. Riwayat Pengecekan

GET /api/v1/history?limit={n}&offset={n}

Lihat riwayat pengecekan kamu. Mendukung pagination untuk data banyak.

Query Parameters (opsional):

Parameter	Tipe	Default	Keterangan
`limit`	integer	10	Jumlah data per halaman (max 50)
`offset`	integer	0	Skip berapa data dari awal (untuk halaman berikutnya)

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://apigetece.my.id/api/v1/history?limit=10&offset=0"

Response:

{
  "success": true,
  "data": {
    "total": 120,
    "limit": 10,
    "offset": 0,
    "checks": [
      {
        "trxId": "CKTG-A1B2C3D4E5",
        "phone": "+628123456789",
        "name": "Nama Pemilik",
        "tags": 12,
        "method": "api",
        "cost": 500,
        "date": "2026-10-14 12:30:45"
      }
    ]
  }
}

💡 Pagination: Untuk ambil halaman berikutnya, tambahkan offset sebesar limit. Contoh: halaman 1 = offset=0, halaman 2 = offset=10, halaman 3 = offset=20, dst.

4. Lihat Hasil Cek (by TRX ID)

GET /api/v1/result/{trxId}

Lihat ulang detail hasil pengecekan yang sudah pernah dilakukan. Tidak memotong saldo.

Gunakan trxId yang didapat dari response /check atau /history.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://apigetece.my.id/api/v1/result/CKTG-A1B2C3D4E5"

Response:

{
  "success": true,
  "data": {
    "trxId": "CKTG-A1B2C3D4E5",
    "phone": "+628123456789",
    "status": "found",
    "name": "Nama Pemilik",
    "carrier": "Telkomsel",
    "tags": [
      { "tag": "Nama Kontak", "count": 5 }
    ],
    "tagCount": 12,
    "tagsPrivate": false,
    "cost": 500,
    "date": "2026-10-14 12:30:45"
  }
}

💡 Kenapa ada endpoint ini? Misalnya kamu cek nomor lewat /check tapi lupa simpan hasilnya. Tinggal panggil /result/{trxId} untuk lihat ulang — tanpa potong saldo karena ini bukan pengecekan baru, cuma recall data lama.

5. Cek Harga

GET /api/v1/price

Lihat harga per pengecekan saat ini.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://apigetece.my.id/api/v1/price"

Response:

{
  "success": true,
  "data": {
    "price": 500
  }
}

📋 Ringkasan Semua Endpoint

Method	Endpoint	Fungsi	Potong Saldo?
GET	`/api/v1/check?phone=xxx`	Cek nomor HP	✅ Ya (jika found)
GET	`/api/v1/balance`	Lihat saldo & kuota	❌ Tidak
GET	`/api/v1/history`	Riwayat pengecekan	❌ Tidak
GET	`/api/v1/result/{trxId}`	Lihat ulang hasil cek	❌ Tidak
GET	`/api/v1/price`	Lihat harga per cek	❌ Tidak

❌ Error Handling

Semua error mengembalikan JSON dengan field error. Cek HTTP status code untuk tahu jenis error:

HTTP Code	Artinya	Contoh Response
400	Parameter salah / kurang	`{"error":"Parameter 'phone' is required"}`
401	API key salah, expired, atau tidak ada	`{"error":"Invalid API key"}`
402	Saldo habis, perlu top up	`{"error":"Insufficient balance","balance":0,"price":500}`
403	API belum di-approve admin	`{"error":"API access not approved..."}`
404	Data / TRX ID tidak ditemukan	`{"error":"Result not found"}`
429	Terlalu banyak request (max 30/menit)	`{"error":"Rate limit exceeded..."}`
500	Ada masalah di server	`{"error":"Internal server error"}`
503	Server sedang maintenance	`{"error":"Service is under maintenance"}`

💡 Tips: Selalu cek resp.status_code / resp.status sebelum parsing JSON. Jika dapat 402, arahkan user untuk top up saldo via bot Telegram.

💡 Contoh Penggunaan

cURL

# Cek nomor
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://apigetece.my.id/api/v1/check?phone=08123456789"

# Cek saldo
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://apigetece.my.id/api/v1/balance"

# Riwayat (halaman 1, 10 data)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://apigetece.my.id/api/v1/history?limit=10&offset=0"

# Lihat ulang hasil by TRX ID
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://apigetece.my.id/api/v1/result/CKTG-A1B2C3D4E5"

# Cek harga
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://apigetece.my.id/api/v1/price"

Python

import requests

API_KEY = "your_api_key_here"
BASE = "https://apigetece.my.id"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Cek nomor
resp = requests.get(f"{BASE}/api/v1/check",
    params={"phone": "08123456789"}, headers=headers)

if resp.status_code == 200:
    data = resp.json()["data"]
    if data["status"] == "found":
        print(f"Nama  : {data['name']}")
        print(f"Tags  : {data['tagCount']} tag")
        for t in data["tags"]:
            print(f"  - {t['tag']} ({t['count']}x)")
        print(f"Cost  : Rp {data['cost']}")
        print(f"Saldo : Rp {data['balance']}")
    else:
        print("Nomor tidak ditemukan (gratis)")
elif resp.status_code == 402:
    print("Saldo habis! Top up di bot Telegram")
elif resp.status_code == 401:
    print("API key salah!")
else:
    print(f"Error {resp.status_code}: {resp.json().get('error')}")

JavaScript (Node.js)

const API_KEY = "your_api_key_here";
const BASE = "https://apigetece.my.id";

async function cekNomor(phone) {
  const resp = await fetch(
    `${BASE}/api/v1/check?phone=${encodeURIComponent(phone)}`,
    { headers: { "Authorization": `Bearer ${API_KEY}` } }
  );

  if (resp.status === 200) {
    const { data } = await resp.json();
    if (data.status === "found") {
      console.log(`Nama  : ${data.name}`);
      console.log(`Tags  : ${data.tagCount}`);
      data.tags.forEach(t => console.log(`  - ${t.tag} (${t.count}x)`));
      console.log(`Cost  : Rp ${data.cost}`);
      console.log(`Saldo : Rp ${data.balance}`);
    } else {
      console.log("Nomor tidak ditemukan (gratis)");
    }
  } else if (resp.status === 402) {
    console.log("Saldo habis! Top up di bot Telegram");
  } else if (resp.status === 401) {
    console.log("API key salah!");
  } else {
    const err = await resp.json();
    console.log(`Error ${resp.status}: ${err.error}`);
  }
}

cekNomor("08123456789");

PHP

<?php
$apiKey  = "your_api_key_here";
$baseUrl = "https://apigetece.my.id";
$phone   = "08123456789";

$ch = curl_init("$baseUrl/api/v1/check?phone=$phone");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer $apiKey"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$body = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$response = json_decode($body, true);

if ($httpCode === 200) {
    $data = $response["data"];
    if ($data["status"] === "found") {
        echo "Nama  : " . $data["name"] . "\n";
        echo "Tags  : " . $data["tagCount"] . "\n";
        foreach ($data["tags"] as $t) {
            echo "  - " . $t["tag"] . " (" . $t["count"] . "x)\n";
        }
        echo "Cost  : Rp " . $data["cost"] . "\n";
        echo "Saldo : Rp " . $data["balance"] . "\n";
    } else {
        echo "Nomor tidak ditemukan (gratis)\n";
    }
} elseif ($httpCode === 402) {
    echo "Saldo habis! Top up di bot Telegram\n";
} elseif ($httpCode === 401) {
    echo "API key salah!\n";
} else {
    echo "Error $httpCode: " . ($response["error"] ?? "Unknown") . "\n";
}

📌 Catatan Penting

Rate limit: Maksimal 30 request per menit. Lebih dari itu akan dapat error 429.
Not found = gratis: Saldo hanya dipotong kalau nomor ditemukan. Nomor tidak ditemukan = cost 0.
Top up saldo: Hanya bisa via bot Telegram menggunakan QRIS. Tidak bisa top up lewat API.
Timezone: Semua waktu di response menggunakan WIB (UTC+7).
Key bocor? Segera reset via bot: ketik /api → klik 🔄 Reset API Key. Key lama langsung nonaktif, key baru langsung aktif.
Saldo habis? Top up lagi di bot Telegram. Saldo bisa dipakai di bot, web, dan API sekaligus (satu akun).

❓ FAQ

Q: Berapa harga per cek?

Harga bisa berubah. Cek harga terbaru via endpoint /api/v1/price atau /api/v1/balance.

Q: Nomor format apa yang diterima?

Semua format: 08123456789, 628123456789, +628123456789. Server otomatis normalisasi ke format internasional.

Q: Saldo API sama dengan saldo di bot / web?

Ya, satu akun = satu saldo. Kalau kamu cek lewat bot, web, atau API, semuanya potong dari saldo yang sama.

Q: Bisa top up lewat API?

Tidak. Top up hanya lewat bot Telegram (QRIS). Setelah top up, saldo otomatis tersedia di API juga.

Q: Kenapa dapat error 403?

API key kamu belum di-approve admin. Hubungi admin atau tunggu notifikasi approval di bot Telegram.

Q: Bisa cek nomor luar negeri?

Tergantung ketersediaan data di GetContact. Format nomor tetap harus benar (pakai kode negara).

CekTAG API v1.0