Ubicaciones
Lista, busca, crea, actualiza y archiva ubicaciones de negocios con el SDK listingsapi-js.
Las ubicaciones son la entidad principal de Listings API: cada ficha, reseña, registro de analítica y publicación está asociado a una ubicación. Todos los métodos de ubicación están disponibles en la instancia del cliente ListingsAPI.
fetchAllLocations
Lista las ubicaciones de la cuenta con paginación basada en cursores. Devuelve un objeto con locations, pageInfo, success y los datos raw de la API. Con fetchAll: true, pagina automáticamente y devuelve un Location[] plano en su lugar.
// Single pageconst page = await client.fetchAllLocations({ first: 25 });if (!Array.isArray(page)) {console.log(page.locations); // Location[]console.log(page.pageInfo); // { hasNextPage, hasPreviousPage, startCursor, endCursor, total? } // Next pageconst next = await client.fetchAllLocations({ first: 25, after: page.pageInfo.endCursor!,});} // All pages at once, returns Location[]const all = await client.fetchAllLocations({ fetchAll: true, pageSize: 100 });Opciones
fetchLocationsByIds
Obtiene ubicaciones específicas por ID. Acepta ID numéricos o codificados en base64 y devuelve un Location[] plano. Si el array de entrada está vacío, devuelve [] sin realizar ninguna solicitud.
const locations = await client.fetchLocationsByIds([16808, 16809, 'TG9jYXRpb246MTY4MTA=']);console.log(locations); // Location[]fetchLocationsByStoreCodes
Obtiene las ubicaciones que coinciden con los códigos de tienda proporcionados. Devuelve un Location[] plano; si el array de entrada está vacío, devuelve [] sin realizar ninguna solicitud.
const locations = await client.fetchLocationsByStoreCodes(['AD-SF-001', 'AD-NY-001']);searchLocations
Busca ubicaciones por palabra clave en el nombre, la dirección y el ID de tienda. Devuelve la misma estructura paginada que fetchAllLocations y admite fetchAll de la misma manera.
// Single pageconst result = await client.searchLocations('Brooklyn', { first: 20 });if (!Array.isArray(result)) {console.log(result.locations, result.pageInfo);} // All matching results, returns Location[]const all = await client.searchLocations('Brooklyn', { fetchAll: true }); // Restrict which fields are searchedconst byName = await client.searchLocations('Acme Dental', { fields: ['name'] });Opciones
Todas las opciones de paginación de fetchAllLocations, además de:
createLocation
Crea una nueva ubicación. La API requiere name, un valor de description de al menos 200 caracteres, subCategoryId, countryIso y city. Devuelve los datos de la respuesta con la ubicación creada; si la API rechaza los datos de entrada, el cliente lanza un ValidationError en su lugar, por lo que no hay ningún indicador de éxito que comprobar.
const result = await client.createLocation({name: 'Acme Dental',description: 'Acme Dental is a family-owned dental practice offering cleanings, ' + 'checkups, fillings, crowns, and cosmetic dentistry for patients of all ' + 'ages. Our gentle, experienced team uses modern digital imaging and ' + 'same-day scheduling to make every visit fast and comfortable.',subCategoryId: 1432,countryIso: 'US',city: 'San Francisco',street: '2100 Mission St',stateIso: 'CA',postalCode: '94110',phone: '4155550100',storeId: 'AD-SF-003',});console.log(result.location.id);updateLocation
Actualiza uno o más campos de una ubicación existente. Pasa el id de la ubicación junto con los campos que quieras cambiar. Los ID numéricos se codifican automáticamente.
await client.updateLocation({id: 16808,phone: '4155550199',name: 'Acme Dental Mission District',});archiveLocations
Archiva una o más ubicaciones. Las ubicaciones archivadas dejan de sincronizarse con los directorios.
await client.archiveLocations([16808, 16809]);cancelArchiveLocations
Cancela el archivado programado de las ubicaciones indicadas. Recibe los ID de las ubicaciones, un selectionType y un identificador changedBy como argumentos posicionales.
await client.cancelArchiveLocations([16808],'manual', // selectionType'ops@example.com', // changedBy);Codificación de ID
Todos los métodos de ubicación aceptan un ID numérico o un ID codificado en base64. El SDK codifica automáticamente los ID numéricos (y las cadenas numéricas) con el formato Location:<id>; los valores que ya están codificados se pasan sin cambios.
// These are equivalentawait client.fetchLocationsByIds([16808]);await client.fetchLocationsByIds(['TG9jYXRpb246MTY4MDg=']);El codificador también se exporta por si necesitas obtener directamente la forma codificada:
import { encodeLocationId } from 'listingsapi-js'; encodeLocationId(16808); // 'TG9jYXRpb246MTY4MDg='encodeLocationId('16808'); // 'TG9jYXRpb246MTY4MDg='encodeLocationId('TG9jYXRpb246MTY4MDg='); // unchanged