API de Grupos de Control

Un grupo de control es una parte de los usuarios de una aplicación que se mantiene al margen y que nunca recibe mensajes de marketing, de modo que el efecto de los mensajes se puede medir en comparación con él. Esta API gestiona los grupos de control y responde a la membresía por usuario. Úsela para replicar las acciones de Configuración > Grupos de control del Panel de Control desde sus propios sistemas, o para verificar si ciertos ID de usuario están excluidos antes de un envío o una importación.

URL Base

https://rpc-api.svc-nue.pushwoosh.com

Todos los endpoints se sirven a través de HTTPS. Las solicitudes y respuestas usan application/json a menos que se indique lo contrario.

Autenticación

Cada solicitud debe incluir un encabezado Authorization con su token de la API del servidor:

Authorization: Api SU_TOKEN_API

Convenciones

• Nomenclatura de campos: los cuerpos de las solicitudes y los parámetros de consulta/ruta aceptan lowerCamelCase (por ejemplo, controlGroupCode, userIds), y el servidor decodifica cualquiera de los dos casos. Las respuestas siempre se codifican usando los nombres de campo de proto, en snake_case (application_id, in_control_group, etc.). Los ejemplos de respuesta y la referencia del objeto de Grupo de control a continuación usan ese caso.
• code: cada respuesta de grupo de control lleva su propio código, generado en Create. Pase este código como controlGroupCode a Get, UpdatePercentage, UpdateCountries, Rename, Disable, Reshuffle, ForceUpdateCalculation, GetCalculationStatus, GetAnalytics y CheckControlGroupMembership.
• Varios grupos: una aplicación puede tener varios grupos de control. Cada grupo activado excluye usuarios de todos los envíos de marketing dentro de sus propios países y su tag, con independencia de los demás grupos, y los grupos pueden solaparse. Un envío no selecciona un grupo. El grupo con un name vacío es el grupo original de la aplicación y funciona de la misma manera.

Respuestas de error

Estado HTTP	Significado
400 Bad Request	Argumento no válido, como percentage fuera de 1–20, userIds vacío o con más de 1,000 entradas, un código de país no reconocido, scopeValues definido sin scopeTag, scopeTag que nombra un tag que la cuenta no tiene, o una entrada de scopeValues que UpdateSettings rechaza (véase más abajo). También devuelto (como un FailedPrecondition en la transmisión) por UpdatePercentage, UpdateCountries, UpdateSettings, Disable, Reshuffle y Delete en un grupo de control que pertenece a la exclusión propia de una campaña, según la precaución a continuación. Reshuffle por sí solo también se niega de esta manera en un grupo deshabilitado (percentage 0).
401 Unauthorized	Encabezado Authorization faltante o no válido.
403 Forbidden	La aplicación o el grupo de control no pertenecen a la cuenta del solicitante.
404 Not Found	No se encontró el grupo de control o la aplicación.
409 Conflict	Create usó un name que ya existe en la aplicación.
500 Internal Server Error	Falla inesperada del lado del servidor.

Endpoints

Método	Ruta	Descripción
GET	/api/applications/{code}/control_groups	Listar los grupos de control de una aplicación
POST	/api/applications/{code}/control_groups	Crear un grupo de control
GET	/api/applications/{code}/control_groups/{control_group_code}	Obtener un único grupo de control
POST	/api/applications/{code}/control_groups/{control_group_code}	Redimensionar un grupo de control
POST	/api/applications/{code}/control_groups/{control_group_code}/countries	Reajustar el alcance de un grupo de control a un conjunto de países
POST	/api/applications/{code}/control_groups/{control_group_code}/settings	Aplicar tamaño, alcance por país y tag, y modo de vida útil en una sola llamada
POST	/api/applications/{code}/control_groups/{control_group_code}/display_name	Renombrar un grupo de control
POST	/api/applications/{code}/control_groups/{control_group_code}/disable	Desactivar un grupo de control
POST	/api/applications/{code}/control_groups/{control_group_code}/reshuffle	Reorganizar un grupo de control
POST	/api/applications/{code}/control_groups/{control_group_code}/recalculate	Forzar el recálculo del tamaño de un grupo de control
GET	/api/applications/{code}/control_groups/{control_group_code}/calculation_status	Sondear un cálculo de tamaño en ejecución
GET	/api/applications/{code}/control_groups/{control_group_code}/analytics	Obtener analíticas de Control vs. Tratamiento
GET	/api/applications/{code}/control_groups/{control_group_code}/cycles	Listar los ciclos cerrados del grupo
POST	/api/applications/{code}/control_groups/{control_group_code}/membership	Verificar la membresía para un lote de ID de usuario
DELETE	/api/applications/{code}/control_groups/{control_group_code}	Eliminar un grupo de control

Listar

Lista todos los grupos de control configurados para una aplicación, primero el original sin nombre.

GET /api/applications/{code}/control_groups

Parámetros de ruta

Parámetro	Tipo	Descripción
code	string	El código de la aplicación para la cual listar los grupos de control.

Respuesta

Campo	Tipo	Descripción
control_groups	array de objetos de Grupo de control	Cada grupo de control configurado para la aplicación.

Crear

Crea un grupo de control con nombre para una aplicación y lo devuelve con su código generado. El nuevo grupo excluye usuarios de todos los envíos de marketing dentro de sus propios países y su tag, junto con los demás grupos activados de la aplicación.

POST /api/applications/{code}/control_groups

Cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
code	string	Sí	El código de la aplicación en la que se creará el grupo.
name	string	Sí	Nombre del grupo, hasta 64 caracteres y sin dos puntos. Debe ser único dentro de la aplicación. Forma parte de la clave de membresía, por lo que nunca cambia.
percentage	integer	Sí	Tamaño de la exclusión como porcentaje, 1–20.
segment	string	No	Expresión Seglang para medir el grupo. Omita para medir sobre toda la base.
countries	array de strings	No	Códigos de país ISO-3166-1 alfa-2 en minúsculas para limitar el alcance de la exclusión. Omita para todos los países. Los códigos no distinguen entre mayúsculas y minúsculas en la entrada.
scopeTag	string	No	Un tag de tipo string o boolean al que limitar la exclusión, combinado con countries mediante AND. Omita para no limitar por tag. Véase Alcance por tag más abajo.
scopeValues	array de strings	Véase la nota	Valores de scopeTag que incluyen a un usuario en el alcance. Obligatorio si scopeTag está definido, y debe estar vacío en caso contrario.
displayName	string	No	Nombre que muestra el Panel de Control, hasta 64 caracteres. Omita para mostrar name.

Ejemplo de solicitud

{
  "code": "XXXXX-XXXXX",
  "name": "Q3 holdout",
  "percentage": 10
}

Respuesta

Devuelve { "group": { ... } }, el nuevo objeto de Grupo de control.

Obtener

Devuelve un grupo de control por su código, con su tamaño de exclusión, generación y los recuentos de usuarios detrás de él.

GET /api/applications/{code}/control_groups/{control_group_code}

Parámetros de ruta

Parámetro	Tipo	Descripción
code	string	El código de la aplicación a la que pertenece el grupo.
control_group_code	string	El código del grupo de control.

Respuesta

Campo	Tipo	Descripción
group	objeto de Grupo de control	El grupo de control solicitado.
total_users	integer	Todos los usuarios en la aplicación.
control_group_users	integer	Usuarios actualmente excluidos.
calculation_status	string	TASK_STATUS_NOT_STARTED, TASK_STATUS_IN_PROGRESS o TASK_STATUS_COMPLETED.
has_data	boolean	Si los números de tamaño en caché ya están disponibles.

UpdatePercentage

Establece el porcentaje de exclusión (1–20) de un grupo de control. Al redimensionar se mantiene a cada miembro existente: la exclusión crece o se reduce a su alrededor en lugar de ser rediseñada. Reemplazado por UpdateSettings, que aplica tamaño, alcance y modo de vida útil en una sola llamada, pero sigue siendo compatible.

POST /api/applications/{code}/control_groups/{control_group_code}

Precaución

Una campaña puede crear su propia muestra de exclusión, que también es un grupo de control pero no aparece en Listar. Este endpoint, UpdateCountries, UpdateSettings, Disable, Reshuffle y Delete se niegan a tocar uno, devolviendo 400 Bad Request (“el grupo de control pertenece a una campaña y no se puede cambiar”) en su lugar.

Cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
percentage	integer	Sí	Nuevo tamaño de exclusión como porcentaje, 1–20.

Respuesta

Un objeto vacío en caso de éxito: {}.

UpdateCountries

Establece los países a los que se limita un grupo de control. Cambiar el alcance reinicia la medición del uplift, porque la población que se compara cambia. La exclusión en sí no se rediseña. Reemplazado por UpdateSettings, que también define un alcance por tag, pero sigue siendo compatible.

POST /api/applications/{code}/control_groups/{control_group_code}/countries

Cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
countries	array de strings	Sí	Códigos de país ISO-3166-1 alfa-2 en minúsculas. Una lista vacía amplía el grupo de nuevo a todos los países. Los códigos no distinguen entre mayúsculas y minúsculas en la entrada.

Ejemplo de solicitud

{
  "countries": ["us", "ca", "gb"]
}

Respuesta

Un objeto vacío en caso de éxito: {}.

UpdateSettings

Aplica el tamaño, el alcance por país y tag, y el modo de vida útil de un grupo de control en una sola llamada. Un cambio que altera a quién se excluye o durante cuánto tiempo (tamaño, alcance, modo, período de renovación o fecha de fin) cierra el ciclo en curso e inicia uno nuevo. Enviar los valores actuales no cambia nada. Rechaza un grupo de control que pertenece a la exclusión propia de una campaña, igual que UpdatePercentage.

POST /api/applications/{code}/control_groups/{control_group_code}/settings

Cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
percentage	integer	Sí	Tamaño de la exclusión como porcentaje, 1–20.
countries	array de strings	No	Códigos de país ISO-3166-1 alfa-2 en minúsculas. Una lista vacía amplía el grupo de nuevo a todos los países.
scopeTag	string	No	Un tag de tipo string o boolean al que limitar la exclusión, combinado con countries mediante AND. Vacío elimina el alcance por tag. Véase Alcance por tag más abajo.
scopeValues	array de strings	Véase la nota	Valores de scopeTag que incluyen a un usuario en el alcance. Obligatorio si scopeTag está definido, y debe estar vacío en caso contrario.
mode	string	No	Vida útil de la membresía: CONTROL_GROUP_MODE_PERMANENT (predeterminado), CONTROL_GROUP_MODE_AUTO_REFRESH o CONTROL_GROUP_MODE_EXPERIMENT.
refreshPeriodDays	integer	Véase la nota	Días entre redistribuciones, 7–365. Obligatorio con CONTROL_GROUP_MODE_AUTO_REFRESH, y debe omitirse en caso contrario.
endsAt	string (RFC 3339)	Véase la nota	Cuándo se desactiva un experimento, con al menos 30 días de antelación. Obligatorio con CONTROL_GROUP_MODE_EXPERIMENT, y debe omitirse en caso contrario.

Cada campo se aplica tal como se envía, igual que en UpdateCountries: un countries vacío amplía el grupo de nuevo a todos los países, y un scopeTag vacío elimina el alcance por tag.

Respuesta

Devuelve { "group": { ... } }, el objeto de Grupo de control actualizado.

Alcance por tag

Un grupo de control puede excluir solo a los usuarios cuyo valor de un tag de tipo string o boolean esté en un conjunto que usted elija, combinado con countries mediante AND si se definen ambos. Defínalo con Create o UpdateSettings.

• scopeTag nombra el tag; vacío significa que no hay alcance por tag. No puede ser Country: el alcance por país usa countries, no un tag.
• scopeValues enumera qué valores de scopeTag están en el alcance. Se requiere al menos uno cuando scopeTag está definido, y ninguno puede repetirse. Los valores de un tag de tipo string no pueden ser cadenas vacías. Cada valor de un tag de tipo boolean debe ser "true" o "false".
• Un dispositivo sin valor para scopeTag queda fuera del alcance, igual que un dispositivo sin el tag Country.
• La membresía en sí no cambia: la fórmula que asigna a los usuarios no se ve afectada por el alcance. El alcance por tag y por país son ambos una comprobación por dispositivo sobre ella, que acota cuáles de los dispositivos de un usuario seleccionado se excluyen realmente, no a quién selecciona la fórmula.
• Un tag a nivel de usuario se copia en cada uno de los dispositivos de ese usuario cuando se define, por lo que la comprobación a nivel de dispositivo anterior también cubre los tags a nivel de usuario, no solo los de dispositivo.
• Cambiar scopeTag, o cambiar scopeValues como conjunto (reordenar por sí solo no cuenta), cierra el ciclo en curso con CONTROL_GROUP_CYCLE_CLOSE_REASON_RESCOPED, igual que cambiar countries. Desactivar un grupo conserva su alcance por tag, igual que ya conserva countries.

Renombrar

Define el nombre que el Panel de Control muestra para un grupo de control. name forma parte de la clave de membresía y no cambia, por lo que el grupo conserva los mismos usuarios y su ciclo en curso.

POST /api/applications/{code}/control_groups/{control_group_code}/display_name

Cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
code	string	Sí	El código de la aplicación a la que pertenece el grupo.
controlGroupCode	string	Sí	El código del grupo de control.
displayName	string	No	Nuevo nombre, hasta 64 caracteres y único dentro de la aplicación. Envíe una cadena vacía para volver a mostrar name.

Respuesta

Devuelve { "group": { ... } }, el objeto de Grupo de control renombrado.

Desactivar

Desactiva un grupo de control, manteniéndolo a él y a su generación para que al volver a activarlo se restaure la misma exclusión en lugar de crear una nueva.

POST /api/applications/{code}/control_groups/{control_group_code}/disable

Respuesta

Un objeto vacío en caso de éxito: {}.

Reorganizar

Rediseña la exclusión de un grupo de control incrementando su generación. Esta es la única forma de obtener una muestra diferente: la membresía es determinista, por lo que desactivar y volver a activar reproduce exactamente la misma.

POST /api/applications/{code}/control_groups/{control_group_code}/reshuffle

Precaución

Rechaza un grupo desactivado (percentage 0) con 400 Bad Request (“el grupo de control no está activado”). Reorganizarlo solo movería una exclusión en la que no hay nadie, y consumiría silenciosamente una generación.

Respuesta

Campo	Tipo	Descripción
generation	integer	La generación del grupo después de la reorganización.

ForceUpdateCalculation

Inicia un nuevo recuento del tamaño de un grupo de control. Los números previamente almacenados en caché continúan sirviéndose hasta que finalice el nuevo recuento. Sondee GetCalculationStatus para ver el progreso.

POST /api/applications/{code}/control_groups/{control_group_code}/recalculate

Respuesta

Un objeto vacío en caso de éxito: {}.

GetCalculationStatus

Sondea solo los recuentos de usuarios cambiantes de un grupo de control mientras se ejecuta un cálculo de tamaño.

GET /api/applications/{code}/control_groups/{control_group_code}/calculation_status

Respuesta

Campo	Tipo	Descripción
total_users	integer	Todos los usuarios en la aplicación.
control_group_users	integer	Usuarios excluidos, contados sobre la aplicación.
calculation_status	string	TASK_STATUS_NOT_STARTED, TASK_STATUS_IN_PROGRESS o TASK_STATUS_COMPLETED.
has_data	boolean	Si los números de tamaño en caché están disponibles.

GetAnalytics

Devuelve las analíticas precalculadas de Control vs. Tratamiento para un grupo de control.

Nota

Un trabajo nocturno calcula las analíticas de cada grupo activado, con nombre o sin él. Un grupo medido sobre un segment todavía no tiene analíticas.

GET /api/applications/{code}/control_groups/{control_group_code}/analytics

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
windowDays	string	No	Preajuste de la ventana de retrospectiva: WINDOW_DAYS_3, WINDOW_DAYS_7 o WINDOW_DAYS_30.

Respuesta

Campo	Tipo	Descripción
events	array de objetos	Una entrada por evento rastreado, cada una con event, treatment y control (users, conversions, conversion_rate, events_per_user), uplift_pct, incremental_events, percent_of_treatment, z_score, p_value, confidence_pct y significance (SIGNIFICANCE_NOT_ENOUGH_DATA, SIGNIFICANCE_NOT_SIGNIFICANT o SIGNIFICANCE_SIGNIFICANT).

ListControlGroupCycles

Lista los ciclos cerrados de un grupo de control, del más reciente al más antiguo. Cada ciclo es la membresía con la que funcionó el grupo entre dos cambios de ajustes, junto con los ajustes a partir de los cuales se generó. El ciclo en curso (actual) no está en esta lista. Sus ajustes están en el propio objeto de Grupo de control.

GET /api/applications/{code}/control_groups/{control_group_code}/cycles

Respuesta

Campo	Tipo	Descripción
cycles	array de objetos de ciclo de grupo de control	Del más reciente al más antiguo.

Objeto de ciclo de grupo de control

Campo	Tipo	Descripción
cycle_number	integer	Secuencial dentro del grupo; el cycle_number del propio grupo es el siguiente al último cerrado aquí.
mode	string	Modo de vida útil con el que funcionó el grupo durante este ciclo: CONTROL_GROUP_MODE_PERMANENT, CONTROL_GROUP_MODE_AUTO_REFRESH o CONTROL_GROUP_MODE_EXPERIMENT.
generation	integer	La generación del grupo durante este ciclo.
percentage	integer	Tamaño de la exclusión durante este ciclo.
countries	array de strings	Alcance por país durante este ciclo; vacío es todos los países.
started_at / ended_at	string (RFC 3339)	Cuándo estuvo activo este ciclo.
close_reason	string	Por qué terminó el ciclo: CONTROL_GROUP_CYCLE_CLOSE_REASON_ROLLOVER, _EXPIRED, _RESHUFFLED, _RESIZED, _RESCOPED, _MODE_CHANGED o _DISABLED.
scope_tag	string	Tag al que se limitó la exclusión del ciclo, combinado con countries mediante AND. Vacío si no hay alcance por tag y en todos los ciclos cerrados antes de que existiera el alcance por tag, incluso si el grupo lo tuvo después.
scope_values	array de strings	Valores de scope_tag que incluyeron a un usuario en el alcance durante este ciclo; solo se define junto con scope_tag.

CheckControlGroupMembership

Informa para cada ID de usuario si está excluido por un grupo de control en este momento. La membresía se calcula solo a partir del ID. No se lee ningún registro de usuario, por lo que también se responde a un ID que la aplicación nunca ha visto, y un grupo desactivado responde false para cada ID en lugar de un error. Un grupo con alcance por país o por tag excluye a un usuario solo si alguno de sus dispositivos está en ese alcance, por lo que un ID no visto (sin ningún dispositivo) devuelve false ahí, aunque el mismo ID devolvería true en un grupo sin alcance. Use esto en lugar de exportar todo el grupo para verificar los usuarios de un envío o importación específicos.

POST /api/applications/{code}/control_groups/{control_group_code}/membership

Cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
userIds	array de strings	Sí	ID de usuario a verificar, como máximo 1,000 por llamada.

Ejemplo de solicitud

{
  "userIds": ["user-1", "user-2", "user-3"]
}

Respuesta

Campo	Tipo	Descripción
users	array de objetos	Una entrada por cada ID solicitado, en el orden en que se dieron (duplicados incluidos). Cada uno tiene user_id (string) y in_control_group (boolean).

Ejemplo de respuesta

{
  "users": [
    { "user_id": "user-1", "in_control_group": false },
    { "user_id": "user-2", "in_control_group": true },
    { "user_id": "user-3", "in_control_group": false }
  ]
}

Eliminar

Elimina un grupo de control por completo. Deja de excluir usuarios y ya no se pueden abrir sus estadísticas. Los demás grupos de la aplicación siguen funcionando.

DELETE /api/applications/{code}/control_groups/{control_group_code}

Precaución

Esto no se puede deshacer. Para dejar de excluir usuarios manteniendo el grupo, su generación y su historial, desactívelo en su lugar.

Respuesta

Un objeto vacío en caso de éxito: {}.

Objeto de grupo de control

Campo	Tipo	Descripción
code	string	Código del grupo de control (formato XXXXX-XXXXX), estable durante la vida del grupo.
name	string	Nombre del grupo, parte de la clave de membresía. Vacío es el grupo original, sin nombre, de la aplicación.
display_name	string	Nombre que muestra el Panel de Control. Vacío muestra name, y el grupo sin nombre se muestra como Global.
segment	string	Expresión Seglang sobre la que se mide el grupo; vacío es toda la base.
percentage	integer	Tamaño de la exclusión como porcentaje, 1–20. Cero significa que el grupo está desactivado.
enabled	boolean	Si el grupo está actualmente excluyendo usuarios.
generation	integer	Incrementado por cada reorganización; 0 significa que nunca se ha reorganizado.
last_modified_at	string (RFC 3339)	Cuándo se cambiaron por última vez los ajustes del grupo.
last_modified_by	string	Correo electrónico del usuario que cambió el grupo por última vez.
application_id	integer	ID numérico de la aplicación, la primera parte de la clave de membresía <application_id>:<generation>:<name>:<user_id> que CheckControlGroupMembership hashea para decidir si un usuario está excluido.
countries	array de strings	Códigos de país ISO-3166-1 alfa-2 en minúsculas a los que se limita la exclusión. Vacío es todos los países.
scope_tag	string	Tag al que se limita la exclusión, combinado con countries mediante AND; vacío es sin alcance por tag. Véase Alcance por tag.
scope_values	array de strings	Valores de scope_tag que incluyen a un usuario en el alcance; un tag de tipo boolean usa "true" y "false".

Relacionado

Grupos de control (guía de producto)

API de segmentación (filtros)