Enriquecer datos de contacto usando ZoomInfo en Jitterbit Studio

Introducción

ZoomInfo proporciona datos de contactos y empresas B2B a través de una API REST. Esta guía muestra cómo usar el conector HTTP v2 para autenticarse con ZoomInfo, construir un enrutador de recursos reutilizable que asigne tipos de puntos finales nombrados a rutas de API, y usar ese enrutador para buscar contactos, enriquecer registros de contactos 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 asigna un nombre de recurso como contact o company a la ruta de API de ZoomInfo correspondiente, y una operación central HTTP v2 POST maneja todas las llamadas de 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 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 sola vez al inicio del flujo de trabajo para obtener un JWT. Todas las llamadas posteriores a ZoomInfo siguen la misma secuencia:

El enrutador y la actividad POST se comparten en todas las llamadas de 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 solicitud y el procesamiento de respuesta son operaciones separadas y reutilizables que se crean por tipo de recurso e se invocan con RunOperation (ver Parte 4).

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

Paso 1: Crear variables de proyecto

Almacena credenciales y el JWT en tiempo de ejecución en variables de proyecto para que los valores sensibles no estén codificados en scripts o en la configuración de actividades.

Abre el menú de acciones del proyecto y selecciona Variables de Proyecto. Luego agrega:

Marca zoom.password y zoom.jwt como ocultos. Para obtener orientación sobre cómo almacenar credenciales de forma segura, consulta Gestionar credenciales de puntos finales.

Paso 2: Configurar la conexión HTTP v2

1. En Studio, abre tu proyecto y haz clic en la pestaña Puntos finales y conectores del proyecto en la paleta de componentes de diseño.

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

3. Nombre de conexión: Ingresa ZoomInfo API.

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

5. Autorización: Selecciona Bearer Token e ingresa [$zoom.jwt] como el valor del token. La variable de proyecto zoom.jwt está vacía cuando el proyecto se ejecuta por primera vez. La operación de autenticación en Parte 2 la completa antes de que se realice cualquier otra llamada de ZoomInfo. El punto final /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 y después 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 publica credenciales en el endpoint /authenticate y almacena el JWT devuelto en zoom.jwt.

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

1. Crea una operación nueva y asígnale el nombre core.ZoomInfo - Get Auth Token.

2. Añade un paso de Transformation. En la transformación, define un esquema de destino JSON con dos campos: username y password. Asigna [$zoom.username] y [$zoom.password] a los campos respectivos.

3. Desde la conexión 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. Name: Escribe ZoomInfo - Authenticate.

6. Path: Escribe /authenticate.

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

8. Haz clic en Finished.

Paso 2: Extraer y almacenar el JWT

Añade un paso de Script después de la actividad POST. El script lee el JWT de $jitterbit.response, que contiene el cuerpo de respuesta sin procesar 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 por ruta JSON. TrimChars elimina las comillas de cierre que GetJSONString incluye en 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 use ZoomInfo, llama a la operación de autenticación como primer paso:

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

Si el mismo flujo de trabajo ejecuta múltiples llamadas a ZoomInfo, autentica una sola 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 endpoint.

Paso 1: Crear el script del enrutador

Crea un componente de Script llamado core. Load Zoom API Resource. Este script lee core.zoom.resource, establecido por quien lo llama, 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 sentencia Case enruta los cuatro tipos de recursos compatibles. Añade una rama nueva para cualquier endpoint adicional de ZoomInfo sin cambiar la operación POST o la conexión.

Paso 2: Crear la operación POST central

1. Crea una operación nueva y asígnale el nombre core. ZoomInfo POST API CALL.

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

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

4. Name: Escribe ZoomInfo - POST.

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

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

7. Haz clic en Finished.

Los tipos de recursos compatibles y sus rutas correspondientes son:

Parte 4: Buscar contactos

Con autenticación y el router 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 POST central.

Crear las operaciones de solicitud de compilación y respuesta de proceso

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

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

Las tres operaciones se ejecutan en secuencia: solicitud de compilación, luego la operación POST central, luego respuesta de proceso. 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 a 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 compilación (Zoominfo - Build Request - Contact Info) asigna 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 respuesta de proceso extrae los registros de contacto devueltos en variables para su uso posterior.

Para el esquema de solicitud y respuesta de la API de Búsqueda de ZoomInfo, consulta la documentación de la API de ZoomInfo.

Filtrar contactos por título de trabajo

Para limitar los resultados a roles específicos, establece zoom.query_jobTitle antes del paso de solicitud de compilación:

$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 varios títulos de trabajo, pasa una lista separada por comas en zoom.query_jobTitle e itera sobre los valores en la operación de solicitud de compilación, realizando una llamada de búsqueda por título y acumulando resultados.

Parte 5: Enriquecer datos de contacto

El enriquecimiento de contactos recupera datos detallados (direcciones de correo directo, números de teléfono y títulos de trabajo actuales) para contactos ya identificados mediante una búsqueda u obtenidos de un registro de Salesforce existente. Utiliza enriquecimiento cuando una búsqueda de contacto básica devuelve información de contacto limitada.

Establece core.zoom.resource en enrich_contact y ejecuta 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 típicamente 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, utiliza los datos devueltos para actualizar el registro de contacto correspondiente de Salesforce. Para fusionar campos enriquecidos en Salesforce, consulta Consultar registros de Salesforce usando SOQL.

Parte 6: Recuperar datos de empresa y scoop

El mismo router maneja búsquedas a nivel de empresa. La búsqueda de empresa 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 de 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 cambian contactos clave en una empresa.

Verificar la integración

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

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

   • core.zoom.object se establece en /search/contact por el script del router.
   • La actividad POST devuelve un estado 200.
   • La operación de respuesta del proceso genera registros de contactos.

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

4. Si las llamadas posteriores a la API devuelven 401 No autorizado, es posible que la extracción de JWT haya fallado silenciosamente. Confirma que el guard 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 router genera un error de "Recurso ZoomInfo desconocido", verifica que core.zoom.resource esté configurado en uno de los valores admitidos (contact, enrich_contact, company, scoop) y que no haya espacios en blanco al principio ni al final del valor.