Gestionar Listings a través de la API
Requisito previo: Para seguir los pasos de esta guía, debes usar una cuenta de producción con una suscripción activa a Listings. De lo contrario, muchas de las solicitudes devolverán respuestas vacías.
Una vez que hayas creado y actualizado correctamente las entidades, puedes usar la API de Listings para gestionar dónde se publican esas entidades en toda la Red de medios digitales de Yext. Cada medio digital es único, pero algunas características comunes que admite incluyen:
- Actualizaciones en tiempo real en respuesta a cambios en Knowledge Graph
- Visualización de logotipos, fotos, menús, horarios festivos y otro contenido enriquecido de entidades
- Eliminación de duplicados
Paso 1: Recuperar una lista de medios digitales disponibles
Antes de conocer los detalles específicos de tus listings, puede ser útil ver a qué medios digitales tienes acceso. Puedes encontrar los tipos de entidad y los países que admite cada medio digital en tu cuenta mediante el endpoint Publishers: List.
| URL | https://api.yextapis.com/v2/accounts/{accountId}/listings/publishers |
| Permisos | Listings: READ |
| Descripción | Recupera una lista de medios digitales disponibles para una cuenta |
Solicitud de ejemplo:
| OBTENER | https://api.yextapis.com/v2/accounts/{accountId}/listings/publishers?api_key={API_KEY}&v=20210504&entityType=[LOCATION,RESTAURANT] |
Objeto de medio digital de ejemplo:
{
"id": "GOOGLEMYBUSINESS",
"name": "Google My Business",
"url": "google.com",
"alternateBrands": [
{
"name": "Waze",
"url": ""
}
],
"supportedCountries": [
"AD","AE","AG","AI","AL","AM","AO","AR","AS","AT","AU","AW","AX","AZ","BA",
"BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS",
"BT","BW","BY","BZ","CA","CF","CG","CH","CI","CL","CM","CO","CR","CV","CW",
"CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","ES","ET","FI","FJ",
"FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GN","GP","GQ",
"GR","GT","GU","GY","HK","HN","HR","HT","HU","ID","IE","IL","IM","IN","IQ",
"IS","IT","JE","JM","JO","JP","KE","KH","KN","KR","KW","KY","KZ","LA","LB",
"LC","LI","LK","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK",
"ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ",
"NA","NC","NE","NG","NI","NL","NO","NP","NZ","OM","PA","PE","PH","PK","PL",
"PM","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SC","SE",
"SG","SH","SI","SK","SL","SM","SN","SR","SV","SX","TC","TD","TG","TH","TJ",
"TL","TN","TR","TT","TW","TZ","UA","UG","US","UY","UZ","VC","VE","VG","VI",
"VN","WF","WS","XK","YT","ZA","ZM","ZW"
],
"supportedEntityTypes": [
"LOCATION",
"HEALTHCARE_PROFESSIONAL",
"HEALTHCARE_FACILITY",
"ATM",
"RESTAURANT"
],
"features": [
"DUAL_SYNC",
"REVIEW_MONITORING",
"PUBLISHER_SUGGESTIONS",
"ANALYTICS",
"SOCIAL"
]
}
Cosas que debes tener en cuenta:
-
alternateBrands— Sitios en los que el medio digital también publica datos de entidades, pero con los que Yext no tiene una conexión directa. Por ejemplo, los datos enviados a Google también estarán disponibles en Waze Maps. -
typicalUpdateSpeed— El tiempo previsto, en segundos, que tardarán los cambios realizados en tus entidades en reflejarse en el listing del medio digital. Para los medios digitales que aceptan actualizaciones en tiempo real, el valor predeterminado será 120.
Paso 2: Comprobar el estado de tus Listings
Una vez que confirmas los medios digitales que contiene tu cuenta, puedes comprobar el estado de tus listings mediante el endpoint Listings: List.
| URL | https://api.yextapis.com/v2/accounts/{accountId}/listings/listings |
| Permisos | Listings: READ |
| Descripción | Recupera información del listing, incluido el estado y los motivos por los que un listing podría no estar disponible. |
Solicitud de ejemplo:
| OBTENER | https://api.yextapis.com/v2/accounts/{accountId}/listings/listings?api_key={API_KEY}&v=20210504 |
Ejemplo de respuesta:
{
"id": "187149016",
"locationId": "{entityId}",
"accountId": "{accountId}",
"publisherId": "GOOGLEMYBUSINESS",
"status": "LIVE",
"additionalStatus": "CONNECTED",
"listingUrl": "{URL}",
"loginUrl": "{URL}",
"screenshotUrl": "NO SCREENSHOT FOR PARTNER",
"alternateBrands": [
{
"brandName": "Waze",
"listingUrl": ""
}
]
}
Tipos de estado:
| Tipo | Descripción |
|---|---|
EN VIVO |
La entidad se asocia a un listing y se pueden realizar actualizaciones. |
OPTED_OUT |
La entidad ha optado por no participar. |
UNAVAILABLE |
Hay un problema con el listing. Los Listings devueltos con este estado también mostrarán un array statusDetails con una descripción del problema, y los pasos que se pueden seguir para resolverlo. |
WAITING_ON_YEXT |
El listing sigue a la espera de ser enviado al medio digital. |
WAITING_ON_CUSTOMER |
El listing está a la espera de que el cliente realice una acción, como añadir una cuenta vinculada. |
WAITING_ON_PUBLISHER |
El listing está a la espera de recibir comentarios del medio digital sobre su estado. |
Cosas que debes tener en cuenta:
- Los resultados se ordenan primero por medio digital y, después, por entidad.
- Puedes filtrar tus resultados por un conjunto específico de medios digitales o entidades mediante los parámetros
publisherIdsylocationIds. - Es posible que diferentes editores devuelvan campos exclusivos para su estado. Consulta la documentación de Listings: Enumera la documentación para obtener más información.
Paso 3: Suscribir tus entidades
Para los listings excluidos, puedes usar el endpoint Listings: Opt In para empezar a sincronizar los datos entre la entidad y el medio digital.
| URL | https://api.yextapis.com/v2/accounts/{accountId}/listings/listings |
| Permisos | Listings: READ |
| Descripción | Suscribe las entidades especificadas a los editores designados. |
Solicitud de ejemplo:
| PUT | https://api.yextapis.com/v2/accounts/{accountId}/listings/listings/optin?api_key={API_KEY}&v=20210504&locationIds=[location123,location456]&publisherIds=[YELP] |
Cosas que debes tener en cuenta:
- Puedes especificar un máximo de 100 combinaciones [
locationId,publisherId] para incluirlas. - Si no se incluye el parámetro
locationIds, de forma predeterminada se aplica a todas las entidades con una suscripción activa a Listings. - Si no se incluye el parámetro
publisherIds, de forma predeterminada se utilizan todos los editores disponibles para la cuenta.
Paso 4: Excluir tus entidades
Si en algún momento quieres dejar de enviar actualizaciones de entidades a un medio digital, puedes usar el endpoint Listings: Opt Out.
| URL | https://api.yextapis.com/v2/accounts/{accountId}/listings/listings/optOUT |
| Permisos | Listings: WRITE |
| Descripción | Excluye del servicio las entidades especificadas en los medios digitales designados. |
Solicitud de ejemplo:
| PUT | https://api.yextapis.com/v2/accounts/{accountId}/listings/listings/optout?api_key={API_KEY}&v=20210504&locationIds=[location123,location456]&publisherIds=[YELP] |
Cosas que debes tener en cuenta:
- Puedes especificar un máximo de 100 combinaciones [
locationId,publisherId] para excluirlas. - Si no se incluye el parámetro
locationIds, de forma predeterminada se aplica a todas las entidades con una suscripción activa a Listings. - Si no se incluye el parámetro
publisherIds, de forma predeterminada se utilizan todos los editores disponibles para la cuenta. - Excluir una entidad no elimina su listing del sitio del medio digital. Cuando se excluye una entidad, los nuevos cambios realizados en ella ya no se enviarán al medio digital.
Paso 5: Gestionar la eliminación de duplicados
Una vez al mes, Yext analiza automáticamente los sitios de los medios digitales en busca de posibles duplicados de tus listings. Mediante las API de duplicados, puedes actuar sobre los posibles duplicados y suprimirlos, o enviar tus propios duplicados para que se supriman.
Hay cuatro métodos de supresión para resolver listings duplicados. Varían según el medio digital, pero todos tienen el mismo resultado final de resolver los listings duplicados en el sitio del medio digital.
- Redirección: La URL del listing suprimido se redirige al listing correcto.
- Eliminar de la búsqueda: El listing suprimido ya no aparece en los resultados de búsqueda, pero al navegar directamente a la URL del listing suprimido, es posible que el listing siga apareciendo.
- Página de búsqueda: La URL del listing suprimido se redirige a una búsqueda de listings relacionados.
- No encontrado: La URL del listing suprimido devuelve un error 404 y también se elimina de los resultados de búsqueda del medio digital.
Comprobar el estado de un duplicado
Puedes comprobar el estado de los listings duplicados de tu cuenta mediante el endpoint Duplicates: List.
| URL | https://api.yextapis.com/v2/accounts/{accountId}/listings/duplicates |
| Permisos | Listings: READ |
| Descripción | Recupera una lista de listings duplicados identificados para una cuenta |
Solicitud de ejemplo:
| OBTENER | https://api.yextapis.com/v2/accounts/{accountId}/listings/duplicates?api_key={API_KEY}&v=20210504&entityType=[LOCATION,RESTAURANT] |
Ejemplo de respuesta:
{
"id": "37975024",
"publisherId": "2FINDLOCAL",
"locationId": "6915443573468587404",
"url": "http://www.2findlocal.com/b/13008975/dees-doughnuts-brooklyn-ny",
"name": "Dee's Doughnuts",
"address": "346 Dean St.",
"phone": "3472012419",
"latitude": "40.683239",
"longitude": "-73.980156",
"status": "UNAVAILABLE",
"suppressionType": "REDIRECT"
}
Tipos de estado:
| Tipo | Descripción |
|---|---|
POSSIBLE_DUPLICATE |
El listing se marca como posible duplicado y se puede suprimir mediante el endpoint Duplicates: Suppress. |
SUPPRESSION_REQUESTED |
La solicitud para suprimir este duplicado sigue a la espera de recibir comentarios del medio digital. |
UNAVAILABLE |
Hubo un problema con la solicitud de supresión. Los Listings devueltos con este estado también mostrarán un array UnavailableReasons con una descripción del problema y los pasos para resolverlo. |
SUPPRESSED |
El duplicado se ha suprimido. |
ELIMINADO |
Indica que el posible duplicado ya lo ha eliminado el medio digital. |
Nota: El tipo de supresión devuelto dependerá del medio digital.
Suprimir un posible listing duplicado
Para suprimir un duplicado, usa el endpoint Duplicates: Suppress.
| URL | https://api.yextapis.com/v2/accounts/{accountId}/listings/duplicates/{duplicateId} |
| Permisos | Listings: WRITE |
| Descripción | Envía una solicitud de supresión al medio digital. |
Solicitud de ejemplo:
| PUT | https://api.yextapis.com/v2/accounts/{accountId}/listings/duplicates/{duplicateId}?api_key={API_KEY}&v=20210504 |
Nota: Al enviar solicitudes a este endpoint, debes proporcionar tu ID de usuario de Yext en el encabezado
Yext-User-Id. Este endpoint no admite actualmente la supresión de duplicados de Google.
Eliminar un listing duplicado suprimido o potencial
Si tu cuenta contiene posibles duplicados que son incorrectos o listings suprimidos que deben revertirse, usa el endpoint Duplicates: Delete.
| URL | https://api.yextapis.com/v2/accounts/{accountId}/listings/duplicates/{duplicateId} |
| Permisos | Listings: WRITE |
| Descripción | Elimina un duplicado de una cuenta. |
Solicitud de ejemplo:
| BORRAR | https://api.yextapis.com/v2/accounts/{accountId}/listings/duplicates/{duplicateId}?api_key={API_KEY}&v=20210504 |
Nota: Al enviar solicitudes a este endpoint, debes proporcionar tu ID de usuario de Yext en el encabezado
Yext-User-Id. Si un duplicado tiene el estadoSUPPRESSEDcuando se elimina, esto indicará al medio digital que se debe revertir la supresión.
Enviar y suprimir un nuevo listing duplicado
Para enviar un nuevo duplicado para que se suprima, usa el endpoint Duplicates: Create.
| URL | https://api.yextapis.com/v2/accounts/{accountId}/listings/duplicates |
| Permisos | Listings: WRITE |
| Descripción | Crea un nuevo duplicado y solicita su supresión. |
Solicitud de ejemplo:
| PUT | https://api.yextapis.com/v2/accounts/{accountId}/listings/duplicates/?api_key={API_KEY}&publisherId=GOOGLEMYBUSINESS&url={Duplicate Listing URL} |
Nota: Cuando se envía un duplicado mediante este método, se le asignará automáticamente el estado
SUPPRESSION_REQUESTEDhasta que se reciba la respuesta del medio digital. Este endpoint no admite actualmente la supresión de duplicados de Google.
Comentarios
0 comentarios
El artículo está cerrado para comentarios.