사업장
listingsapi-js SDK로 사업장 목록을 조회하고, 사업장을 검색, 생성, 수정 및 보관 처리합니다.
사업장은 Listings API의 핵심 엔터티입니다. 모든 등록 정보, 리뷰, 분석 레코드, 게시물은 하나의 사업장에 속합니다. 모든 사업장 메서드는 ListingsAPI 클라이언트 인스턴스에 있습니다.
fetchAllLocations
커서 기반 페이지네이션으로 계정의 사업장 목록을 조회합니다. locations, pageInfo, success 및 raw API 페이로드가 포함된 객체를 반환합니다. fetchAll: true를 사용하면 자동으로 페이지를 순회하고, 대신 평탄화된 Location[]를 반환합니다.
// 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 });옵션
fetchLocationsByIds
ID로 특정 사업장을 조회합니다. 숫자 ID 또는 base64로 인코딩된 ID를 받아 평탄화된 Location[]를 반환합니다. 입력 배열이 비어 있으면 요청을 보내지 않고 []를 반환합니다.
const locations = await client.fetchLocationsByIds([16808, 16809, 'TG9jYXRpb246MTY4MTA=']);console.log(locations); // Location[]fetchLocationsByStoreCodes
지정한 매장 코드와 일치하는 사업장을 조회합니다. 평탄화된 Location[]를 반환하며, 입력 배열이 비어 있으면 요청을 보내지 않고 []를 반환합니다.
const locations = await client.fetchLocationsByStoreCodes(['AD-SF-001', 'AD-NY-001']);searchLocations
이름, 주소, 매장 ID에서 키워드로 사업장을 검색합니다. fetchAllLocations와 동일한 페이지네이션 응답 구조를 반환하며, fetchAll도 같은 방식으로 지원합니다.
// 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'] });옵션
fetchAllLocations의 모든 페이지네이션 옵션과 다음 옵션을 지원합니다:
createLocation
새 사업장을 생성합니다. API에는 name, 200자 이상의 description, subCategoryId, countryIso, city가 필요합니다. 생성된 사업장이 포함된 응답 페이로드를 반환하며, API가 입력을 거부하면 클라이언트가 대신 ValidationError를 발생시키므로 확인할 성공 플래그는 없습니다.
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
기존 사업장의 필드를 하나 이상 수정합니다. 사업장 id와 변경할 필드를 전달합니다. 숫자 ID는 자동으로 인코딩됩니다.
await client.updateLocation({id: 16808,phone: '4155550199',name: 'Acme Dental Mission District',});archiveLocations
하나 이상의 사업장을 보관 처리합니다. 보관 처리된 사업장은 디렉터리와의 동기화가 중단됩니다.
await client.archiveLocations([16808, 16809]);cancelArchiveLocations
지정한 사업장의 보관 처리 예약을 취소합니다. 사업장 ID, selectionType, changedBy 식별자를 위치 인수로 받습니다.
await client.cancelArchiveLocations([16808],'manual', // selectionType'ops@example.com', // changedBy);ID 인코딩
모든 사업장 메서드는 숫자 ID 또는 base64로 인코딩된 ID를 받습니다. SDK는 Location:<id> 형식을 사용하여 숫자 ID와 숫자 문자열을 자동으로 인코딩하며, 이미 인코딩된 값은 그대로 전달합니다.
// These are equivalentawait client.fetchLocationsByIds([16808]);await client.fetchLocationsByIds(['TG9jYXRpb246MTY4MDg=']);인코딩된 값이 직접 필요한 경우를 위해 인코더도 내보냅니다:
import { encodeLocationId } from 'listingsapi-js'; encodeLocationId(16808); // 'TG9jYXRpb246MTY4MDg='encodeLocationId('16808'); // 'TG9jYXRpb246MTY4MDg='encodeLocationId('TG9jYXRpb246MTY4MDg='); // unchanged