사이트 API

사이트는 알마니에 연동된 쇼핑몰 단위입니다. 대부분의 API는 X-Site-Id 헤더로 대상 사이트를 지정해야 하며, 그 헤더에 넣을 사이트 ID를 얻는 시작점이 바로 이 API입니다. 키가 접근할 수 있는 사이트 목록과 사이트별 발신프로필 등록 여부를 함께 확인할 수 있습니다.

X-Site-Id 없이 호출할 수 있는 유일한 목록 API입니다 X-Site-Id 헤더를 생략할 수 있는 엔드포인트는 GET /sites 와 GET /me 둘뿐이며, 그중 목록 API는 이 API가 유일합니다. 연동을 시작할 때 가장 먼저 호출해 사이트 ID를 확보한 뒤, 이후 요청의 X-Site-Id 헤더에 사용하세요. 4003(X-Site-Id 헤더 누락) 에러를 받았을 때도 이 API로 접근 가능한 사이트를 확인합니다.
시작 전에 이 API는 인증에서 발급한 API 키(Authorization: Bearer …)만 있으면 호출할 수 있습니다. 예시의 ak_live_xxxx 는 더미 키입니다. 에러 응답 형식과 전체 에러 코드는 에러 형식과 코드를 참고하세요.

사이트 목록 조회

GET /sites

요청에 사용한 API 키의 소유 계정에 연결된 전체 사이트 목록을 조회합니다. 삭제되지 않은 사이트(SITE_INFO.DEL_YN = 'N')만 반환합니다. 별도 스코프 없이 모든 유효한 API 키로 호출할 수 있습니다. 커서 페이지네이션(공통 규약 참조)을 지원하며, 대부분의 계정은 사이트 수가 적어 첫 페이지에 모두 반환됩니다.

Query 파라미터

limit 선택 int

페이지 크기입니다. 기본 20, 최대 100.

cursor 선택 string

이전 응답의 data.nextCursor 값입니다. 없으면 첫 페이지를 반환합니다.

Response

items[].siteId number

사이트 ID입니다. 이후 요청의 X-Site-Id 헤더에 이 값을 사용합니다.

items[].siteName string

알마니 콘솔에 등록된 사이트 이름입니다.

items[].platform string

사이트가 연동된 쇼핑몰 플랫폼 코드입니다. 예: cafe24 · makeshop · imweb 등.

items[].siteUrl string

사이트 URL입니다.

items[].active boolean

사이트 활성 여부입니다. 현재 목록은 삭제되지 않은 사이트만 반환하므로 반환 항목은 true입니다.

items[].registeredAt string

사이트 등록 시각입니다. ISO-8601, KST 오프셋 포함.

items[].senderProfileRegistered boolean

발신프로필 등록 여부입니다. false 인 사이트는 자동 검수 템플릿 생성·검수 요청·검수 취소 시 6001 에러가 반환되므로, 먼저 발신프로필 API로 등록을 완료해야 합니다.

nextCursor string | null

null이면 마지막 페이지입니다.

요청 예시 
curl "https://docs.almani-center.com/open/v1/sites" \
  -H "Authorization: Bearer ak_live_xxxx"
// Java 17 + Spring Framework 6 RestClient
RestClient restClient = RestClient.builder()
        .baseUrl("https://docs.almani-center.com/open/v1")
        .defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer ak_live_xxxx")
        .build();

String response = restClient.get()
        .uri("/sites")
        .retrieve()
        .body(String.class);
응답 예시 
HTTP/1.1 200 OK

{
  "code": "0000",
  "message": "OK",
  "data": {
    "items": [
      {
        "siteId": 1024,
        "siteName": "알마니몰",
        "platform": "cafe24",
        "siteUrl": "https://almanimall.example.com",
        "active": true,
        "registeredAt": "2026-06-10T09:12:00+09:00",
        "senderProfileRegistered": true
      },
      {
        "siteId": 1025,
        "siteName": "알마니 스토어",
        "platform": "makeshop",
        "siteUrl": "https://almanistore.example.com",
        "active": true,
        "registeredAt": "2026-07-02T15:40:00+09:00",
        "senderProfileRegistered": false
      }
    ],
    "nextCursor": null
  },
  "meta": {
    "requestId": "req_2b91cd07",
    "quota": {
      "rateLimit": {
        "limit": 120,
        "remaining": 119,
        "resetAt": "2026-07-25T14:31:00+09:00"
      }
    }
  }
}