Lewati ke konten utama

Developer Overview

Peta integrasi bagi developer yang memakai API, webhook, widget, dan embedded app Custelio. Halaman ini menunjuk ke dokumen yang menangani tiap jalur; dokumen tujuan memuat prasyarat, langkah, dan batasnya. Anda perlu memilih jalur yang benar, memahami batas status produk, dan tahu mana yang aman dipakai untuk kasus Anda.

Tujuan​

Developer memilih jalur integrasi yang benar, memahami batas status produk, dan tahu mana yang aman dipakai untuk kasusnya.

Untuk siapa​

Developer/integrator yang membangun integrasi server-side, frontend, atau alur otomatisasi.

Prasyarat​

  • Tenant dan akun telah dibuat; kredensial API diberikan administrator.
  • Konsep tenant, token, dan status fitur dipahami; lihat Glosarium bila perlu.

Jalur integrasi​

API​

Referensi API — autentikasi, tenant context, request ID, idempotency, dan pemakaian dokumen OpenAPI.

Batasan referensi API: OpenAPI adalah referensi terbatas, bukan bukti semua endpoint tersedia. Drift yang diketahui: operasi tercantum yang belum terhubung ke runtime, status implemented/planned yang tidak sama dengan kode, skema yang belum terbukti lewat integrasi provider, dan parity Chatwoot yang belum lengkap. Verifikasi endpoint pada deployment dan status fitur sebelum integrasi. Tidak ada klaim parity penuh.

Webhook​

Inbound dan outbound webhooks — verifikasi signature HMAC, deduplikasi event, retry, dan batas delivery. Webhook outbound belum tersedia penuh pada seluruh alur; status tetap limited.

Widget dan embedded app​

Widget dan embedded apps — integrasi eksperimental untuk menanamkan pengalaman CRM dengan public widget key atau embedded app ber-origin allowlist. Public key bukan authorization; jangan menaruh secret di bundle publik.

Prinsip integrasi​

  1. Autentikasi diuji server-side. UI yang menyembunyikan tombol bukan kontrol akses.
  2. Catat request ID setiap respons untuk korelasi log dan dukungan.
  3. Gunakan idempotency key unik untuk setiap perubahan outbound; retry hanya dengan key yang sama.
  4. Jangan menganggap HTTP 201 = pesan terkirim. Delivery harus mengikuti status provider/webhook.
  5. Jangan menonaktifkan keamanan sebagai workaround. Verifikasi HMAC, origin check, dan TLS tetap aktif.
  6. Jangan mencatat secret atau PII pada log atau payload contoh.

Jika terjadi masalah​

  • 400 payload/signature salah: perbaiki serialisasi/payload dan Content-Type; jangan menonaktifkan verifikasi. Lihat Inbound dan outbound webhooks.
  • 401/403 autentikasi atau izin ditolak: perbaiki token/tenant/secret/scope; jangan memakai kredensial lebih luas sebagai jalan pintas. Lihat Referensi API.
  • 404 endpoint tidak ditemukan: periksa path, tenant, dan status fitur; OpenAPI dapat menampilkan operasi yang belum terhubung runtime.
  • 409 konflik state: ambil state terbaru atau gunakan idempotency key yang sama; jangan mengirim ulang dengan key baru.
  • 429 rate limit: hormati Retry-After dan gunakan backoff.
  • 501 operasi belum didukung: periksa kemampuan provider; jangan fallback diam-diam ke jalur yang mengubah arti permintaan.
  • Webhook tidak diterima / gagal verifikasi: periksa signature/secret dan deduplikasi event; lihat Inbound dan outbound webhooks.
  • Widget/embedded ditolak (401/403): perbaiki origin allowlist, token scope, atau role; jangan menaruh secret di bundle publik. Lihat Widget dan embedded apps.

Tanda berhasil​

Developer memilih jalur sesuai kebutuhan, memverifikasi dukungan endpoint pada deployment, dan integrasi berjalan dengan autentikasi serta idempotensi yang benar.

Batasan​

Referensi API terbatas, webhook outbound sebagian belum penuh, dan widget/embedded app masih eksperimental. Delivery WhatsApp dan sebagian kemampuan provider bergantung deployment; verifikasi pada environment Anda sendiri.

Tugas terkait​