REST API de segmentos de usuarios

Cree segmentos basados en listas actualizados manualmente y sobrescriba, añada o elimine miembros por ID de segmento.

General

• Las solicitudes y respuestas usan JSON codificado en UTF-8.
• La URL completa del endpoint es la URL base del centro de datos más la ruta de la API. Consulte Descripción general de la REST API para obtener la URL base y la API Key / API Secret.
• Use autenticación HTTP Basic: Authorization: Basic ${base64(api_key:api_secret)}. La fuente de datos de API vinculada a la API Key determina el proyecto; quien llama no pasa un ID de proyecto en el cuerpo de la solicitud.
• Las respuestas correctas comparten una estructura común: code 0 significa éxito, message describe el resultado y data contiene la carga útil. El procesamiento por lotes de escrituras de miembros depende de la operación: OVERRIDE se ejecuta solo después de recibir todos los lotes; cada lote de APPEND y REMOVE se aplica de forma independiente. data.status y data.complete en la respuesta indican el estado del procesamiento.

Crear un segmento basado en listas

Crea un segmento con modo de actualización manual y carga de lista como método de creación. El segmento no tiene miembros tras la creación; use Actualizar miembros del segmento para cargar la lista.

Endpoint

POST /v1/segments

Ejemplo de solicitud

              
              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"
  }'

            

Parámetros de solicitud

Ejemplo de respuesta

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

            

Actualizar miembros del segmento

Un único endpoint sobrescribe, añade o elimina miembros de la lista. Solo se aceptan segmentos del proyecto actual creados mediante carga de lista, con actualización manual y activos. Los identificadores de usuario deben coincidir con usuarios activos existentes en el proyecto; la API no crea activos de usuario. Cuando el segmento no cumple los requisitos, se devuelven los errores 55210–55214 (consulte Respuestas de error).

Endpoint

POST /v1/segments/{segmentId}/members

Ejemplo de solicitud

El siguiente ejemplo divide una operación OVERRIDE en dos lotes. Cada batchId representa una operación de lista; todos los lotes deben usar el mismo batchId, operation y batchCount. OVERRIDE aplica el cambio de lista solo después de recibir todos los lotes. APPEND y REMOVE surten efecto en cuanto cada solicitud de lote tiene éxito.

              
              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"}
    ]
  }'

            

Cuando se recibe el primer lote OVERRIDE, status en la respuesta es RECEIVING y complete es false. Envíe el lote restante con el mismo batchId y establezca batchIndex en 1.

Parámetros de solicitud

Los elementos de members admiten los dos formatos siguientes; euid no puede enviarse junto con identityName / identityValue:

Operaciones de lista

Los reintentos con el mismo batchId deben usar la misma operación, batchCount y contenido del lote; el mismo batchId y batchIndex no pueden llevar contenido distinto. Los resultados idempotentes se conservan 24 horas.

Los lotes OVERRIDE se retienen hasta recibir todos y luego se aplican; los datos retenidos caducan tras un TTL de 24 horas, y la lista no cambia si los lotes están incompletos antes del vencimiento. Cada lote APPEND y REMOVE se aplica de forma independiente; batchCount y batchIndex siguen identificando lotes, admiten idempotencia y registran el progreso sin bloquear el lote actual.

Cada cambio de lista exitoso se registra en el historial de actualización del segmento con origen REST API. OVERRIDE se registra por lote completado; APPEND y REMOVE por lote exitoso. Los registros de auditoría no incluyen muestras de identificadores no coincidentes o no válidos.

Ejemplos de respuesta

Lote aún incompleto:

              
              {
  "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
  }
}

            

Lote OVERRIDE completado:

              
              {
  "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
  }
}

            

Cuando un lote APPEND o REMOVE tiene éxito, el lote actual se aplica de inmediato y devuelve complete: true aunque batchCount sea mayor que el número de lotes recibidos hasta el momento. Por ejemplo, con batchCount 2 y solo el primer lote recibido, receivedBatchCount es 1 y status es 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
  }
}

            

Las muestras siguen la estructura de objeto de identificador de miembro de la solicitud y pueden incluir el identityValue enviado. El servidor almacena muestras solo en la caché de idempotencia de 24 horas, no en registros de auditoría; gestione respuestas y registros según sus requisitos de cumplimiento de datos.

Si la respuesta es PROCESSING, reintente con el mismo batchId, batchIndex y contenido original del lote para un resultado idempotente. No hay una API de consulta de progreso de lote independiente.

Respuestas de error

Los errores usan code y message; consulte Códigos de estado HTTP para códigos de estado HTTP y códigos de retorno generales.

Al crear un segmento, los códigos de error de negocio y message de Metadata se pasan al llamador, p. ej. nombre duplicado 40026, límite 40032. En la ruta de carga de lista, «el segmento no existe» devuelve 55201 en lugar de 40027.

Los identificadores de miembros no coincidentes o no válidos no fallan toda la operación de lista (excepto OVERRIDE cuando no hay usuarios coincidentes; consulte 55214). La respuesta devuelve recuentos y hasta 100 muestras de identificadores. Las muestras pueden incluir identityValue; proteja los datos de respuesta en consecuencia.