Audiencias

Las audiencias usan el recurso /segments. Leer lista o detalle requiere segments:read; sus mutaciones requieren segments:write e Idempotency-Key.

Elige un tipo

POST /segments crea una audiencia por asignación explícita:

{"name": "Clientes de tienda", "type": "assignment"}

O por condiciones del perfil:

{
  "name": "Contactos en español",
  "type": "conditions",
  "definition": {
    "schemaVersion": 1,
    "rule": {
      "kind": "field",
      "field": {"scope": "custom", "id": "locale", "type": "text"},
      "operator": "eq",
      "value": "es-CR"
    }
  }
}

El tipo permanece fijo. POST /segments/{id}/save guarda la configuración con If-Match; la revisión autoritativa es ruleRevision.

Asigna o define reglas

Para assignment, usa PUT /segments/{id}/contacts/{contactId} y DELETE en la misma ruta con cuerpo vacío o {}. También existe POST /segments/{id}/assign con {contactId}. Repetir un alta no crea otra transición.

Para conditions, combina reglas con {kind: "group", operator: "and" | "or", children: [...]}. Cada campo admite operadores de su tipo. Los campos custom usan {scope: "custom", id, type}; una condición de pertenencia usa kind: "segment", segmentId y member_of o not_member_of, y solo referencia audiencias por asignación.

Un valor ausente solo coincide con is_not_set; no equivale a false, cero ni array vacío. Modificar el perfil o las asignaciones reconcilia la pertenencia calculada; no escribas miembros de una audiencia por condiciones manualmente.

Evalúa antes de una difusión

POST /segments/{id}/evaluate crea trabajo asíncrono y devuelve 202 con el recibo de generación. Una generación completa de la revisión actual puede publicarse como activeGenerationId. La API de claves no ofrece listado de miembros ni consulta de generaciones; revisa el resultado desde Marketing.

Una generación no garantiza un snapshot global de contactos mientras estos cambian. La difusión fija una generación completa, y cada envío vuelve a comprobar consentimiento y elegibilidad.

Archiva con revisión

archive, restore y DELETE /segments/{id} requieren revisión. Las dependencias pueden impedir archivo o borrado; restaurar comprueba capacidad. Los límites del plan pueden ser inferiores al techo operativo de 50 audiencias activas. Consulta audiencias en Marketing.