Formulir dan lead

Cara kerjanya

Formulir adalah definisi kecil yang disimpan admin untuk sebuah brand: kunci, daftar field, dan pesan sukses. Situs Anda mengirim input pengunjung ke endpoint publik. ATLAS memeriksanya terhadap definisi, menyimpannya sebagai lead, mengantrekan pengiriman ke CRM, memberi tahu tim Anda, dan, bila pengunjung setuju, melaporkan konversi ke platform iklan.

Formulir bergantung pada modul forms. Jika sebuah brand mematikan modul itu, endpoint publik menjawab 404 dan panggilan manage untuk formulir dan lead menjawab 403.

Membuat formulir

Formulir dikelola oleh admin. Semua panggilan berada di bawah https://api.atlascms.id/v1/manage dan memerlukan sesi yang sudah masuk serta header X-Brand-Id.

Menampilkan formulir milik brand, diurutkan menurut kunci. POST /v1/manage/forms membuat formulir (201), PUT /v1/manage/forms/{form} memperbaruinya, dan DELETE /v1/manage/forms/{form} menghapusnya (204). Setiap perubahan dicatat di log audit.

Setiap field di dalam fields punya properti berikut:

{
  "key": "contact",
  "name": "Contact form",
  "fields": [
    { "name": "name", "type": "text", "required": true },
    { "name": "email", "type": "email", "required": true },
    { "name": "phone", "type": "phone" },
    { "name": "topic", "type": "select", "options": ["Sales", "Support", "Partnership"] },
    { "name": "message", "type": "textarea", "max": 2000 }
  ],
  "success_message": "Terima kasih, kami akan membalas dalam satu hari kerja.",
  "active": true
}

Beri nama field `email` dan `phone`

Event pelacakan di bawah membaca field bernama email dan phone. Pakai nama itu bila Anda ingin konversi dicocokkan di platform iklan.

Mengirim dari situs Anda

Kirim input pengunjung sebagai JSON. Hanya field yang dideklarasikan formulir yang diterima dan disimpan. Brand dikenali dari token baca Anda (Authorization: Bearer atl_read_...) atau dari header Host.

curl -s -X POST "https://api.atlascms.id/v1/public/forms/contact" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Atlas-Client-Ip: 203.0.113.7" \
  -d '{
    "fields": { "name": "Sari", "email": "[email protected]", "message": "Halo" },
    "consent": true,
    "utm": { "utm_source": "newsletter" },
    "source_page": "/contact",
    "website": ""
  }'

{ "data": { "id": "01m518vvbf8txh40wcvwhvtzyd", "message": "Terima kasih, kami akan membalas dalam satu hari kerja." } }

Validasi mengikuti tipe field: email harus alamat yang valid (maksimal 254 karakter), phone menerima + opsional, angka, spasi, tanda kurung, dan tanda hubung (6 sampai 20 karakter), dan select harus salah satu opsi yang dideklarasikan.

Teruskan pengunjung, bukan server Anda

Bila server situs Anda yang mengirim formulir, sertakan token baca beserta dua header berikut agar yang dinilai dan disimpan adalah pengunjung, bukan server Anda.

ATLAS hanya memercayai header ini pada panggilan yang membawa token baca. Tanpa token, alamat koneksi yang dipakai. Alamat IP mentah tidak pernah disimpan.

Mengelola kotak masuk lead

Lead berisi data pribadi. Setiap panggilan di bagian ini memerlukan publisher atau admin. Editor mendapat 403, bahkan untuk membaca.

Lead punya dua status. status menunjukkan posisinya di tim Anda: new (bawaan), contacted, qualified, spam, atau archived. delivery_status adalah status pengiriman ke CRM: pending, forwarded, failed, atau skipped.

Filter: form (kunci formulir), status, delivery, assigned (id anggota, me, atau none), from dan to (hari Y-m-d dalam zona waktu brand), q (mencari di field yang dikirim, catatan, dan halaman sumber), sort (created_at atau status, awali - untuk membalik), dan per_page (1 sampai 100, bawaan 50). meta.status_counts memberi jumlah per status untuk filter yang aktif.

curl -s -X PATCH "https://api.atlascms.id/v1/manage/form-submissions/01m518vvbf8txh40wcvwhvtzyd" \
  -H "X-Brand-Id: $BRAND_ID" -H "Content-Type: application/json" \
  --cookie "$SESSION" \
  -d '{ "status": "contacted", "note": "Dihubungi hari Senin", "assigned_to": null }'

Spam dihitung terpisah: ringkasan dan dasbor menghitung setiap kiriman yang bukan spam.

Ekspor ke CSV

Memakai filter yang sama dengan daftar dan mengalirkan unduhan text/csv (UTF-8 dengan BOM, 10 permintaan per menit). Kolomnya adalah id, created_at, form, status, delivery_status, locale, consent, source_page, referrer, nilai utm_*, fbclid, gclid, note, dan satu kolom field_<name> untuk setiap field formulir. Ekspor dicatat di log audit beserta filternya.

Sel yang diawali =, +, -, @, tab, atau carriage return diberi awalan ', sehingga spreadsheet tidak pernah menjalankan nilai kiriman sebagai rumus.

Meneruskan lead ke CRM

Begitu lead tersimpan, ATLAS mengantrekan pengiriman ke integrasi crm milik brand. Tanpa endpoint yang dikonfigurasi, lead tetap berada di ATLAS dengan delivery_status: skipped. Pengiriman yang gagal dicoba total 5 kali, dengan jeda 10 detik, 1 menit, 5 menit, dan 15 menit di antaranya, lalu ditandai failed dengan alasan singkat. Gunakan retry untuk mengirim ulang.

Atur dengan PUT /v1/manage/integrations/crm (admin):

{
  "enabled": true,
  "config": {
    "endpoint": "https://crm.example.com/api/leads",
    "auth_header": "X-Api-Key",
    "auth_scheme": "none",
    "payload": "atlas"
  }
}

Token adalah secret yang hanya bisa ditulis. Simpan dengan PUT /v1/manage/secrets/crm/token dan isi { "value": "..." }. Token dienkripsi, tidak pernah dikembalikan, dan tidak pernah masuk log atau baris audit. Menyimpan endpoint yang berbeda menghapus token yang tersimpan, jadi masukkan lagi.

Payload atlas bawaan berbentuk seperti ini. Setiap permintaan juga membawa X-Atlas-Delivery berisi id lead, sehingga CRM Anda bisa mengabaikan pengiriman ulang.

{
  "id": "01m518vvbf8txh40wcvwhvtzyd",
  "brand": "atlascms",
  "form": "contact",
  "locale": "id",
  "fields": { "name": "Sari", "email": "[email protected]", "message": "Halo" },
  "utm": { "utm_source": "newsletter" },
  "fbclid": null,
  "gclid": null,
  "source_page": "/contact",
  "referrer": null,
  "consent": true,
  "submitted_at": "2026-10-21T14:42:20+00:00"
}

Pelacakan konversi

Bila pengunjung mencentang persetujuan ("consent": true), ATLAS juga mengirim event konversi Lead dari server ke setiap integrasi platform iklan yang aktif (meta_pixel dengan token Conversions API, tiktok_pixel dengan access token). Id lead menjadi id event, sehingga event pixel browser yang sama tidak terhitung dua kali. Email dan telepon di-hash sebelum keluar dari ATLAS. Lead tanpa persetujuan tidak mengirim event.

Kirim event uji dengan POST /v1/manage/integrations/{provider}/test (admin, 10 per menit). test_event_code opsional menjaga event itu tetap di luar laporan sungguhan.

Notifikasi

Saat lead masuk, setiap publisher dan admin brand mendapat notifikasi di dalam aplikasi. Lima lead pertama dalam jendela 10 menit diberitahukan satu per satu. Setelahnya, satu notifikasi ringkasan berisi jumlah dikirim per jendela, sehingga lonjakan kiriman tidak membanjiri tim.

Aturan privasi

• Hanya publisher dan admin yang bisa membaca, mengubah, mengekspor, atau menghapus lead. Lead milik brand lain dijawab 404.
• Alamat IP pengunjung hanya disimpan sebagai hash.
• Secret, token, dan nilai yang dikirim tidak pernah muncul di baris audit, log, atau URL. Log audit mencatat bahwa lead berubah, tidak pernah isi catatannya.
• Backup brand tidak menyertakan field lead. Lihat Backup.
• Menghapus lead bersifat permanen. Hapus bila diminta, dan jaga agar pemberitahuan privasi Anda sesuai dengan data yang Anda kumpulkan.