Mulai Cepat

Target halaman ini sempit dan konkret: satu panggilan API yang berhasil, dari komputer atau server Anda, dalam lima langkah.

Sebelum mulai, dua hal yang menghemat waktu Anda:

• Panggilan API hanya dari server, bukan dari browser. Header X-API-Key tidak diizinkan pada request lintas-origin, jadi fetch() dari halaman web akan gagal di preflight. Alasannya di Konvensi API.
• Kalau tujuan Anda memasang form order di situs, Anda tidak butuh API sama sekali. Langsung ke Pasang Form Order.

#Langkah 1 — Minta API key

Belum ada halaman di dashboard untuk membuat key sendiri. Untuk sekarang key diterbitkan atas permintaan.

1. Pastikan Anda punya akses ke akun pemilik (owner) tenant AdForm yang bersangkutan, atau bekerja atas permintaan pemiliknya.
2. Ajukan permintaan lewat Pusat Bantuan.
3. Sebutkan empat hal ini supaya tidak bolak-balik:
   • Nama tenant yang key-nya diminta.
   • Nama integrasi, misalnya "Sinkronisasi katalog CRM internal".
   • Scope yang dibutuhkan. Hanya membaca? Cukup products:read. Perlu membuat produk baru dari template? Tambahkan products:write. Minta seminimal mungkin.
   • Perlu masa berlaku atau tidak. Tanpa masa berlaku, key hidup sampai dicabut.

Anda menerima key satu kali. Bentuknya:

adk_0123456789abcdef0123456789abcdef0123456789abcdef

AdForm hanya menyimpan hash-nya, jadi nilai aslinya tidak bisa ditampilkan ulang. Kalau hilang, key lama dicabut dan Anda dapat key baru.

#Langkah 2 — Simpan key sebagai environment variable

Jangan menaruh key di dalam kode, di file konfigurasi yang ikut ter-commit, di aplikasi mobile, atau di mana pun yang bisa dibaca browser. Key tidak dibatasi per-domain maupun per-IP: siapa pun yang memegangnya bisa memakainya atas nama tenant Anda.

Untuk mencoba di terminal:

export ADFORM_API_KEY='adk_0123456789abcdef0123456789abcdef0123456789abcdef'

Untuk produksi, simpan di secret manager atau environment variable milik platform Anda, dan bacalah dari sana:

$apiKey = getenv('ADFORM_API_KEY');

const apiKey = process.env.ADFORM_API_KEY;

Pastikan key tidak ikut tercetak ke log. Kalau perlu mencatat sesuatu untuk penelusuran, catat 12 karakter pertamanya saja (adk_0123456) — itu memang penanda yang dipakai AdForm juga.

#Langkah 3 — Dapatkan ID produk

Endpoint yang tersedia menunjuk produk lewat ID numerik, bukan slug.

Katakan apa adanya: belum ada endpoint untuk mendaftar produk dengan API key. Jadi ID-nya tidak bisa Anda cari sendiri lewat API. Minta ke pemilik akun tenant — cara paling praktis adalah meminta daftar id dan nama produk sekalian saat mengajukan key di Langkah 1.

Untuk latihan pertama, satu ID produk sudah cukup. Kami pakai 12 sebagai contoh di bawah; ganti dengan ID Anda.

#Langkah 4 — Panggil endpoint pertama

Operasi paling aman untuk dicoba pertama kali adalah operasi baca: mengambil data dan snippet embed sebuah produk. Ia tidak mengubah apa pun.

curl -sS -i \
  -H "X-API-Key: $ADFORM_API_KEY" \
  "https://adform.id/api/products.php?action=embed&id=12"

Tiga bagian yang wajib benar:

Flag -i menampilkan header response, berguna untuk memastikan status dan Content-Type.

#Langkah 5 — Baca respons dan tangani galat

#Kalau berhasil

Status 200, dan body seperti ini (dipendekkan):

{
  "success": true,
  "id": 12,
  "name": "Kaos Polos Hitam",
  "slug": "kaos-polos-hitam",
  "price": 89000,
  "sale_price": 69000,
  "variants": [
    { "dimension": "Ukuran", "options": ["M", "L", "XL"] }
  ],
  "variant_prices": [69000, 69000, 79000],
  "variant_display": "small",
  "embed": {
    "product_id": 12,
    "tenant_id": 34,
    "slug": "kaos-polos-hitam",
    "form_url": "https://adform.id/t/34/kaos-polos-hitam",
    "iframe": "<iframe src=\"https://adform.id/t/34/kaos-polos-hitam\" ...></iframe>",
    "iframe_with_pixel": "<iframe ...></iframe>\n<script src=\"https://adform.id/embed.js\"></script>"
  }
}

Yang perlu dipahami dari respons ini:

• Harga adalah bilangan bulat rupiah. 69000 berarti Rp69.000. Tidak ada desimal dan tidak ada simbol mata uang.
• embed.iframe_with_pixel adalah potongan HTML siap tempel. Itu yang sebaiknya Anda pakai untuk memasang form — jangan merangkai URL-nya sendiri.
• Field baru bisa muncul sewaktu-waktu. Abaikan field yang tidak Anda kenal, jangan menolak respons karenanya.

Penjelasan tiap field ada di API Produk.

#Kalau gagal

Galat selalu berbentuk satu field:

{ "error": "Missing scope: products:read" }

Empat galat yang paling sering muncul pada percobaan pertama:

Aturan penanganannya sederhana: cabangkan pada status HTTP, bukan pada teks error. 4xx selain 429 adalah kesalahan tetap — jangan diulang otomatis. Yang layak diulang hanya 429 (tunggu sesuai header Retry-After) dan 5xx. Daftar lengkapnya di Kode Error.

Perhatikan juga: field success tidak ada pada respons galat. Uji status HTTP, bukan data.success === false.

#Contoh utuh, siap salin

<?php
$apiKey = getenv('ADFORM_API_KEY');
if (!$apiKey) {
    exit("ADFORM_API_KEY belum diisi.\n");
}

$ch = curl_init('https://adform.id/api/products.php?action=embed&id=12');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 15,
    CURLOPT_HTTPHEADER     => [
        'X-API-Key: ' . $apiKey,
        'Accept: application/json',
    ],
]);

$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($body, true);

if ($status !== 200) {
    // 429 → tunggu lalu ulangi. 4xx lain → perbaiki konfigurasi, jangan diulang.
    exit("AdForm {$status}: " . ($data['error'] ?? substr((string)$body, 0, 200)) . "\n");
}

echo "Produk : {$data['name']}\n";
echo "Harga  : {$data['price']}\n";
echo "Form   : {$data['embed']['form_url']}\n";

#Batas laju, sebelum Anda menaikkan beban

/api/products.php dibatasi 60 request per 60 detik per alamat IP, dihitung per IP dan bukan per key. Tidak ada header sisa kuota — satu-satunya sinyal adalah Retry-After yang menyertai 429. Aman kalau Anda menahan diri di sekitar 1 request per detik. Rinciannya di Batas Penggunaan.

#Setelah ini

• Operasi kedua yang tersedia adalah duplikat produk (action=duplicate, scope products:write). Ia membuat produk baru dari produk yang sudah ada dan langsung mengembalikan snippet embed-nya — lihat API Produk.
• Untuk memasang form hasilnya di situs Anda, lanjut ke Pasang Form Order.
• Sebelum menulis integrasi sungguhan, baca Konvensi API. Di sana ada aturan yang berlaku di semua endpoint, termasuk bahwa body harus JSON dan bahwa operasi tulis tidak idempoten.

Kalau ada yang belum tersedia dan Anda membutuhkannya, sampaikan lewat Pusat Bantuan. Permintaan konkret dari integrator yang menentukan urutan pengerjaan kami.