Aplica y consulta restricciones
Aplica y consulta restricciones
Cuando una persona pide no ser contactada, agrégala a la lista de exclusión que corresponda. Cuando cambia de opinión, sácala. Cada cambio queda como una versión nueva de su agreement, con su propia evidencia: así respondes desde cuándo estaba en la lista y por qué volvió a ser contactable.
Antes de empezar, crea la lista con una plantilla de restricción.
Crea la entidad antes de aplicar
Las restricciones se aplican sobre una entidad de tu empresa, identificada por su entity_id o por su user_reference. Soyio no crea la entidad al aplicar una restricción: si no existe, la respuesta es 404. Créala antes con POST /api/v1/entities, usando como user_reference un identificador propio de tu sistema y no datos personales como el RUT, el correo o el teléfono.
Si la misma persona existe en tu empresa con dos identificadores distintos, por ejemplo el id de cliente de tu CRM y el de tu call center, la restricción aplica solo al que usaste. Las dos quedan unidas cuando fusionas los sujetos: la fusión conserva las restricciones de ambos.
Agrega una persona a la lista
Envía la lista y la entidad a POST /api/v1/restriction_actions:
{
"user_reference": "cliente-1234",
"restriction_template_id": "restpl_wAspvmEr4ACDZaPUtfwjsA",
"reason_code": "sernac",
"channel": "phone_call",
"origin_event": {
"system": "call_center",
"event_id": "CL-9931"
}
}
La persona queda restringida por todo lo que declara la versión vigente de la plantilla: cada categoría de datos, con cada uso y en cada alcance. No envíes data_restrictions al aplicar.
Si la solicitud llegó antes de que la registraras, indica la fecha real en effective_at. Si la plantilla tiene duración, la restricción vence al cumplirse ese plazo desde effective_at, y puedes indicar otro vencimiento con expires_at. Si la plantilla no tiene duración y no envías expires_at, la restricción no vence.
Reintentos seguros
origin_event identifica la solicitud en tu sistema. Si envías de nuevo el mismo system y event_id, Soyio responde 200 con la acción original y no crea otra, así que reintentar no duplica nada. La primera vez la respuesta es 201.
Saca a una persona de la lista
Envía la misma solicitud con kind: "lift". Sin data_restrictions, la persona sale de la lista completa:
{
"user_reference": "cliente-1234",
"restriction_template_id": "restpl_wAspvmEr4ACDZaPUtfwjsA",
"kind": "lift",
"origin_event": {
"system": "call_center",
"event_id": "CL-10020"
}
}
Para levantar solo una parte, envía en data_restrictions las restricciones que quieres levantar. Por ejemplo, si la lista bloquea llamadas y SMS por separado y la persona vuelve a aceptar SMS:
{
"user_reference": "cliente-1234",
"restriction_template_id": "restpl_wAspvmEr4ACDZaPUtfwjsA",
"kind": "lift",
"origin_event": {
"system": "call_center",
"event_id": "CL-10021"
},
"data_restrictions": [
{
"data_category": "user.contact.phone_number",
"data_use": "marketing.communications.sms"
}
]
}
Cada restricción tiene que coincidir exactamente con una que la persona tenga activa en esa lista, incluido su alcance. Si no envías data_subject, Soyio usa el de la plantilla. Si no coincide, la respuesta es 422 y te indica cuáles puedes levantar.
Tampoco se levanta una parte de una restricción más amplia: si la lista bloquea marketing.communications completo, levantar solo .sms falla. Si necesitas levantar por medio, declara cada medio por separado en la plantilla.
Levantar no borra la restricción. Queda registrada con la fecha en que se levantó y la acción que la levantó.
Un levantamiento rige desde que lo registras: no se puede programar. Un effective_at futuro responde 422.
Si la versión vigente de la plantilla tiene liftable: false, levantar falla con 422. El valor que cuenta es el actual de la plantilla, no el que tenía cuando se aplicó la restricción.
Listas deshabilitadas
Una lista deshabilitada no acepta personas nuevas: aplicar responde 422. Deshabilitarla no cambia las restricciones que ya estaban aplicadas, y levantar sigue funcionando, para que nadie quede atrapado en una lista cerrada.
Consulta si una persona está restringida
Consulta el estado con GET /api/v1/entities/{id}/agreement/restriction_status, o por referencia con GET /api/v1/entities/reference/{user_reference}/agreement/restriction_status. Indica qué quieres hacer con data_category, data_use o ambos:
const params = new URLSearchParams({
data_category: 'user.contact.phone_number',
data_use: 'marketing.communications.sms',
data_subject: 'customer',
});
const response = await fetch(
`https://app.soyio.id/api/v1/entities/reference/cliente-1234/agreement/restriction_status?${params}`,
{ headers: { Authorization: `Bearer ${process.env.SOYIO_API_KEY}` } }
);
{
"restriction_status": {
"data_category": "user.contact.phone_number",
"data_use": "marketing.communications.sms",
"data_subject": "customer",
"status": "restricted",
"conflicting_permission": false,
"precedence": null,
"restricted_by": [
{
"data_category": "user.contact.phone_number",
"data_use": "marketing.communications.sms",
"data_subject": "customer",
"effective_at": "2026-09-29T12:58:00.000Z",
"expires_at": null,
"restriction_template_id": "restpl_wAspvmEr4ACDZaPUtfwjsA",
"restriction_action_id": "restact_1B2M2Y8AsgTpgAmY7PhCfg",
"reason_code": "sernac"
}
]
}
}
status puede ser:
restricted: todo lo consultado está restringido.partially_restricted: solo una parte está restringida. Pasa, por ejemplo, si consultasmarketing.communicationsy la persona solo tiene restringido.sms.unrestricted: nada de lo consultado está restringido.
Envía siempre data_subject. Cada lista aplica a un tipo de titular, como customer, y si no lo indicas Soyio no sabe si la persona es de ese tipo: el resultado es partially_restricted.
Para consultar dentro de un producto o filial, agrega scope_type y scope_id. Una restricción de una filial alcanza a todos sus productos.
Restricción y consentimiento a la vez
Una persona puede estar en una lista y, después, consentir lo mismo desde tu sitio. Por defecto gana la última acción de la persona: si consintió después de entrar a la lista, el estado es unrestricted y precedence es last_action. La restricción no se borra.
Volver a aceptar un consentimiento que la persona ya tenía también cuenta como consentir después: Soyio guarda la fecha del último otorgamiento.
Si prefieres que la restricción gane siempre, activa restrictions_always_prevail en la configuración de listas de exclusión. El cambio vale para todas las consultas desde ese momento, incluso sobre restricciones aplicadas antes.
Revisa todas las restricciones de una persona
Para ver cada restricción con su estado, usa GET /api/v1/entities/{id}/agreement/restrictions, o por referencia con GET /api/v1/entities/reference/{user_reference}/agreement/restrictions. Cada restricción trae su state:
active: está vigente.superseded: sigue registrada, pero un consentimiento posterior le gana.scheduled: todavía no entra en vigencia.lifted: alguien la levantó.expired: se aplicó con fecha de vencimiento y ya venció.
Así distingues a quien sacaron de la lista de quien consintió después.
Historial de acciones
Cada vez que agregas o sacas a alguien queda una acción de restricción. Consulta las acciones con GET /api/v1/restriction_actions y filtra con where por restriction_template_id, subject_id, kind o status.
Mantén tus canales al día
Soyio registra la restricción, pero quien deja de contactar a la persona es tu canal: tu call center, tu herramienta de email o tu CRM. Suscríbete a estos webhooks para que se enteren apenas cambie algo:
restriction_action.applied: una persona quedó en una lista.restriction_action.lifted: una persona salió de una lista.restriction_action.superseded: un consentimiento posterior de la persona le ganó a la restricción. Llega unos segundos después del consentimiento y no se envía si tu empresa activórestrictions_always_prevail. Si después la persona revoca ese consentimiento, la restricción vuelve a tener efecto sin un evento propio: la revocación llega comoagreement.updated.
Cada evento trae la acción y, en data_restrictions, las filas que cambiaron con su taxonomía y su alcance, así que tu canal puede actuar sin volver a consultar. Volver a agregar a alguien que ya estaba en la lista también envía restriction_action.applied, porque actualiza la fecha de la restricción. Un levantamiento que no cambió nada, porque la restricción ya estaba levantada, no envía evento.
Además, cada vez que una restricción cambia, el acuerdo de la persona tiene una versión nueva y se envía agreement.updated. Ese evento trae las restricciones del acuerdo en data_restrictions, y en changes.data_restrictions las que se aplicaron (applied) o se levantaron (lifted) en esa versión.
Para cargar o reconciliar tu base completa, exporta las acciones con resource: "restriction_actions", o los acuerdos con resource: "agreements", que incluyen sus restricciones.
Permisos
Tu API key necesita alguno de estos permisos:
- Para aplicar y levantar:
restriction_actions.api.writeorestriction_actions.api.manage - Para consultar el estado, las restricciones y las acciones:
restriction_actions.api.readorestriction_actions.api.manage - Para exportar las acciones:
exports.api.write, además de un permiso de consulta
Los permisos generales del módulo (restrictions.api.read, restrictions.api.write y restrictions.api.manage) también dan acceso a estos endpoints.
Próximos pasos
- Datos de contexto en restricciones: qué poner en
origin_event,originymetadata - Referencia de la API: revisa el detalle de cada endpoint