Encuentra y suprime fichas duplicadas

Lista fichas duplicadas por ubicación y cuenta, confirma las reales para suprimirlas, descarta falsos positivos y sigue cada una hasta su resolución.

Un duplicado es una segunda entrada del mismo negocio en el mismo directorio. Divide las reseñas y las señales de posicionamiento y confunde a los clientes. La detección se ejecuta automáticamente. Revisas lo que ha encontrado, confirmas los duplicados reales y descartas las entradas que son legítimas.

Cada duplicado tiene un estado que te indica en qué punto del proceso de limpieza se encuentra:

1. Enumera los duplicados de una ubicación

GET /locations/{locationId}/listings/duplicates devuelve un array simple de grupos de sitios. Cada grupo es un directorio con un array listings de posibles duplicados, y cada entrada tiene un listingItemId, un liveLink que puedes abrir para evaluarla y un status.

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/duplicates \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "duplicateListingsForLocation": [      {        "id": "U2l0ZToxNTA=",        "name": "City Squares",        "url": "citysquares.com",        "listings": [          {            "id": "RHVwbGljYXRlOjIzNTk4NDUw",            "listingItemId": "TGlzdGluZ0l0ZW06MjM1OTg0NTA=",            "name": "Woodbury Train Station",            "liveLink": "http://citysquares.com/b/woodbury-train-station-23598450",            "status": "POTENTIAL"          }        ]      }    ]  }}

Un array vacío significa que no se ha detectado nada. Conserva listingItemId: es el valor que aceptan ambos endpoints de marcado. El Node SDK aplana los grupos en un array por duplicado, por lo que d.id es el valor que debes pasar en ese caso.

2. Obtén una vista agregada de los duplicados de toda la cuenta

GET /locations/listings/duplicates es la vista de toda la cuenta. Es una página basada en desplazamiento: recibe page y perPage y devuelve records[] junto con pageInfo.totalRecords y pageInfo.totalPages. El valor predeterminado de status es POTENTIAL y el de tag es all, por lo que una llamada sin parámetros devuelve todos los duplicados abiertos que la clave permite consultar. Añade siteId (un id de plan-sites) para limitar los resultados a un directorio.

curl "https://listingsapi.com/api/v4/locations/listings/duplicates?status=POTENTIAL&page=1&perPage=50" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "duplicateListingsRollup": {      "pageInfo": { "hasNextPage": true, "totalPages": 34, "totalRecords": 1673 },      "records": [        {          "id": "3329229",          "name": "Woodbury Train Station",          "duplicateProcessingState": "POTENTIAL",          "liveLink": "http://citysquares.com/b/woodbury-train-station-23598450",          "locationId": "73451",          "siteName": "City Squares",          "siteUrl": "citysquares.com"        }      ]    }  }}

La vista agregada te indica dónde están los duplicados; duplicateProcessingState es el mismo estado del ciclo de vida descrito arriba. Para actuar sobre uno, usa su locationId en el endpoint por ubicación del paso 1 y consulta allí el listingItemId. Recorre las páginas de una en una; un bucle sin pausas es la forma más rápida de provocar un 429.

3. Confirma un duplicado para que se suprima

Una vez que la persona encargada de la revisión confirme que una entrada es un duplicado, llama a POST /locations/listings/mark-as-duplicate con los valores de listingItemId en input. Agrupa todos los ids confirmados de una ubicación en una sola llamada. locationId es opcional y limita la solicitud a esa ubicación.

curl -X POST https://listingsapi.com/api/v4/locations/listings/mark-as-duplicate \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "listingItemIds": ["TGlzdGluZ0l0ZW06MjM1OTg0NTA="]  }}'

{  "data": {    "markAsDuplicate": {      "success": true,      "errors": null    }  }}

success: true significa que los elementos se han aceptado y han pasado a PROCESSING. Un 200 con success: false, o un 400, incluye un array errors cuyas entradas contienen code y message; la causa habitual es un id desconocido o con un formato incorrecto. Los SDK lanzan ValidationError en ese caso.

4. Descarta un falso positivo

La detección es conservadora. Otro establecimiento de la misma franquicia, un segundo perfil legítimo o una ubicación que ha cambiado de nombre pueden parecer duplicados. POST /locations/listings/mark-as-not-duplicate acepta exactamente el mismo cuerpo y elimina la entrada de ambas listas de forma permanente. También es la forma de revertir un paso 3 realizado por error.

curl -X POST https://listingsapi.com/api/v4/locations/listings/mark-as-not-duplicate \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "listingItemIds": ["TGlzdGluZ0l0ZW06MjM1OTg0NTA="]  }}'

La respuesta es data.markAsNotDuplicate con los mismos campos success y errors que en el paso 3.

5. Haz un seguimiento del progreso

Vuelve a consultar la vista agregada con status=PROCESSING para ver qué duplicados siguen en manos de las plataformas de publicación, y con status=FIXED para confirmar cuáles han desaparecido. Ninguno de los dos SDK expone todavía el filtro status, así que llama al endpoint directamente con la misma cabecera Authorization.

curl "https://listingsapi.com/api/v4/locations/listings/duplicates?status=PROCESSING&page=1&perPage=50" \-H "Authorization: API $LISTINGSAPI_KEY" curl "https://listingsapi.com/api/v4/locations/listings/duplicates?status=FIXED&page=1&perPage=50" \-H "Authorization: API $LISTINGSAPI_KEY"

Solicitar perPage=1 y consultar pageInfo.totalRecords te permite obtener el recuento de cada estado en cuatro llamadas. Un registro FAILED cuyo liveLink todavía lleva a una página accesible necesita una revisión manual; un registro FAILED cuyo enlace ya no funciona corresponde a un duplicado que la plataforma de publicación ha resuelto por su cuenta y se puede descartar siguiendo el paso 4.

Próximos pasos

• Consulta el estado de las fichas y los enlaces activos: la ficha principal de cada directorio, con la que compite un duplicado.
• Busca y corrige errores en las fichas: la otra ronda de limpieza.
• Referencia: Obtén las fichas duplicadas de una ubicación, Obtén todas las fichas duplicadas de una cuenta, Marca una ficha como duplicada, Marca una ficha como no duplicada.