상품 API

캠페인 상품필터에 넣을 상품과 옵션을 검색합니다. 알마니 콘솔의 상품 선택 창과 같은 데이터와 선택 조건을 사용합니다.

콘솔과 동일한 검색 범위 상품은 X-Site-Id의 사이트·플랫폼 안에서만 검색되며 삭제 상품은 제외됩니다. 검색어는 상품명, 상품코드, 자체 상품코드에 부분 일치하고 productId에는 정확히 일치합니다. 옵션 목록은 삭제되지 않고 상품 매칭이 활성화된 옵션(MATCH_ENABLED_YN=Y)만 반환합니다.

상품 전체 옵션을 대상으로 하려면 캠페인 상품필터 요청에서 variantIds를 생략하거나 빈 배열로 보내세요. 특정 옵션만 대상으로 할 때만 이 페이지의 옵션 조회 결과를 넣습니다.

공통 요청 정보

Base URL필수string

https://docs.almani-center.com/open/v1

Authorization필수header

Bearer ak_live_xxxx 형식의 API 키입니다. 키에는 campaign:read 스코프가 필요합니다.

X-Site-Id필수header

조회할 알마니 사이트 ID입니다. API 키 소유자의 사이트가 아니면 4004로 거절됩니다.

상품 검색

GET/products

필요 스코프: campaign:read

Query 파라미터

keyword선택string

상품명·상품코드·자체 상품코드 부분 검색 또는 productId 정확 검색. 최대 100자.

displayOnly선택boolean

true이면 진열 상품만 반환합니다.

sellingOnly선택boolean

true이면 판매 중인 상품만 반환합니다.

limit선택integer

한 페이지의 상품 수입니다. 기본 20, 최대 100입니다.

cursor선택string

다음 페이지를 조회할 때 직전 응답의 nextCursor를 가공하지 않고 그대로 보냅니다.

주요 응답 필드

items[].productIdstring

상품필터 요청에 사용할 알마니 상품 식별자입니다.

items[].productCodestring

플랫폼 상품코드입니다. Cafe24의 예: P00000BB.

items[].customProductCodestring | null

쇼핑몰에서 지정한 자체 상품코드입니다.

items[].productName / pricestring / number

현재 동기화된 상품명과 판매가입니다.

items[].display / selling / soldOutboolean

진열, 판매, 품절 상태입니다. 상품필터 등록 가능 여부와 실제 판매 가능 여부를 함께 판단할 때 사용합니다.

items[].hasSelectableVariantsboolean

true이면 옵션 조회 API로 선택 가능한 품목코드를 확인할 수 있습니다.

items[].updatedAtdatetime | null

알마니에 저장된 상품 정보의 마지막 갱신 시각입니다.

nextCursorstring | null

다음 페이지가 없으면 null입니다.

요청 예시
curl "https://docs.almani-center.com/open/v1/products?keyword=다이어리&displayOnly=true&sellingOnly=true" \
  -H "Authorization: Bearer ak_live_xxxx" \
  -H "X-Site-Id: 467"
응답 예시
{
  "code": "0000",
  "data": {
    "items": [{
      "productId": "27",
      "productCode": "P00000BB",
      "customProductCode": "DIARY-BASE",
      "productName": "다이어리",
      "price": 39000,
      "display": true,
      "selling": true,
      "soldOut": false,
      "hasSelectableVariants": true
    }],
    "nextCursor": null
  }
}

상품 옵션 조회

GET/products/{productId}/variants

필요 스코프: campaign:read

해당 상품에 속하고 현재 상품필터에서 선택할 수 있는 옵션만 반환합니다. 다른 사이트 상품 또는 매칭 비활성 옵션은 반환하지 않습니다.

Path 파라미터

productId필수string

상품 검색 응답의 productId입니다. 최대 100자입니다.

응답 필드

items[].variantIdstring

상품필터의 variantIds에 넣을 옵션 식별자입니다.

items[].variantKeyTypestring

플랫폼별 옵션 키 유형입니다. Cafe24는 CAFE24_VARIANT_CODE를 사용합니다.

items[].optionLabelstring

관리자가 구분할 수 있는 옵션 조합명입니다.

items[].display / selling / soldOutboolean

옵션의 진열·판매·품절 상태입니다.

요청 예시
curl "https://docs.almani-center.com/open/v1/products/27/variants" \
  -H "Authorization: Bearer ak_live_xxxx" \
  -H "X-Site-Id: 467"
응답 예시
{
  "code": "0000",
  "data": {
    "productId": "27",
    "items": [{
      "variantId": "P00000BB000A",
      "variantKeyType": "CAFE24_VARIANT_CODE",
      "optionLabel": "기본 / A",
      "display": true,
      "selling": true,
      "soldOut": false
    }]
  }
}

상품 선택 후 캠페인에 적용하기

GET /products로 상품의 productId를 찾습니다.
특정 옵션만 대상으로 할 때 GET /products/{productId}/variants로 variantId를 확인합니다.
현재 상품필터와 revision을 조회합니다.
상품 추가·제거 API를 실행합니다.

상품 API 오류

코드	HTTP	발생 조건
`4000`	400	`keyword` 또는 `productId` 형식이 올바르지 않음
`4003`	400	`X-Site-Id` 헤더 누락
`4004`	403	API 키 소유자가 아닌 사이트 요청
`4005`	403	`campaign:read` 스코프 없음
`4040`	404	해당 사이트·플랫폼에서 상품을 찾을 수 없음