Enriquecer datos de contacto utilizando ZoomInfo en Jitterbit Studio

Introducción

ZoomInfo proporciona datos de contacto y empresa B2B a través de una API REST. Esta guía muestra cómo utilizar el conector HTTP v2 para autenticarse con ZoomInfo, construir un enrutador de recursos reutilizable que mapea tipos de puntos finales nombrados a rutas de API, y usar ese enrutador para buscar contactos, enriquecer registros de contacto existentes y recuperar datos de empresas.

El patrón clave en esta guía es un enrutador de recursos basado en Case: un único script mapea un nombre de recurso como contact o company a la ruta correspondiente de la API de ZoomInfo, y una operación central HTTP v2 POST maneja todas las llamadas a la API. Esto hace que la integración sea reutilizable: agregar un nuevo punto final de ZoomInfo requiere solo una adición de una línea al script del enrutador, sin necesidad de configuración adicional de conexión o actividad.

Esta guía asume una cuenta de ZoomInfo con credenciales de acceso a la API (nombre de usuario y contraseña).

Patrón de diseño

La autenticación se ejecuta una vez al inicio del flujo de trabajo para obtener un JWT. Todas las llamadas subsiguientes a ZoomInfo siguen la misma secuencia:

El enrutador y la actividad POST se comparten entre todas las llamadas a la API de ZoomInfo.

La tabla muestra el flujo conceptual. En la implementación, el enrutador de recursos y la actividad POST son pasos dentro de una operación compartida (la operación POST central en Parte 3), mientras que la construcción de la solicitud y el procesamiento de la respuesta son operaciones separadas y reutilizables que se crean por tipo de recurso y se invocan con RunOperation (ver Parte 4).

Parte 1: Configurar variables del proyecto y la conexión HTTP v2

Paso 1: Crear variables del proyecto

Almacene las credenciales y el JWT de tiempo de ejecución en variables del proyecto para que los valores sensibles no estén codificados de forma rígida en scripts o configuraciones de actividad.

Abra el menú de acciones del proyecto y seleccione Variables del Proyecto. Luego agregue:

Marque zoom.password y zoom.jwt como ocultos. Para obtener orientación sobre cómo almacenar credenciales de forma segura, consulte Gestionar credenciales de punto final.

Paso 2: Configurar la conexión HTTP v2

1. En Studio, abra su proyecto y haga clic en la pestaña Puntos finales y conectores del proyecto en la paleta de componentes de diseño.

2. Haga clic en el conector HTTP v2 para abrir la pantalla de configuración de la conexión.

3. Nombre de la conexión: Ingrese ZoomInfo API.

4. URL base: Ingrese https://api.zoominfo.com.

5. Autorización: Seleccione Bearer Token e ingrese [$zoom.jwt] como el valor del token. La variable del proyecto zoom.jwt está vacía cuando el proyecto se ejecuta por primera vez. La operación de autenticación en Parte 2 la poblará antes de que se realice cualquier otra llamada a ZoomInfo. El endpoint /authenticate en sí no valida el encabezado Authorization, por lo que un token vacío en la llamada inicial no causa un error.

6. Haz clic en Test para verificar la conexión, luego haz clic en Save Changes.

Parte 2: Autenticar y almacenar el JWT

ZoomInfo utiliza un modelo de autenticación basado en JWT. Antes de cualquier llamada a la API, una operación envía credenciales al endpoint /authenticate y almacena el JWT devuelto en zoom.jwt.

Paso 1: Crear la operación de autenticación

1. Crea una nueva operación y nómbrala core.ZoomInfo - Get Auth Token.

2. Agrega un paso de Transformación. En la transformación, define un esquema de destino JSON con dos campos: username y password. Mapea [$zoom.username] y [$zoom.password] a los respectivos campos.

3. Desde la conexión de ZoomInfo API, arrastra una actividad POST después de la transformación como destino.

4. Haz doble clic en la actividad POST para abrir su configuración.

5. Nombre: Ingresa ZoomInfo - Authenticate.

6. Ruta: Ingresa /authenticate.

7. En la pestaña Request, agrega un encabezado Content-Type con el valor application/json.

8. Haz clic en Finished.

Paso 2: Extraer y almacenar el JWT

Agrega un paso de Script después de la actividad POST. El script lee el JWT de $jitterbit.response, que contiene el cuerpo de respuesta en bruto de la actividad HTTP anterior, y lo almacena en la variable del proyecto:

$zoom.jwt = TrimChars(GetJSONString($jitterbit.response, "/jwt"), "\"");
If(length(trim($zoom.jwt)) == 0,
    RaiseError("ZoomInfo authentication failed. Response: " + $jitterbit.response)
);
WriteToOperationLog("ZoomInfo JWT obtained successfully.");

GetJSONString extrae un valor de campo mediante la ruta JSON. TrimChars elimina las comillas que GetJSONString incluye en los valores de cadena.

Paso 3: Llamar a la operación de autenticación al inicio de cada flujo de trabajo

En cualquier flujo de trabajo que utilice ZoomInfo, llama a la operación de autenticación como el primer paso:

$core.zoom.resource = "authenticate";
RunOperation("<TAG>operation:core.ZoomInfo - Get Auth Token</TAG>");

Si el mismo flujo de trabajo realiza múltiples llamadas a ZoomInfo, autentique una vez al inicio en lugar de antes de cada llamada individual.

Parte 3: Construir el enrutador de recursos

El enrutador de recursos asigna un tipo de recurso nombrado a la ruta correspondiente de la API de ZoomInfo. Una operación POST central reutiliza esta ruta para cada punto final.

Paso 1: Crear el script del enrutador

Cree un componente de Script llamado core. Load Zoom API Resource. Este script lee core.zoom.resource, establecido por el llamador, y escribe la ruta de la API en core.zoom.object:

$core.zoom.resource = ToLower($core.zoom.resource);
If(length($core.zoom.resource) == 0,
    RaiseError("$core.zoom.resource is empty. Set a resource type before running this script.")
);

Case(
    $core.zoom.resource == "contact",
        $core.zoom.object = "/search/contact";
    ,
    $core.zoom.resource == "enrich_contact",
        $core.zoom.object = "/enrich/contact";
    ,
    $core.zoom.resource == "company",
        $core.zoom.object = "/search/company";
    ,
    $core.zoom.resource == "scoop",
        $core.zoom.object = "/search/scoop";
    ,
    true,
        RaiseError("Unknown ZoomInfo resource: [" + $core.zoom.resource + "]")
);

WriteToOperationLog("ZoomInfo resource: " + $core.zoom.resource
    + " → path: " + $core.zoom.object);

La declaración Case enruta los cuatro tipos de recursos admitidos. Agregue una nueva rama para cualquier punto final adicional de ZoomInfo sin cambiar la operación POST o la conexión.

Paso 2: Crear la operación POST central

1. Cree una nueva operación y nómbrala core. ZoomInfo POST API CALL.

2. Agregue el script core. Load Zoom API Resource como el primer paso para que core.zoom.object se establezca antes de que se ejecute la actividad.

3. Desde la conexión ZoomInfo API, arrastre una actividad POST después del script.

4. Nombre: Ingrese ZoomInfo - POST.

5. Ruta: Ingrese [$core.zoom.object]. Studio resuelve la variable en tiempo de ejecución utilizando el valor establecido por el script del enrutador.

6. En la pestaña Request, agregue un encabezado Content-Type con el valor application/json.

7. Haga clic en Finished.

Los tipos de recursos admitidos y sus rutas correspondientes son:

Parte 4: Buscar contactos

Con la autenticación y el enrutador en su lugar, cada llamada a ZoomInfo sigue la misma secuencia: establecer core.zoom.resource, construir el cuerpo de la solicitud en una transformación y ejecutar la operación central POST.

Crear las operaciones de solicitud de construcción y procesamiento de respuesta

Las operaciones de solicitud de construcción y procesamiento de respuesta mencionadas en los pasos a continuación no son la operación central POST: se crea un par para cada tipo de recurso (contact, enrich_contact, company, scoop). Cada una es una operación pequeña y de un solo propósito construida en torno a una transformación:

• Operación de solicitud de construcción: Contiene una transformación que mapea las variables de entrada (por ejemplo, zoom.companyName o zoom.query_jobTitle) al cuerpo de la solicitud JSON que el endpoint de ZoomInfo espera. Ejecútala antes de la operación central POST para que el cuerpo de la solicitud esté preparado antes de que la actividad POST lo envíe.
• Operación de procesamiento de respuesta: Lee la respuesta de ZoomInfo y extrae los campos devueltos en variables o registros para su uso posterior. Analiza la respuesta ya sea con una transformación que mapea el esquema de respuesta a un objetivo, o con un paso de script que llama a GetJSONString en $jitterbit.response (el mismo enfoque utilizado para extraer el JWT en Parte 2).

Las tres operaciones se ejecutan en secuencia: construir solicitud, luego la operación central POST, luego procesar respuesta. Para el esquema de solicitud y respuesta de cada endpoint, consulta la documentación de la API de ZoomInfo.

Búsqueda de contactos por nombre de empresa

Para recuperar contactos asociados con una empresa, establece el tipo de recurso y el nombre de la empresa, construye el cuerpo de la solicitud y ejecuta la operación POST:

// Authenticate (skip if already done earlier in the workflow)
RunOperation("<TAG>operation:core.ZoomInfo - Get Auth Token</TAG>");

// Set the resource type and search parameters
$core.zoom.resource = "contact";
$zoom.companyName = $salesforce.accountName;

// Build and submit the search
RunOperation("<TAG>operation:Zoominfo - Build Request - Contact Info</TAG>");
RunOperation("<TAG>operation:core. ZoomInfo POST API CALL</TAG>");
RunOperation("<TAG>operation:Zoominfo - Process Request - Contact Info</TAG>");

La operación de solicitud de construcción (Zoominfo - Build Request - Contact Info) mapea zoom.companyName y cualquier filtro de título de trabajo opcional al formato de solicitud de la API de búsqueda de ZoomInfo. La operación de procesamiento de respuesta extrae los registros de contacto devueltos en variables para su uso posterior.

Para el esquema de solicitud y respuesta de la API de ZoomInfo Search, consulte la documentación de la API de ZoomInfo.

Filtrar contactos por título de trabajo

Para reducir los resultados a roles específicos, establezca zoom.query_jobTitle antes del paso de construcción de la solicitud:

$zoom.query_jobTitle = "Chief Executive Officer";
$core.zoom.resource = "contact";
RunOperation("<TAG>operation:Zoominfo - Build Request - Contact Info</TAG>");
RunOperation("<TAG>operation:core. ZoomInfo POST API CALL</TAG>");
RunOperation("<TAG>operation:Zoominfo - Process Request - Contact Info</TAG>");

Para buscar en múltiples títulos de trabajo, pase una lista separada por comas en zoom.query_jobTitle e itere sobre los valores en la operación de construcción de la solicitud, realizando una llamada de búsqueda por cada título y acumulando resultados.

Parte 5: Enriquecer datos de contacto

El enriquecimiento de contactos recupera datos detallados (direcciones de correo electrónico directas, números de teléfono y títulos de trabajo actuales) para contactos ya identificados a través de una búsqueda o provenientes de un registro existente de Salesforce. Utilice el enriquecimiento cuando una búsqueda básica de contactos devuelva información de contacto limitada.

Establezca core.zoom.resource en enrich_contact y ejecute la operación POST central:

$core.zoom.resource = "enrich_contact";
RunOperation("<TAG>operation:Zoominfo - Build Enrich Request</TAG>");
RunOperation("<TAG>operation:core. ZoomInfo POST API CALL</TAG>");
RunOperation("<TAG>operation:Zoominfo - Process Enrich Response</TAG>");

El cuerpo de la solicitud de enriquecimiento generalmente identifica el contacto por nombre y empresa, o por un ID de contacto de ZoomInfo devuelto de una búsqueda anterior. Después del enriquecimiento, utilice los datos devueltos para actualizar el registro de contacto correspondiente en Salesforce. Para fusionar campos enriquecidos en Salesforce, consulte Consultar registros de Salesforce usando SOQL.

Parte 6: Recuperar datos de la empresa y scoop

El mismo enrutador maneja las búsquedas a nivel de empresa. La búsqueda de empresas devuelve un ID de empresa de ZoomInfo que se puede utilizar en llamadas posteriores a /search/scoop para recuperar noticias recientes y datos de cambios en el liderazgo.

// Search for the company record
$zoom.companyName = $salesforce.accountName;
RunOperation("<TAG>operation:core.ZoomInfo Build Request - Get Company</TAG>");
$core.zoom.resource = "company";
RunOperation("<TAG>operation:core. ZoomInfo POST API CALL</TAG>");
RunOperation("<TAG>operation:core.ZoomInfo - Read Response - Get Company Id</TAG>");

// Retrieve scoop data using the company ID from the previous step
RunOperation("<TAG>operation:Build Request - Get Scoop for a Company</TAG>");
$core.zoom.resource = "scoop";
RunOperation("<TAG>operation:core. ZoomInfo POST API CALL</TAG>");
RunOperation("<TAG>operation:Read Response - Scoop for a Company</TAG>");

Los datos de scoop incluyen anuncios de cambios en el liderazgo, como nuevas contrataciones ejecutivas o cambios de rol. Esto es útil para flujos de trabajo de inteligencia de cuentas que alertan a los equipos de ventas o de cuentas cuando los contactos clave en una empresa cambian.

Verificar la integración

1. Ejecute core.ZoomInfo - Get Auth Token de forma aislada. Agregue una llamada a WriteToOperationLog después del script de extracción de JWT para confirmar que zoom.jwt no esté vacío. Verifique los registros de operaciones para la entrada del registro.

2. Realiza una búsqueda de contactos para un nombre de empresa que sepas que existe en ZoomInfo. Confirma en los registros que:

   • core.zoom.object está configurado como /search/contact por el script del enrutador.
   • La actividad POST devuelve un estado 200.
   • La operación de respuesta del proceso produce registros de contacto.

3. Si la llamada a /authenticate devuelve un estado no 200, confirma que las variables de proyecto zoom.username y zoom.password están configuradas correctamente. Las credenciales de ZoomInfo son sensibles a mayúsculas y minúsculas.

4. Si las llamadas API subsiguientes devuelven 401 No autorizado, la extracción de JWT puede haber fallado silenciosamente. Confirma que el guardia RaiseError en el script de autenticación está activo y que zoom.jwt no está vacío antes de que se ejecute la siguiente cadena de operaciones.

5. Si el enrutador genera un error de "Recurso desconocido de ZoomInfo", verifica que core.zoom.resource esté configurado como uno de los valores admitidos (contact, enrich_contact, company, scoop) y que no haya espacios en blanco al principio o al final del valor.