로고, 커버 및 사진 업로드
URL로 사업장에 로고, 커버 이미지 및 갤러리 사진을 첨부하고, 첨부된 항목을 조회하고, 대표 이미지에 별표를 지정하고, 오래된 항목을 삭제합니다.
사진은 공개 URL을 통해 사업장에 첨부됩니다. 이미지를 호스팅하면 API가 이를 가져와 저장하고, 게시 플랫폼은 저장된 위치에서 이미지를 가져갑니다. 사업장에는 로고 1개, 커버 1개 및 개수 제한 없는 추가 사진을 보관할 수 있으며, 추가 사진 중 최대 4개에 별표를 지정하여 우선 배치할 수 있습니다.
1. URL로 업로드
POST /locations/photos는 input.locationId 및 input.photos 배열을 받습니다. 각 항목의 URL은 url이 아니라 photo라는 필드에 넣습니다. type을 LOGO, COVER 또는 ADDITIONAL로 명시적으로 설정하며, type이 없는 항목은 추가 사진으로 저장됩니다.
curl -X POST https://listingsapi.com/api/v4/locations/photos \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "photos": [ { "photo": "https://cdn.example.com/jenny-home/logo.png", "type": "LOGO" }, { "photo": "https://cdn.example.com/jenny-home/cover.jpg", "type": "COVER" }, { "photo": "https://cdn.example.com/jenny-home/storefront.jpg", "type": "ADDITIONAL" } ] }}'{ "data": { "addLocationPhotos": { "success": true, "request": {}, "photos": [ { "id": "TWVkaWFGaWxlOjU4Nzg5MzE=", "databaseId": 5878931, "type": "LOGO", "starred": false, "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/f47d62a6.png" }, { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "databaseId": 5878932, "type": "ADDITIONAL", "starred": false } ], "errors": null } }}각 사진의 id를 보관합니다. 별표 지정 및 삭제 엔드포인트에서 이 값을 받습니다. LOGO 또는 COVER를 다시 업로드하면 기존 항목이 교체됩니다. 작은 배치는 이와 같이 인라인으로 저장됩니다. 큰 배치는 대신 대기열에 추가되며, photos는 비어 있는 상태로 반환되고 request.requestId가 설정됩니다. requestId의 존재 여부에 따라 분기한 다음 GET /locations/photos/requests/{requestId}를 폴링합니다.
curl https://listingsapi.com/api/v4/locations/photos/requests/e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a \-H "Authorization: API $LISTINGSAPI_KEY"2. 첨부된 항목 조회
GET /locations/{locationId}/photos는 사업장의 모든 미디어 파일을 일반 배열로 반환합니다. 이를 사용하여 업로드 전에 로고나 커버가 누락되었는지 확인하고, 이후 두 단계에서 사용할 id를 수집합니다. 경로에는 base64 id 또는 인코딩하지 않은 숫자를 사용할 수 있습니다.
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/photos \-H "Authorization: API $LISTINGSAPI_KEY"{ "data": { "mediaFilesOfLocation": [ { "id": "TWVkaWFGaWxlOjU4Nzg5MzE=", "categoryName": "Logo", "categoryId": "4", "starred": false, "viewsCount": 0 }, { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "categoryName": "Additional", "categoryId": "12", "starred": true, "viewsCount": 143 } ] }}categoryName은 Logo, Cover 또는 Additional입니다. 미디어가 없는 사업장은 오류가 아니라 빈 배열을 반환합니다.
3. 추가 사진에 별표 지정
POST /locations/photos/star는 대표 이미지 기능을 지원하는 게시 플랫폼에서 우선 배치할 추가 사진을 표시합니다. ADDITIONAL 사진에만 별표를 지정할 수 있으며, 사업장당 최대 4개까지 지정할 수 있습니다. 5번째 사진에 지정하면 전체 호출이 SY15012로 실패합니다. 업로드할 때 항목에 starred: true를 전달할 수도 있습니다.
curl -X POST https://listingsapi.com/api/v4/locations/photos/star \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "photoIds": ["TWVkaWFGaWxlOjU4Nzg5MzI="], "starred": true }}'{ "data": { "starUnstarLocationPhotos": { "success": true, "photos": [ { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "type": "ADDITIONAL", "starred": true } ], "error": null } }}응답 키는 starUnstarLocationPhotos이며, errors 배열이 아니라 단일 error를 담고 있습니다. 본문의 starred 플래그가 동작을 제어하며, 별표를 해제하려면 false를 보냅니다. SDK 메서드는 동일한 boolean 값을 받습니다.
4. 사진 삭제
POST /locations/photos/remove는 id를 기준으로 추가 사진의 첨부를 해제합니다. removedCount는 첨부가 해제된 사진 수를 보고하므로, 0과 함께 errors: null이 반환되면 해당 id 중 이 사업장에 첨부된 항목이 하나도 없었다는 의미입니다.
curl -X POST https://listingsapi.com/api/v4/locations/photos/remove \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "photoIds": ["TWVkaWFGaWxlOjU4Nzg5MzI="] }}'{ "data": { "removeLocationPhotos": { "removedCount": 1, "errors": null } }}여기서는 ADDITIONAL 사진만 삭제할 수 있습니다. 로고나 커버를 변경하려면 해당 type으로 새 이미지를 업로드하면 기존 이미지가 교체됩니다. 삭제하면 파일과 사업장의 연결이 해제되며, 미디어 라이브러리에서 파일이 완전히 삭제되는 것은 아닙니다.