Établissements
Listez, recherchez, créez, mettez à jour et archivez des établissements avec le SDK listingsapi-js.
Les établissements sont l’entité centrale de Listings API : chaque fiche, avis, enregistrement analytique et publication est rattaché à un établissement. Toutes les méthodes relatives aux établissements sont disponibles sur l’instance client ListingsAPI.
fetchAllLocations
Liste les établissements du compte avec une pagination par curseur. Renvoie un objet contenant locations, pageInfo, success et les données raw de l’API. Avec fetchAll: true, la pagination est automatique et la méthode renvoie à la place un Location[] à plat.
// 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 });Options
fetchLocationsByIds
Récupère des établissements précis à partir de leur ID. Accepte des ID numériques ou encodés en base64 et renvoie un Location[] à plat. Si le tableau d’entrée est vide, renvoie [] sans effectuer de requête.
const locations = await client.fetchLocationsByIds([16808, 16809, 'TG9jYXRpb246MTY4MTA=']);console.log(locations); // Location[]fetchLocationsByStoreCodes
Récupère les établissements correspondant aux codes de magasin fournis. Renvoie un Location[] à plat ; si le tableau d’entrée est vide, renvoie [] sans effectuer de requête.
const locations = await client.fetchLocationsByStoreCodes(['AD-SF-001', 'AD-NY-001']);searchLocations
Recherche des établissements par mot-clé dans le nom, l’adresse et l’ID du magasin. Renvoie la même structure paginée que fetchAllLocations et prend en charge fetchAll de la même manière.
// 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'] });Options
Toutes les options de pagination de fetchAllLocations, ainsi que :
createLocation
Crée un nouvel établissement. L’API exige name, un description d’au moins 200 caractères, un subCategoryId, countryIso et city. Renvoie les données de réponse contenant l’établissement créé ; si l’API rejette les données d’entrée, le client lève à la place une exception ValidationError, il n’y a donc aucun indicateur de réussite à vérifier.
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
Met à jour un ou plusieurs champs d’un établissement existant. Fournissez le champ id de l’établissement ainsi que les champs à modifier. Les ID numériques sont encodés automatiquement.
await client.updateLocation({id: 16808,phone: '4155550199',name: 'Acme Dental Mission District',});archiveLocations
Archive un ou plusieurs établissements. Les établissements archivés ne sont plus synchronisés avec les annuaires.
await client.archiveLocations([16808, 16809]);cancelArchiveLocations
Annule l’archivage programmé des établissements indiqués. Accepte les ID des établissements, un selectionType et un identifiant changedBy comme arguments positionnels.
await client.cancelArchiveLocations([16808],'manual', // selectionType'ops@example.com', // changedBy);Encodage des ID
Chaque méthode relative aux établissements accepte un ID numérique ou un ID encodé en base64. Le SDK encode automatiquement les ID numériques (ainsi que les chaînes numériques) au format Location:<id> ; les valeurs déjà encodées sont transmises telles quelles.
// These are equivalentawait client.fetchLocationsByIds([16808]);await client.fetchLocationsByIds(['TG9jYXRpb246MTY4MDg=']);L’encodeur est également exporté si vous avez besoin d’obtenir directement la forme encodée :
import { encodeLocationId } from 'listingsapi-js'; encodeLocationId(16808); // 'TG9jYXRpb246MTY4MDg='encodeLocationId('16808'); // 'TG9jYXRpb246MTY4MDg='encodeLocationId('TG9jYXRpb246MTY4MDg='); // unchanged