REST API Segmen Pengguna

Buat segmen berbasis daftar yang diperbarui manual dan timpa, tambahkan, atau hapus anggota berdasarkan ID segmen.

Umum

• Permintaan dan respons menggunakan JSON yang dienkode UTF-8.
• URL endpoint lengkap adalah Base URL pusat data ditambah path API. Lihat Ikhtisar REST API untuk cara mendapatkan Base URL dan API Key / API Secret.
• Gunakan HTTP Basic Authentication: Authorization: Basic ${base64(api_key:api_secret)}. Sumber data API yang terikat ke API Key menentukan proyek; pemanggil tidak perlu meneruskan ID proyek di body permintaan.
• Respons sukses memiliki struktur umum: code 0 berarti sukses, message menjelaskan hasil, dan data membawa payload. Penanganan batch untuk penulisan anggota bergantung pada operasi: OVERRIDE dijalankan hanya setelah semua batch diterima; setiap batch APPEND dan REMOVE diterapkan secara independen. data.status dan data.complete dalam respons menunjukkan status pemrosesan.

Membuat segmen berbasis daftar

Membuat segmen dengan mode pembaruan manual dan unggah daftar sebagai metode pembuatan. Segmen tidak memiliki anggota setelah dibuat; gunakan Perbarui anggota segmen untuk mengunggah daftar.

Endpoint

POST /v1/segments

Contoh permintaan

              
              curl -X POST 'https://ma-api.engagelab.com/v1/segments' \
  -H 'Authorization: Basic {base64(api_key:api_secret)}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "High-value users",
    "description": "High-value user list synced from the order system"
  }'

            

Parameter permintaan

Contoh respons

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "segmentId": 123456789,
    "name": "High-value users",
    "generation": "generation-1"
  }
}

            

Perbarui anggota segmen

Satu endpoint menimpa, menambahkan, atau menghapus anggota daftar. Hanya segmen di proyek saat ini yang dibuat melalui unggah daftar, menggunakan pembaruan manual, dan aktif yang diterima. Pengenal pengguna harus cocok dengan pengguna aktif yang ada di proyek; API tidak membuat aset pengguna. Jika segmen tidak memenuhi syarat, error 55210–55214 dikembalikan (lihat Respons error).

Endpoint

POST /v1/segments/{segmentId}/members

Contoh permintaan

Contoh berikut membagi satu operasi OVERRIDE menjadi dua batch. Setiap batchId mewakili satu operasi daftar; semua batch harus menggunakan batchId, operation, dan batchCount yang sama. OVERRIDE menerapkan perubahan daftar hanya setelah semua batch diterima. APPEND dan REMOVE berlaku segera setelah setiap permintaan batch berhasil.

              
              curl -X POST 'https://ma-api.engagelab.com/v1/segments/123456789/members' \
  -H 'Authorization: Basic {base64(api_key:api_secret)}' \
  -H 'Content-Type: application/json' \
  -d '{
    "batchId": "crm-sync-20260915-001",
    "operation": "OVERRIDE",
    "batchIndex": 0,
    "batchCount": 2,
    "members": [
      {"euid": "100001"},
      {"identityName": "user_id", "identityValue": "user-002"}
    ]
  }'

            

Ketika batch OVERRIDE pertama diterima, status dalam respons adalah RECEIVING dan complete adalah false. Kirim batch sisanya dengan batchId yang sama dan set batchIndex ke 1.

Parameter permintaan

Elemen members mendukung dua format berikut; euid tidak boleh dikirim bersama identityName / identityValue:

Operasi daftar

Percobaan ulang dengan batchId yang sama harus menggunakan operasi, batchCount, dan konten batch yang sama; batchId dan batchIndex yang sama tidak boleh membawa konten berbeda. Hasil idempoten disimpan selama 24 jam.

Batch OVERRIDE ditahan hingga semua diterima, lalu diterapkan; data yang ditahan kedaluwarsa setelah TTL 24 jam, dan daftar tidak berubah jika batch belum lengkap sebelum kedaluwarsa. Setiap batch APPEND dan REMOVE diterapkan secara independen; batchCount dan batchIndex tetap mengidentifikasi batch, mendukung idempotensi, dan melacak progres tanpa memblokir batch saat ini.

Setiap perubahan daftar yang berhasil dicatat dalam riwayat pembaruan segmen dengan sumber REST API. OVERRIDE dicatat per batch selesai; APPEND dan REMOVE per batch berhasil. Catatan audit tidak menyertakan sampel pengenal yang tidak cocok atau tidak valid.

Contoh respons

Batch belum lengkap:

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "batchId": "crm-sync-20260915-001",
    "operation": "OVERRIDE",
    "status": "RECEIVING",
    "complete": false,
    "expectedBatchCount": 2,
    "receivedBatchCount": 1,
    "inputCount": 2,
    "matchedCount": 2,
    "unmatchedCount": 0,
    "unmatchedSamples": [],
    "unmatchedSamplesTruncated": false,
    "invalidCount": 0,
    "invalidSamples": [],
    "invalidSamplesTruncated": false,
    "enterCount": 0,
    "exitCount": 0
  }
}

            

Batch OVERRIDE selesai:

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "batchId": "crm-sync-20260915-001",
    "operation": "OVERRIDE",
    "status": "COMPLETED",
    "complete": true,
    "expectedBatchCount": 2,
    "receivedBatchCount": 2,
    "inputCount": 3,
    "matchedCount": 2,
    "unmatchedCount": 1,
    "unmatchedSamples": [
      {"identityName": "user_id", "identityValue": "user-not-found"}
    ],
    "unmatchedSamplesTruncated": false,
    "invalidCount": 1,
    "invalidSamples": [
      {"identityName": "not_configured", "identityValue": "example"}
    ],
    "invalidSamplesTruncated": false,
    "enterCount": 2,
    "exitCount": 1
  }
}

            

Ketika batch APPEND atau REMOVE berhasil, batch saat ini langsung diterapkan dan mengembalikan complete: true meskipun batchCount lebih besar dari jumlah batch yang diterima sejauh ini. Misalnya, dengan batchCount 2 dan hanya batch pertama diterima, receivedBatchCount adalah 1 dan status adalah COMPLETED.

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "batchId": "crm-sync-20260915-append",
    "operation": "APPEND",
    "status": "COMPLETED",
    "complete": true,
    "expectedBatchCount": 2,
    "receivedBatchCount": 1,
    "inputCount": 2,
    "matchedCount": 1,
    "unmatchedCount": 1,
    "unmatchedSamples": [
      {"identityName": "user_id", "identityValue": "user-not-found"}
    ],
    "unmatchedSamplesTruncated": false,
    "invalidCount": 0,
    "invalidSamples": [],
    "invalidSamplesTruncated": false,
    "enterCount": 1,
    "exitCount": 0
  }
}

            

Sampel mengikuti struktur objek pengenal anggota dari permintaan dan dapat menyertakan identityValue yang dikirim. Server menyimpan sampel hanya di cache idempotensi 24 jam, bukan di catatan audit; tangani respons dan log sesuai persyaratan kepatuhan data Anda.

Jika respons adalah PROCESSING, coba lagi dengan batchId, batchIndex, dan konten batch asli yang sama untuk hasil idempoten. Tidak ada API kueri progres batch terpisah.

Respons error

Error menggunakan code dan message; lihat Kode Status HTTP untuk kode status HTTP dan kode return umum.

Saat membuat segmen, kode error bisnis dan message dari Metadata diteruskan ke pemanggil, mis. nama duplikat 40026, batas 40032. Pada path unggah daftar, «segmen tidak ada» mengembalikan 55201 alih-alih 40027.

Pengenal anggota yang tidak cocok atau tidak valid tidak gagalkan seluruh operasi daftar (kecuali OVERRIDE ketika tidak ada pengguna yang cocok; lihat 55214). Respons mengembalikan jumlah dan hingga 100 sampel pengenal. Sampel dapat menyertakan identityValue; lindungi data respons sesuai kebutuhan.