Lewati ke konten utama

Scoutello API

Scoutello API adalah API server-ke-server untuk menyinkronkan kontak, tugas, protokol, peluang, proyek, pencapaian, dan acara organisasi secara dua arah. API ini juga menyediakan riwayat email keluar hanya-baca, pencarian anggota yang dapat ditugaskan, serta penemuan tag berdasarkan entitas. Rute GET/list inkremental dan upsert batch idempoten merupakan dasar sinkronisasi dalam versi ini. API ini tidak menyediakan operasi penghapusan atau webhook.

URL dasar API adalah:

https://admin.scoutello.com/api/v1

URL tersebut juga ditampilkan di Pengaturan organisasi → Developer/API. Dokumen OpenAPI tersedia di:

https://admin.scoutello.com/api/v1/openapi.json

Membuat dan melindungi kunci​

Untuk organisasi modular, modul CRM harus aktif selain cakupan yang diperlukan untuk kunci tersebut. Kunci yang valid tidak dapat mengaktifkan modul yang belum tersedia. Permintaan akan mengembalikan HTTP 403 dengan kode kesalahan module_not_active jika akses CRM tidak tersedia. Pengguna dengan hak administrasi organisasi dapat meninjau atau mengaktifkan CRM di Langganan; coba lagi setelah akses aktif.

Pengguna dengan hak administrasi organisasi dapat membuat integrasi dan kunci API di Pengaturan organisasi → Developer/API. Kunci lengkap hanya ditampilkan sekali. Salin kunci tersebut ke pengelola rahasia sebelum menutup dialog; Scoutello tidak dapat menampilkan kunci lengkap itu lagi.

  • Gunakan integrasi dan kunci terpisah untuk setiap sistem eksternal dan lingkungan.
  • Berikan hanya cakupan yang diperlukan oleh sistem tersebut.
  • Jangan pernah menempatkan kunci di kode browser, URL, sistem kontrol versi, log, pesan dukungan, atau penyimpanan sisi klien.
  • Lakukan rotasi kunci secara berkala. Saat integrasi aktif menjalani rotasi, kunci pengganti langsung berfungsi dan kunci sebelumnya tetap valid selama tidak lebih dari 15 menit agar sistem eksternal dapat beralih tanpa downtime. Masa kedaluwarsa sebelumnya tetap berlaku, sehingga kunci sebelumnya dapat berhenti berfungsi lebih cepat.
  • Jika kunci mungkin telah terekspos, jeda integrasi sebelum melakukan rotasi. Menjeda integrasi akan menolak sementara semua kuncinya. Rotasi saat integrasi dijeda tidak memiliki masa tumpang tindih: kunci sebelumnya tetap dinonaktifkan, dan kunci pengganti tetap dinonaktifkan hingga integrasi dilanjutkan.
  • Cabut seluruh integrasi secara permanen saat memutuskan sistem eksternal. Pencabutan akan menonaktifkan semua kuncinya dan tidak dapat dibatalkan.

Kirimkan kunci pada setiap permintaan yang diautentikasi:

Authorization: Bearer YOUR_API_KEY

Autentikasi Bearer lebih disarankan. Klien yang tidak dapat menetapkan Authorization dapat menggunakan x-api-key sebagai gantinya. Jangan kirim kedua header; permintaan dengan nilai yang berbeda pada kedua header akan ditolak.

API ini ditujukan untuk klien backend dan tidak mengaktifkan akses browser lintas asal.

Gunakan GET /whoami setelah mengonfigurasi kunci untuk memverifikasi integrasi, organisasi, cakupan, dan batas kunci tanpa mengambil data pribadi pengguna.

Cakupan​

CakupanMemungkinkan
contacts.readMencantumkan dan mengambil kontak. Kontak akun organisasi dan kontak anggota yang memiliki akses tidak disertakan.
contacts.writeMemvalidasi dan menerapkan upsert kontak.
tasks.readMencantumkan dan mengambil tugas nonpribadi.
tasks.writeMemvalidasi dan menerapkan upsert tugas.
protocols.readMencantumkan dan mengambil protokol nonpribadi.
protocols.writeMemvalidasi dan menerapkan upsert protokol.
opportunities.readMencantumkan dan mengambil peluang.
opportunities.writeMemvalidasi dan menerapkan upsert peluang.
projects.readMencantumkan dan mengambil proyek.
projects.writeMemvalidasi dan menerapkan upsert proyek dan peserta.
milestones.readMencantumkan dan mengambil pencapaian proyek.
milestones.writeMemvalidasi dan menerapkan upsert pencapaian.
members.readMencantumkan anggota yang telah diterima hanya dengan ID Pelanggan anggota, ID Pengguna, dan nama tampilan.
events.readMencantumkan dan mengambil acara serta jadwal inti.
events.writeMemvalidasi dan menerapkan upsert acara.
mails.readMembaca riwayat email keluar milik organisasi yang terkirim dan gagal.
mail-drafts.readMembaca draf persetujuan email mandiri dan status pengiriman milik integrasi ini.
mail-drafts.writeMenyiapkan atau merevisi draf email untuk persetujuan manusia; tidak pernah menyetujui atau mengirimkannya.
tags.readMenemukan tag yang dapat dipilih untuk jenis entitas yang didukung.

Tugas dan protokol pribadi tidak pernah dikembalikan oleh API ini. Cakupan yang tidak ada akan menghasilkan kesalahan otorisasi; kondisi tersebut tidak diperlakukan sebagai hasil kosong.

Kontak CRM nonanggota dapat dibaca dan direferensikan meskipun tertaut ke login Scoutello. Respons hanya berisi kolom CRM organisasi, tanpa data identitas atau akses Pengguna. Kontak dengan peran, izin, undangan, penerimaan, atau status akun organisasi tetap tersembunyi. Pengeditan kontak yang tertaut ke login tetap dilarang (protected_contact), termasuk kolom CRM yang sebenarnya tidak berubah. Untuk mereferensikan kontak yang sudah ada dan dapat dibaca dari tugas/protokol, contacts.write dapat membuat tautan eksternalnya hanya dengan externalId, scoutelloId, dan externalUpdatedAt opsional. Pembaruan berikutnya yang hanya mengubah metadata tautan menggunakan externalId dan externalUpdatedAt opsional; hilangkan scoutelloId bootstrap setelah tertaut. Proses ini tidak pernah mengubah kontak atau Penggunanya. Penetapan anggota yang telah diterima menggunakan proyeksi members.read terpisah.

Kunci baru menggunakan awalan sctl_api_ dan hanya dimulai dengan contacts.write. Cakupan lainnya merupakan pilihan eksplisit yang harus diberikan oleh administrator organisasi saat membuat atau merotasi kunci. Kredensial yang sudah ada mempertahankan cakupan saat ini dan tetap valid.

Kontak tertaut ke proyek dan draf email​

Upsert kontak menerima pasangan projectScoutelloId / projectExternalId dan companyScoutelloId / companyExternalId opsional (pilih satu dari setiap pasangan). Kontak, hubungan dengan perusahaan, dan keanggotaan proyek disimpan secara atomik untuk setiap item. Penambahan keanggotaan proyek memerlukan projects.write; referensi yang dihilangkan mempertahankan hubungan dan keanggotaan lainnya. Hasil pembacaan detail kontak menyertakan projectParticipations jika projects.read diberikan. Agen proyek penjualan harus menyertakan referensi proyek secara eksplisit, bahkan saat menggunakan kembali kontak.

Draf mandiri menggunakan sistem persetujuan manusia yang sudah ada, tanpa eksekusi alur kerja:

MetodeJalurTujuan
GET/mail-draftsDraf milik integrasi dengan pagination; filter projectScoutelloId dan status opsional.
GET/mail-drafts/{scoutelloId}Versi saat ini, tautan peninjauan, hash konten, status persetujuan/pengiriman, dan ID email pada akhirnya.
GET/mail-drafts/external/{externalId}Mencari ID eksternal integrasi yang stabil.
POST/mail-drafts/batch-upsertMemvalidasi atau menerapkan persiapan draf.

Persiapan draf memerlukan mail-drafts.write, contacts.read, dan projects.write. Kontak yang dirujuk menjadi peserta proyek. Pemberi persetujuan harus merupakan anggota organisasi yang telah diterima dan memiliki izin untuk mengedit email. Pemilihan pengirim menggunakan pengaturan pengirim organisasi atau pribadi yang sudah diizinkan untuk anggota tersebut; alamat From sembarang tidak diterima.

{
"mode": "validate",
"records": [{
"externalId": "sales:indoor:outreach:museum:v1",
"expectedVersion": 0,
"project": { "externalId": "sales:indoor" },
"contact": { "externalId": "sales:indoor:museum:person" },
"approverScoutelloUserId": "ACCEPTED_MEMBER_USER_ID",
"senderScope": "organization",
"content": {
"to": ["verified-recipient@example.com"],
"subject": "Indoor tour proposal",
"body": "The intended email copy only.",
"notes": "Internal research and review context; not sent."
}
}]
}

Periksa setiap hasil validasi sebelum mengulangi permintaan dengan mode: "apply". Baca ID yang dihasilkan untuk memperoleh reviewUrl, draftVersion, contentHash, status, dispatchStatus, dan mailScoutelloId. Gunakan expectedVersion: 0 hanya untuk pembuatan, dan gunakan versi yang baru dikembalikan untuk revisi. Konteks dan pemberi persetujuan tidak dapat diubah; draf yang telah ditinjau/dikirim akan menolak konten yang diubah. Percobaan ulang yang identik akan mengembalikan draf asli.

Draf muncul di tab Email proyek/kontak dan notifikasi persetujuan di dasbor. Persiapan API tidak mengirim email apa pun, termasuk email notifikasi; perilaku email notifikasi workflow yang sudah ada tetap tidak berubah. Orang yang ditugaskan dapat mengedit penerima, subjek, isi, dan lampiran yang didukung, menyimpan versinya, lalu Approve & send. Integrasi tidak dapat melakukan persetujuan atau pengiriman. Pengiriman yang gagal atau ambigu tidak pernah dicoba ulang secara membabi buta. Saat mengonversi draf berbasis protokol, pertahankan protokolnya dan buat referensi silang ke penggantinya.

Akses MCP​

Kunci API dan cakupan Scoutello yang sama dapat digunakan dengan endpoint MCP HTTP yang dapat dialirkan:

https://admin.scoutello.com/api/v1/mcp

Konfigurasikan klien MCP untuk mengirim Authorization: Bearer YOUR_API_KEY. URL /api/mcp lama tetap menjadi alias kompatibilitas jalur, tetapi klien baru sebaiknya menggunakan endpoint berversi. Kredensial sctl_mcp_ sebelumnya tidak diterima; ganti dengan kunci integrasi API Scoutello.

Alat MCP dipetakan langsung ke kontrak REST dan menggunakan skema runtime, pemeriksaan tenant, siklus proses integrasi, batas laju, serta metode layanan yang sama. Misalnya, contacts_list, contacts_get, contacts_get_by_external_id, dan contacts_batch_upsert mencerminkan empat rute kontak. Pola yang sama berlaku untuk tugas, protokol, peluang, proyek, pencapaian, dan acara; mail menyediakan mails_list dan mails_get, anggota menyediakan members_list, sedangkan tag menyediakan tags_list.

Server hanya mengiklankan alat yang diizinkan oleh cakupan kunci saat ini. Kunci dengan contacts.read dapat menemukan alat baca kontak, tetapi tidak contacts_batch_upsert; kunci dengan contacts.write mendapatkan alat pembaruan batch, tetapi tidak alat baca. whoami selalu tersedia. Alat tulis memiliki efek langsung yang sama seperti padanan REST-nya, jadi gunakan mode: "validate" jika pemanggil perlu memeriksa batch tanpa menerapkannya.

MCP juga bersifat server-ke-server dan tidak mengaktifkan akses browser lintas asal. Transport JSON-RPC memerlukan URL khusus, sehingga tidak dapat berbagi URL sumber daya REST individual meskipun autentikasi dan perilaku datanya sama.

Untuk konfigurasi klien, verifikasi, pemetaan alat, dan petunjuk pemecahan masalah lengkap, lihat panduan integrasi MCP.

Membaca rekaman​

Kontak, tugas, protokol, peluang, proyek, pencapaian, dan acara menggunakan rute baca yang sama:

GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}

Ganti contacts dengan tasks, protocols, opportunities, projects, milestones, atau events untuk sumber daya sinkronisasi lainnya. externalId muncul di DTO baca ketika rekaman telah ditautkan oleh integrasi ini.

Respons daftar memiliki pembungkus berikut:

{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}

limit harus berada dalam rentang 1 hingga 100. Hasil diurutkan berdasarkan waktu efektif saat representasi API publiknya berubah, lalu berdasarkan ID Scoutello. Waktu efektif ini dapat lebih lambat daripada updatedAt entitas yang dikembalikan ketika metadata tautan integrasi berubah. Kursor bersifat opak: simpan dan kirim tanpa perubahan, serta jangan menarik makna dari isinya.

Respons pertama menetapkan snapshotAt untuk penelusuran tersebut. Ikuti nextCursor hingga hasMore bernilai false sebelum memulai pembacaan inkremental lainnya. Hal ini mencegah perubahan rekaman selama paginasi membuat penelusuran saat ini tidak stabil.

Untuk sinkronisasi inkremental, konsumsi setiap halaman kursor, lalu simpan snapshotAt dari penelusuran tersebut sebagai stempel waktu batas atas. Teruskan nilai tersebut sebagai nilai updatedSince ISO 8601 pada penelusuran berikutnya. Batas bawah bersifat inklusif, sehingga percobaan ulang snapshot yang telah selesai dapat mengembalikan rekaman batas, tetapi tidak dapat melewatkannya.

Respons satu rekaman memiliki pembungkus berikut:

{
"data": {},
"requestId": "request-id"
}

Respons satu kontak juga menyertakan array relations. Setiap relasi mempertahankan ID relasi Scoutello, waktu pembuatan, jenis, catatan, serta referensi kontak connectedFrom dan connectedTo. Referensi kontak berisi ID Scoutello dan ID eksternal integrasi ini jika tersedia. Kontak yang dikecualikan oleh batas privasi akses organisasi API tidak ditampilkan melalui relasi. Respons daftar kontak tetap ringkas dan tidak menyertakan relasi; gunakan salah satu rute kontak tunggal jika detail hubungan diperlukan.

Filter kerja dan cakupan kursor​

Daftar kontak menerima search, type (person, company, supplier, other), status, dan tagIds. Pencarian dipangkas, tidak membedakan huruf besar-kecil, dan dibatasi hingga 200 karakter / 10 token yang dipisahkan spasi. Setiap token harus muncul setidaknya di salah satu dari firstName, lastName, atau companyName, termasuk nama perusahaan lama yang tersimpan di lastName. Karakter seperti % dan _ dicocokkan secara literal. Tag menggunakan pencocokan any-of dengan 1–50 ID. Semua filter yang diberikan digabungkan dengan AND. REST menyandikan ID tag sebagai parameter berulang; MCP menyediakan array:

GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two

Kursor kontak terikat pada organisasi, integrasi, dan setiap filter. Pertahankan filter di setiap halaman; perubahan filter akan menolak kursor. Urutan/duplikasi tag dan urutan/penulisan huruf besar-kecil/spasi token pencarian tidak mengubah filter efektif.

Rute daftar kerja menerima filter tambahan berikut; kombinasi resource/kolom lainnya akan ditolak:

ResourceFilter
TasksprojectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter
ProtocolsprojectScoutelloId, milestoneScoutelloId, status (draft atau final)
OpportunitiesprojectScoutelloId, stage, ownerScoutelloUserId
Projectsstatus, assignedContactScoutelloId
MilestonesprojectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter

dueBefore bersifat eksklusif; dueAfter bersifat inklusif. Keduanya membandingkan tanggal jatuh tempo tugas atau tanggal berakhir milestone; rekaman tanpa tanggal tersebut tidak akan cocok. Gunakan tanggal-waktu ISO yang menyertakan zona waktu. Semua filter diterapkan sebelum pagination. Lanjutkan cursor dengan filter yang persis sama, termasuk updatedSince, serta organisasi/integrasi yang sama. Ukuran halaman dapat berubah. Cursor lama yang tidak memiliki cakupan harus memulai ulang dari stempel waktu high-water yang tersimpan setelah rilis ini.

Projects, milestone, penugasan, dan catatan​

GET /members (MCP members_list) menggunakan pagination standar dan memerlukan members.read. Responsnya berisi scoutelloId (ID member Customer), scoutelloUserId (ID User), dan displayName. Hanya member organisasi yang diterima dan memiliki peran yang akan ditampilkan; pencarian ini tidak mengekspos email atau izin.

Tasks menerima assignedScoutelloUserIds; opportunities menggunakan ownerScoutelloUserId. Projects dan milestones menggunakan assignedContacts: [{"scoutelloId":"member-customer-id"}]. Penugasan memerlukan member yang telah diterima di organisasi kredensial. Penugasan yang dihilangkan tetap tidak berubah; [] menghapusnya. Impor project, milestone, task, dan protocol berlangsung tanpa notifikasi: proses tersebut tidak mengirim notifikasi penugasan atau komunikasi.

Event assignedContacts mendukung kontak CRM yang dapat dibaca serta member yang telah diterima, yang diberikan berdasarkan ID Customer member. Member yang telah diterima tetap tidak tersedia sebagai referensi kontak CRM biasa atau target tautan eksternal; gunakan kolom penugasan member untuk menetapkan tanggung jawab tim.

Buat milestone dengan name dan salah satu dari projectScoutelloId atau projectExternalId. Milestone mendukung description (Markdown), status (open, in_progress, completed, closed), startDate/endDate yang dapat bernilai null, order (default-nya 0), dan assignedContacts. Tanggal selesai tidak boleh lebih awal daripada tanggal mulai. Setiap milestone memiliki tautan eksternal stabil yang cakupannya dibatasi pada integrasi. Project-nya tidak dapat diubah melalui API. Pembuatan dan pembaruan akan melokalkan nama/deskripsi ke bahasa organisasi.

Task dan protokol menerima referensi project, milestone, dan opportunity sebagai <entity>ScoutelloId atau <entity>ExternalId, misalnya milestoneExternalId. Gunakan hanya satu ejaan untuk setiap relasi, termasuk saat menghapus relasi dengan null. Semua relasi harus berasal dari organisasi kredensial. Referensi yang hanya berisi milestone akan menentukan project secara otomatis; project yang tidak cocok, atau penghapusan project secara eksplisit saat milestone-nya tetap dipertahankan, akan ditolak. Opportunity tertaut yang memiliki project harus sesuai dengan project pekerjaan. Relasi yang tidak dicantumkan akan mempertahankan nilai saat ini; null yang dicantumkan secara eksplisit akan menghapus relasi jika konteks yang tersisa valid. Respons pembacaan menampilkan kedua ejaan ID dan penugasan task.

Perencanaan task dan alur kerja​

status pada task adalah kunci immutable untuk status dalam alur kerja efektif task, bukan enum tetap. Baca alur kerja organisasi dan project yang tersedia dengan GET /task-workflows menggunakan cakupan tasks.read. Setiap status mencakup key, label, type siklus hidup (backlog, unstarted, started, completed, atau cancelled), warna, urutan, flag default, dan status arsip. Entri project menunjukkan apakah alur kerja organisasi diwarisi. Konfigurasi alur kerja tetap dikelola melalui dashboard.

Task menerima priority yang dapat bernilai null (low, medium, high, atau urgent) dan estimatedEffortMinutes, serta startDate dan dueDate yang dapat bernilai null. Respons pembacaan task mencakup statusType yang didenormalisasi, referensi parent, referensi subtask ringkas, serta referensi blockedBy / blocks.

Buat atau perbarui subtugas satu tingkat menggunakan parentTaskScoutelloId atau parentTaskExternalId; null mengubahnya menjadi tugas tingkat teratas. Dependensi menggunakan array referensi { "scoutelloId": "..." } atau { "externalId": "..." } di blockedBy dan blocks. Kolom relasi yang tidak dicantumkan akan mempertahankan nilainya, sedangkan array dependensi kosong akan menghapus arah tersebut. API menolak subtugas bertingkat, dependensi induk-anak, dependensi lintas organisasi, duplikasi, referensi ke diri sendiri, serta siklus langsung atau transitif.

Filter daftar tugas menerima status alur kerja yang harus sama persis, siklus hidup statusType, priority, parentState (top_level, subtask, atau parent), serta blockedState (blocked, blocking, atau unblocked).

Protokol juga menerima status: "draft" | "final" (rekaman baru secara default menggunakan final). Protokol baru memerlukan type, date, serta kontak atau konteks proyek/milestone yang valid. contactExternalId: null hanya menghapus kontaknya jika konteks proyek/milestone tetap ada. Dengan demikian, catatan proyek internal dapat dibuat dan dibaca tanpa membuat-buat pelanggan. Draft/final menjelaskan status catatan dan tidak pernah mengirim komunikasi. Tugas dan protokol privat tetap tidak dapat diakses.

Peserta proyek​

Project participants berisi upsert tambahan yang menggunakan referensi contact sebagai kunci, misalnya:

{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}

Peserta menjelaskan prospek/pelanggan yang terkait dengan suatu proyek; anggota yang bertanggung jawab menggunakan penugasan. Peserta yang tidak dicantumkan, array kosong, dan kolom peserta yang tidak dicantumkan akan mempertahankan data yang ada. null menghapus role, notes, atau groupScoutelloId. Kontak teridentifikasi yang duplikat dalam satu payload akan ditolak. Grup harus sudah menjadi bagian dari proyek yang dipilih; hasil pembacaan mencakup participantGroups (ID/nama), ID peserta, kontak, peran, catatan, dan ID grup. Penghapusan peserta atau pembuatan grup saat ini tersedia di dasbor.

Upsert rekaman secara massal​

Tulis hingga 100 rekaman menggunakan rute batch resource tersebut:

POST /contacts/batch-upsert
Content-Type: application/json
{
"mode": "apply",
"records": [
{
"externalId": "record-123",
"externalUpdatedAt": "2026-09-01T11:45:00.000Z",
"type": "person",
"firstName": "Alex",
"lastName": "Example",
"email": "alex@example.com"
}
]
}

Batch tugas menyelesaikan rekaman tugasnya terlebih dahulu sebelum menerapkan relasi induk dan dependensi. Pemrosesan dua tahap ini memungkinkan induk, tugas yang memblokir, atau tugas yang diblokir untuk merujuk tugas lain yang dibuat dalam batch yang sama berdasarkan ID eksternalnya, terlepas dari urutan rekaman.

Gunakan dokumen OpenAPI untuk field dan batasan validasi setiap resource. Setiap record harus memiliki externalId yang stabil dengan panjang antara 1 hingga 200 karakter. Perlakukan sebagai pengenal teknis opak: jangan gunakan alamat email, nama, rahasia API, atau data pribadi lainnya. externalUpdatedAt bersifat opsional, tetapi sangat disarankan jika sistem sumber menyediakan stempel waktu modifikasi yang andal.

Ukuran isi permintaan dibatasi hingga 1 MiB. mode secara default menggunakan apply:

  • apply memvalidasi dan menulis record yang diterima.
  • validate menjalankan validasi dan pencocokan yang sama tanpa menulis data, lalu mengembalikan hasil would_*.

Untuk impor kontak, matchByEmail dapat diatur ke true dalam permintaan. Nilai defaultnya adalah false; ID eksternal merupakan batas identitas default yang lebih aman.

Field yang tidak disertakan mempertahankan nilai saat ini. null yang diberikan secara eksplisit akan menghapus field nullable, sedangkan array assignment/tag kosong yang diberikan akan menghapus relasi tersebut. Project participants adalah upsert aditif: array kosong tidak mengubah daftar. Penulisan tag kontak, tugas, peluang, dan acara menggunakan ID tag Scoutello. ID eksternal relasi hanya dicari melalui tautan yang termasuk dalam integrasi saat ini, sedangkan ID pengguna Scoutello yang digunakan untuk kepemilikan atau penanggung jawab harus mengidentifikasi anggota yang diterima dalam organisasi saat ini.

Pembuatan peluang memerlukan akun atau kontak, dan peluang yang kalah memerlukan alasan kekalahan. Jumlah moneter menggunakan satuan sen dalam bilangan bulat. Nama dan deskripsi project serta acara dibaca dan ditulis dalam bahasa yang dikonfigurasi untuk organisasi. Penulisan acara mendukung tanggal eksplisit serta pengulangan harian, mingguan, atau bulanan dengan pengecualian; tingkat visibilitas yang dipublikasikan tetap bergantung pada pemeriksaan kesiapan hukum Scoutello. API tidak menyediakan tiket acara, peserta, media, template, newsletter, kolaborasi, atau kontrol manajemen acara lanjutan lainnya.

Menemukan tag​

Gunakan endpoint tag sebelum memberikan tagIds:

GET /tags?entity=events&type=category

entity wajib diisi dan menerima contacts, tasks, opportunities, atau events. Nilai tersebut dipetakan ke relevansi tag yang tersimpan. type bersifat opsional dan menerima category atau attribute. Kategori yang dapat dipilih dapat dimiliki organisasi atau bersifat global; atribut yang dapat dipilih berasal dari kumpulan atribut global terkurasi milik Scoutello. Hasil mencakup scoutelloId, nama yang dilokalkan ke bahasa organisasi, type, dan relevancy. ID tag lintas organisasi, dengan relevansi yang salah, atau yang tidak dapat dipilih akan menolak item batch yang terdampak.

Membaca riwayat email keluar​

Riwayat email bersifat hanya-baca:

GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}

Hanya email milik organisasi dengan status sent atau failed yang dikembalikan. Respons berisi header dan isi umum yang tersimpan, BCC, status dan stempel waktu, referensi proyek/acara/newsletter, ID dan tipe lampiran, serta statistik agregat pengiriman/pembukaan/klik/pentalan/keluhan/penolakan penerima. Email draf, email yang berada dalam antrean atau terjadwal, baris per penerima, snapshot hasil render, error mentah dari penyedia, dan URL unduhan lampiran tidak pernah ditampilkan. Pembaruan pengiriman kepada penerima pada waktu berikutnya akan memajukan stempel waktu sinkronisasi efektif email, sehingga email tersebut kembali muncul dalam pembacaan inkremental. Tidak ada rute untuk menulis email.

Hasil penerapan dapat berupa created, updated, linked, unchanged, stale_ignored, atau rejected. Validasi menggunakan would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale, atau rejected. Permintaan batch yang valid mengembalikan HTTP 200 meskipun ada rekaman individual yang ditolak, jadi selalu periksa setiap item dan ringkasan respons. Sertakan respons requestId saat meminta dukungan Scoutello menyelidiki kegagalan.

Stempel waktu dan konflik​

Jika externalUpdatedAt tersedia, Scoutello menggunakannya untuk menolak perubahan kedaluwarsa tanpa menggagalkan bagian batch lainnya. Hasil stale_ignored bersifat final untuk payload lama tersebut; ambil rekaman terbaru sebelum memutuskan apakah akan mengirim versi yang lebih baru.

Perlakukan stempel waktu sebagai nilai UTC ISO 8601. Pertahankan presisi aslinya dan jangan mengganti waktu tersebut dengan waktu saat tugas sinkronisasi berlangsung, karena yang digunakan adalah waktu modifikasi rekaman sumber.

Idempotensi​

Batas idempotensi adalah integrasi dan externalId. Scoutello membandingkan hash payload kanonis dan nilai externalUpdatedAt opsional, sehingga pengiriman ulang rekaman yang sama tidak membuat duplikat dan dapat mengembalikan unchanged.

Dengan externalUpdatedAt, stempel waktu dan payload yang sama akan unchanged, stempel waktu yang lebih lama akan stale_ignored, sedangkan stempel waktu yang sama dengan payload berbeda merupakan konflik versi. Untuk tautan yang belum pernah menerima stempel waktu, payload tanpa stempel waktu yang sama tetap unchanged, sedangkan payload yang berubah diterapkan sesuai urutan kedatangan. Setelah tautan menerima stempel waktu, payload yang berubah dan tidak menyertakan externalUpdatedAt ditolak sebagai konflik versi, sehingga data tanpa versi tidak dapat menimpa status berversi. Karena itu, stempel waktu modifikasi sumber sangat disarankan.

Jejak audit​

Akseptierte tindakan membuat, memperbarui, dan sinkronisasi yang hanya menautkan akan muncul di changelog Scoutello dengan Public API sebagai sumbernya dan dikaitkan dengan integrasi yang bertanggung jawab. Ringkasan proses operasional tetap menyimpan ID permintaan dan jumlah hasil agregat untuk pemecahan masalah; ringkasan tersebut tidak menyimpan payload rekaman atau rahasia API.

Error dan percobaan ulang​

Error tingkat permintaan menggunakan envelope berikut:

{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}

Lakukan percobaan ulang untuk respons HTTP 429 dan 5xx sementara dengan exponential backoff dan jitter. Patuhi Retry-After jika tersedia. Kegagalan jaringan mungkin terjadi setelah Scoutello menerima permintaan; mengirim ulang batch yang sama aman karena setiap rekaman bersifat idempoten berdasarkan ID eksternal dan payload kanonis. Jangan mencoba ulang secara otomatis untuk hasil autentikasi, otorisasi, validasi, konflik versi, atau rejected individual tanpa mengubah permintaan.

Loop sinkronisasi dua arah yang direkomendasikan​

  1. Panggil /whoami selama penyiapan dan verifikasi organisasi serta cakupan yang diharapkan.
  2. Baca setiap halaman yang berubah sejak high-water mark terakhir yang selesai, lalu terapkan perubahan tersebut ke sistem eksternal secara idempoten.
  3. Kirim perubahan eksternal ke /batch-upsert, menggunakan ID eksternal yang stabil dan stempel waktu modifikasi sumber.
  4. Simpan checkpoint hanya setelah semua halaman dan hasil item selesai ditangani.
  5. Selesaikan konflik sesuai aturan kepemilikan sistem sumber; jangan meniru penghapusan dengan mengirim rekaman kosong.

Scoutello sengaja tidak menyediakan rute penghapusan publik dalam versi pertama ini. Tangani kebijakan penghapusan atau pengarsipan di luar API hingga operasi siklus hidup terdokumentasi diperkenalkan.

Postingan sosial untuk peninjauan oleh manusia​

API sosial menyiapkan postingan untuk peninjau manusia yang ditentukan namanya. API ini tidak dapat menyetujui atau menerbitkannya. REST dan MCP menggunakan cakupan dan layanan yang sama.

CakupanEndpoint di bawah /api/v1
social-channels.readGET /social-channels
social-posts.readGET /social-posts, GET /social-posts/{scoutelloId}
social-post-drafts.readGET /social-post-drafts, GET /social-post-drafts/{scoutelloId}, GET /social-post-drafts/external/{externalId}
social-post-drafts.writePOST /social-post-drafts/batch-upsert, POST /social-media/uploads, POST /social-media/uploads/{assetId}/finalize

Cakupan baru harus diberikan secara eksplisit. Kredensial yang ada tidak memperoleh akses tambahan. Gunakan members.read untuk menemukan ID pengguna anggota, lalu pilih peninjau dengan izin memposting (newsletter.edit). Draf tidak memerlukan kontak CRM atau proyek.

{
"mode": "apply",
"records": [{
"externalId": "campaign:autumn:launch",
"expectedVersion": 0,
"approverScoutelloUserId": "REVIEWER_USER_ID",
"content": {
"title": "Autumn launch",
"publishMode": "schedule",
"scheduledAt": "2026-10-01T09:00:00+02:00",
"variants": [{
"channelId": "CHANNEL_SCOUTELLO_ID",
"content": "Explore the autumn collection.",
"settings": {},
"mediaIds": ["FINALIZED_ASSET_ID"]
}]
}
}]
}

publishMode: "now" 및 scheduledAt: null을(를) 사용해 승인된 콘텐츠를 게시합니다. 각 채널 변형에는 전체 텍스트, 설정 및 순서가 지정된 미디어 ID가 포함됩니다. 채널 검색을 통해 지원되는 형식, 제한 및 설정을 확인할 수 있습니다. 현재 지원되는 채널은 LinkedIn 프로필/페이지, Facebook, Instagram 및 Threads입니다. Instagram에는 미디어가 필요합니다. 하나의 변형에는 이미지 또는 동영상을 최대 10개까지 포함할 수 있습니다.

배치 요청은 기존 1MiB 요청 제한 내에서 서로 다른 외부 ID를 최대 100개까지 허용합니다. mode: "validate"은 초안을 저장하거나, 에셋을 업로드하거나, 알림을 생성하거나, 작업을 대기열에 추가하지 않고 참조와 버전을 확인합니다. 적용 결과에는 ID, 검토 링크, 버전 및 레코드별 처리 결과가 포함됩니다. 일부 작업이 실패해도 성공한 다른 항목은 롤백되지 않습니다. 알림 전송에 실패하면 저장된 검토 URL과 함께 경고가 반환됩니다.

대기 중인 초안을 수정하기 전에 최신 draftVersion을(를) 가져옵니다. 동일한 재시도는 멱등적으로 처리되며 이후에 사람이 수정한 내용이 유지됩니다. 검토자는 기존 항목에서 변경할 수 없습니다. 승인 또는 거부 후 다른 제안에는 새 외부 ID를 사용합니다. 초안 조회는 요청한 통합에 한정됩니다. 게시 이력에는 대시보드, 스크립트 및 기존 Scoutello 게시물을 비롯해 조직에서 저장된 모든 Scoutello 생성 캠페인이 포함됩니다. 외부 채널의 이력은 가져오지 않습니다.

목록에서는 표준 limit, cursor 및 updatedSince 매개변수를 사용합니다. 게시물과 초안에서는 channelId, status, after, before 및 search도 사용할 수 있습니다. 이후 커서 페이지에서도 모든 필터를 유지합니다. 날짜 필터는 게시 시간에 적용되며, 즉시 게시되는 대기 중인 초안에는 생성 시간이 적용됩니다. 초안 status 필터는 승인 상태를 기준으로 합니다. 게시물 status은 캠페인 또는 채널 전송 상태와 일치합니다. 조회 결과에는 마지막으로 확인된 전송 상태, 채널별 실패, 공개 링크 및 조정 타임스탬프가 표시됩니다. 초안 증분 조회에도 캠페인 전송 변경 사항이 반영됩니다.

미디어 업로드​

  1. Panggil POST /social-media/uploads dengan clientUploadId, filename, contentType, size dalam byte, serta sha256 heksadesimal huruf kecil dari byte asli. Jenis yang didukung adalah PNG, JPEG, WebP, MP4, WebM, QuickTime, dan M4V. Batas ukuran unggahan adalah 500 MiB.
  2. Kirim byte asli dengan HTTP PUT ke upload.url yang dikembalikan, menggunakan header-nya. URL unggahan kedaluwarsa setelah 15 menit. Gunakan kembali clientUploadId untuk mencoba ulang file yang sama; sesi yang kedaluwarsa atau file yang berbeda memerlukan ID baru.
  3. Panggil POST /social-media/uploads/{assetId}/finalize dengan isi JSON berupa {}. Finalisasi akan memeriksa ukuran, jenis, signature, dan checksum, membekukan salinan privat, serta mengembalikan ID aset untuk mediaIds. Finalisasi berulang aman dilakukan.

Kepemilikan unggahan terikat pada organisasi dan integrasi. Draf dapat merujuk aset yang telah difinalisasi dari organisasinya. URL pratinjau bersifat sementara; ambil kembali draf untuk memperbaruinya. URL unggahan tidak pernah diterbitkan untuk objek yang telah difinalisasi.

Peninjauan manual dan pengiriman​

Peninjau menerima notifikasi dasbor dan dapat membuka postingan dari Postings atau URL peninjauannya. Pengeditan akan membuat versi immutable lainnya. Persetujuan menggunakan versi dan hash konten yang ditampilkan, memeriksa ulang keanggotaan, channel, dan aset, lalu membuat satu kampanye permanen secara atomik. Jika waktu yang diusulkan telah berlalu, peninjau harus menyimpan waktu baru secara eksplisit atau memilih penerbitan saat disetujui.

Percobaan ulang antrean menggunakan kembali kampanye dan tanda terima platformnya. Kampanye yang telah disetujui tidak dapat diedit langsung. Pembatalan melalui dasbor mempertahankan riwayat persetujuan dan media; pembatalan tidak dapat menghentikan pengiriman yang sedang aktif. Lakukan polling pada draf atau kampanye untuk membedakan persetujuan dari pengiriman aktual ke platform.