사업장 찾기 및 관리 종료 사업장 보관 처리

키워드로 검색하고, 매장 코드와 id를 일괄 조회하고, 폐점한 지점이 청구 주기 종료 시 보관 처리되도록 예약하고, 보관 처리 예약을 취소합니다.

3개의 읽기 엔드포인트는 자유 텍스트 검색, 매장 코드 조회, id 조회라는 서로 다른 키로 사업장을 찾습니다. 보관 처리는 예약된 쓰기 작업으로, 사업장은 현재 청구 주기가 끝날 때까지 활성 상태를 유지하며, 그 후에는 동기화와 요금 청구가 중단됩니다. 그 시점까지는 보관 처리 예약을 취소할 수 있습니다.

1. 키워드로 검색

GET /locations/search?query=는 검색어를 이름, 도로명 주소, 도시, 매장 id와 대조하고, pageInfo.endCursor가 포함된 edges[].node를 커서 연결로 반환하며, first와 after로 페이지를 나눕니다. 계정 전체를 페이지 단위로 조회하려면 query를 생략합니다.

curl "https://listingsapi.com/api/v4/locations/search?query=Acme&first=10" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "searchLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Acme Kitchen",            "storeId": "ACME-NYC-001",            "approved": "APPROVED",            "archived": false,            "archivalScheduledAt": null          }        }      ],      "pageInfo": { "endCursor": "TG9jYXRpb246MTgwMDI4OQ==", "hasNextPage": false, "total": 1 }    }  }}

edges 배열이 비어 있으면 일치하는 항목이 없다는 뜻이며, 매장이 이미 존재하는지 확실하지 않을 때는 생성 전에 이를 확인합니다. 두 SDK 모두 fields를 받아 일치 대상을 name 또는 store_id로만 제한할 수 있습니다.

2. 매장 코드로 조회

시스템에서 자체 매장 코드를 사업장 식별 키로 사용한다면 GET /locations-by-store-codes로 해당 사업장을 직접 조회합니다. storeCodes 매개변수는 URL로 인코딩된 JSON 배열입니다. 일치하는 항목이 없는 코드는 결과에 포함되지 않습니다.

curl -G https://listingsapi.com/api/v4/locations-by-store-codes \--data-urlencode 'storeCodes=["ACME-NYC-001","ACME-NYC-002"]' \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "getLocationsByStoreCodes": [      {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "storeId": "ACME-NYC-001",        "name": "Acme Kitchen",        "archived": false      }    ]  }}

3. id 묶음의 전체 레코드 조회

자체 저장소나 웹훅 페이로드에서 얻은 base64 id를 이미 보유하고 있다면, GET /locations-by-ids는 한 번의 호출로 해당 id 모두의 전체 레코드를 반환합니다. 보관 처리된 사업장도 조회되므로 archived와 archivedAt을 확인하여 구분합니다. 알 수 없는 id는 별도 알림 없이 제외되므로 개수를 비교합니다.

curl -G https://listingsapi.com/api/v4/locations-by-ids \--data-urlencode 'ids=["TG9jYXRpb246MTgwMDI4OQ==","TG9jYXRpb246MTgwMDI5MA=="]' \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "getLocationsByIds": [      { "id": "TG9jYXRpb246MTgwMDI4OQ==", "databaseId": 1800289, "name": "Acme Kitchen", "archived": false, "archivedAt": null },      { "id": "TG9jYXRpb246MTgwMDI5MA==", "databaseId": 1800290, "name": "Acme Kitchen Brooklyn", "archived": false, "archivedAt": null }    ]  }}

계정 전체에서 일부만 서버 측에서 걸러 조회하려면 GET /locations에 JSON으로 인코딩된 filter 매개변수를 전달합니다. 예를 들어 승인 상태별로 필터링할 수 있습니다. 모든 사업장 조회를 참조합니다.

4. 더 이상 관리하지 않는 사업장 보관 처리

POST /locations/archive는 input.locationIds를 받고 사업장마다 result 항목을 하나씩 반환합니다. 보관 처리는 즉시 실행되지 않고 예약됩니다. 각 사업장은 ARCHIVE_SCHEDULED 상태로 전환되고, 현재 청구 주기가 끝날 때까지 계속 동기화되며, 다음 청구서가 생성될 때 보관 처리됩니다. 그때부터 게시 플랫폼과의 동기화 및 요금 청구가 중단됩니다.

curl -X POST https://listingsapi.com/api/v4/locations/archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationIds": ["TG9jYXRpb246MTgwMDI4OQ==", "TG9jYXRpb246MTgwMDI5MA=="]  }}'

{  "data": {    "archiveLocations": {      "errors": null,      "result": [        { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ARCHIVE_SCHEDULED", "success": true, "errors": null },        { "locationId": "TG9jYXRpb246MTgwMDI5MA==", "status": "ARCHIVE_SCHEDULED", "success": true, "errors": null }      ]    }  }}

각 항목의 success를 확인합니다. 잘못된 id 하나가 나머지 일괄 처리를 막지는 않습니다. 보관 처리가 예약된 동안에는 목록 및 검색 결과에서 해당 사업장의 archivalScheduledAt 필드가 설정됩니다. 보관 처리된 사업장은 다시 활성화하기 전까지 업데이트할 수 없습니다. 웹훅이 구성되어 있으면 profile.deleted 이벤트가 발생하며, 이는 소프트 삭제이고 하드 삭제는 없습니다.

5. 보관 처리 예약 취소

청구 주기가 끝나기 전에 동일한 id로 POST /locations/cancel_archive를 호출하면 해당 사업장이 ACTIVE 상태로 돌아가고 요금 청구가 계속됩니다. 사업장이 완전히 보관 처리된 후에는 해당 사업장에 대해 404를 반환합니다. 취소 시 웹훅 이벤트는 발생하지 않습니다.

curl -X POST https://listingsapi.com/api/v4/locations/cancel_archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="] } }'

{  "data": {    "cancelLocationsArchive": {      "errors": null,      "result": [        { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ACTIVE", "success": true, "errors": null }      ]    }  }}

두 SDK 모두 선택 유형과 changedBy 식별자라는 2개의 추가 위치 인수가 필요하며, 이를 locationIds와 함께 전송합니다. REST 본문에는 id만 필요합니다.

다음 단계

• 사업장 추가: 생성 호출과 이 호출에서 storeId를 설정하면 2단계를 수행할 수 있는 이유를 설명합니다.
• 사업장 업데이트: 찾은 사업장을 보관 처리하는 대신 세부 정보를 수정합니다.
• 사업장 검색, 매장 코드로 사업장 조회, ID로 사업장 조회, 사업장 보관 처리 및 예약된 보관 처리 취소: 참조 페이지입니다.