Skip to main content
Build the future with Agentforce at TDX in San Francisco or on Salesforce+ on March 5–6. Register now.

Eliminar contactos con la API de REST

Objetivos de aprendizaje

Después de completar esta unidad, podrá:

  • Eliminar contactos por lotes usando la API de REST
  • Conocer el estado de las solicitudes de eliminación de contactos
  • Solucionar problemas de las solicitudes de eliminación de contactos

Eliminar contactos de forma más eficiente

Eliminar uno o dos contactos directamente en Marketing Cloud Engagement es muy sencillo, pero si va a eliminar algo más que un puñado de ellos, el proceso puede hacerse muy tedioso. Así que, aunque el límite por lote de solicitudes es de un millón de contactos, no esperamos que seleccione ese número de contactos manualmente. Por ello, si necesita eliminar un gran número de contactos (e hizo los deberes para asegurarse de que la eliminación de los contactos es la mejor opción), hay disponibles varios recursos de API de REST para hacerlo en Marketing Cloud Engagement.

Activar la eliminación de contactos

Recuerde, debe haber activado Eliminación de contacto para poder empezar. Consulte la unidad anterior si necesita recordar cómo hacerlo. Del mismo modo, puede modificar el periodo de supresión de su cuenta en el recurso configSettings, tal y como se muestra en este ejemplo.

Ejemplo: configurar el periodo de supresión de Eliminación de contacto

Este ejemplo define el valor como 0 días (mediante un valor de -1), es decir, en una eliminación inmediata.

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete/configSettings
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
   "items" : [{
      "settingKey" : "SuppressionRestoreUntilDays",
      "value" : "-1"
      }
   ]

Elegir cómo eliminar contactos con la API de REST

Ahora que su cuenta tiene activada la eliminación de contactos, puede usar uno de los tres valores distintos para elegir qué contactos se eliminan: Id. de contacto, claves de contacto o extensiones de datos. Vamos a examinar con más detenimiento cada uno de ellos, junto con código de muestra. 

Id. de contactos

Si selecciona eliminar los contactos por su valor de Id. de contacto, debería pasar los valores en una matriz, como se muestra en este ejemplo.

Ejemplo: eliminar contactos por Id. de contacto

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete?type=ids
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
   "values": [12345678, 12345679],
    "DeleteOperationType": "ContactAndAttributes"
}

Claves de contactos

Si selecciona eliminar los contactos utilizando el valor de ContactKey, debería pasar también estos valores en una matriz.

Ejemplo: eliminar contactos por clave de contacto

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete?type=keys
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
   "values": [
      "TEST_317-531-5555", "TEST_317-531-5556"
      ],
   "DeleteOperationType": "ContactAndAttributes"
}

Extensiones de datos

Puede optar por eliminar todos los contactos de una extensión de datos específica. Recuerde que esta operación elimina los registros de contacto descritos en la extensión de datos en todas las extensiones de datos que pueden enviarse. Eso incluye las extensiones de datos que se envían en función de sus valores ContactKey, ContactID y Dirección de email. También puede decidir si eliminar o no toda la extensión de datos cuando termine. ¡Hay tantas opciones! 

Este proceso crea una solicitud asíncrona para su lote de solicitudes de eliminación. Puede ponerse en contacto con el gerente de cuenta de Marketing Cloud Engagement si desea más información sobre cómo configurar los límites de solicitudes de eliminación en su cuenta.

Nota

Debe especificar que está eliminando una extensión de datos e incluir la clave externa de esa extensión de datos. Además, no es posible eliminar extensiones de datos sincronizadas. Puede usarlas para ayudar a identificar los contactos que se van a eliminar, aunque la extensión de datos en sí permanecerá.

Ejemplo: eliminar contactos mediante una extensión de datos

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete?type=listReference
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
   "deleteOperationType": "ContactAndAttributes",
   "targetList": {
      "listType": {
         "listTypeID": 3
      },
   "listKey": "ContactListDeleteSource_as_DataExtension"
   },
   "deleteListWhenCompleted": false,
   "deleteListContentsWhenCompleted": false
}

Comprobar sus solicitudes

Como mencionamos, las solicitudes de eliminación de contactos tardan tiempo en completarse. De hecho, pueden tardar varias horas, en función de cuántos contactos incluyó en su solicitud, cuántas solicitudes creó y otros factores del sistema. Sin embargo, puede monitorear el progreso de sus solicitudes mediante el valor OperationID. Cada solicitud de eliminación de contactos devuelve un valor OperationID que puede usar para recuperar cualquier información disponible. A continuación, se incluyen algunas solicitudes como ejemplo.

Ejemplo: obtener el estado de una solicitud de eliminación de contactos específica

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
GET /contacts/v1/contacts/actions/delete/status?operationID=IDVALUEHERE
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Este ejemplo de respuesta muestra la información de un contacto eliminado.

{
   "operation": {
      "listTypeID": 3,
      "listIdentifier": "037c2811-ce62-4381-b3d2-1936e51fbf4d",
      "listKey": "037c2811-ce62-4381-b3d2-1936e51fbf4d",
      "expectedListCount": 1,
      "deleteType": "ContactAndAttributes",
      "deleteListOnCompleted": false,
      "operationID": 2,
      "eID": 12345,
      "mID": 12345,
      "employeeID": 30980,
      "operationRequestID": "21d0d10d-a15a-413c-bc3e-8b43b185e551",
      "status": "Completed",
      "scheduledTime": "2016-06-14T16:01:58.107",
      "retryCount": 0,
      "createdDate": "2016-06-14T16:02:00",
      "createdBy": 30980,
      "modifiedDate": "2016-06-14T16:02:00",
      "modifiedBy": 30980
    },
    "requestServiceMessageID": "93631be1-107f-4239-a8b7-cdae245d7403",
    "resultMessages": [],
    "serviceMessageID": "00e6add8-d79a-4bd6-9568-2f2a272538f0"
}

Ejemplo: recuperar solicitudes de eliminación de contactos por fecha

También puede recuperar un resumen de las solicitudes creadas durante un intervalo de fechas específico. 

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
GET contacts/v1/contacts/analytics/deleterequests?startdateutc=2019-02-18T00%3A00%3A00&enddateutc=2019-03-19T00%3A00%3A00&%24page=1&%24pagesize=20&%24orderby=operationId%20desc&statusid=5
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{

La respuesta incluye los valores OperationID y un breve resumen de todas las solicitudes que corresponden. Si desea información más específica, use el valor OperationID con el recurso /contacts/v1/contacts/actions/delete/status?operationID=.

"startDateUtc":"2019-02-18T00:00:00",
"endDateUtc":"2019-03-19T00:00:00",
"statusAsOfDateUtc":"2019-03-19T19:33:17.496471Z",
"pageNumber":1,
"pageSize":20,
"operations":[
   {
      "operationId":22944,
      "totalContactCount":1,
      "completedContactCount":1,
      "receivedDateUtc":"2019-03-04T22:42:00",
      "status":"Completed",
      "lastStatusDateUtc":"2019-03-19T04:47:40.293",
      "deleteMethod":"Contact Key/ID"
   },
   {
      "operationId":22943,
      "totalContactCount":1,
      "completedContactCount":1,
      "receivedDateUtc":"2019-03-04T22:41:00",
      "status":"Completed",
      "lastStatusDateUtc":"2019-03-19T04:47:40.293",
      "deleteMethod":"Contact Key/ID"
   },
   {
      "operationId":22625,
      "totalContactCount":1,
      "completedContactCount":1,
      "receivedDateUtc":"2019-02-26T23:26:00",
      "status":"Completed",
      "lastStatusDateUtc":"2019-03-13T10:10:17.9",
      "deleteMethod":"Contact Key/ID"
   }
   ],
   "requestServiceMessageID":"e1198208-6432-40fd-b5ae-172c9d9bc44a",
   "responseDateTime":"2019-03-19T13:33:18.2141124-06:00",
   "resultMessages":[],
   "serviceMessageID":"ef7d833c-509f-4dbc-8f99-060aac3c0382"
}

Ejemplo: recuperar un resumen de solicitudes de eliminación de contactos

Este ejemplo muestra un resumen de los reportes de estado de todas las solicitudes durante el periodo de tiempo especificado.

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
GET contacts/v1/contacts/analytics/deleterequests/summary?startdateutc=2018-01-15T00:00:00Z&enddateutc=2018-01-15T05:00:00Z
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

El ejemplo de respuesta desglosa las solicitudes en completadas, en procesamiento y no válidas.

{
   "startdateutc":"2018-01-15T00:00:00Z",
   "enddateutc":"2018-01-15T04:30:00Z",
   "statusofdateutc": "2018-01-17T04:30:00Z",
   "interval":"0",
   "itemcount":5,
   "totaltimeseries":[
      {
         "requestcount":500,
         "minvalue":100,
         "maxvalue":100,
         "items":[
            {time:"01-15-2018 00:00:00","value":100},
            {time:"01-15-2018 01:00:00","value":100},
            {time:"01-15-2018 02:00:00","value":100},
            {time:"01-15-2018 03:0000:","value":100},
            {time:"01-15-2018 04:00:00","value":100}
         ]
      }],
      "statustimeseries":[
         {
            "statusid": 5,
            "status": "Completed",
            "requestcount":350,
            "minvalue":0,
            "maxvalue":100,
            "items":[
               {time:"01-15-2018 00:00:00","value":100},
               {time:"01-15-2018 01:00:00","value":100},
               {time:"01-15-2018 02:00:00","value":100},
               {time:"01-15-2018 03:00:00","value":50},
               {time:"01-15-2018 04:00:00","value":0}
            ]
         },
         {
            "statusid": 1,
            "status": “Processing”,
            "requestcount":100,
            "minvalue":0,
            "maxvalue":75,
            "items":[
               {time:"01-15-2018 00:00:00","value":0},
               {time:"01-15-2018 01:00:00","value":0},
               {time:"01-15-2018 02:00:00","value":0},
               {time:"01-15-2018 03:00:00","value":25},
               {time:"01-15-2018 04:00:00","value":75}
            ]
         },
         {
            "statusid": 7,
            "Status": "Invalid",
            "requestcount":50,
            "minvalue":0,
            "maxvalue":50,
            "items":[
               {time:"01-15-2018 00:00:00","value":0},
               {time:"01-15-2018 01:00:00","value":0},
               {time:"01-15-2018 02:00:00","value":0},
               {time:"01-15-2018 03:00:00","value":25},
               {time:"01-15-2018 04:00:00","value":25}
            ]
         }]
}

Puede usar los valores OperationID para realizar un seguimiento de las solicitudes en procesamiento o no válidas.

Es un montón de código, ¿verdad? Tomemos un descanso de tanto código y vayamos a la unidad final para aprender las mejores prácticas para evitar riesgos al eliminar contactos.

Recursos

Comparta sus comentarios de Trailhead en la Ayuda de Salesforce.

Nos encantaría saber más sobre su experiencia con Trailhead. Ahora puede acceder al nuevo formulario de comentarios en cualquier momento en el sitio de Ayuda de Salesforce.

Más información Continuar a Compartir comentarios