> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiderx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 상품·콘텐츠 데이터 연동

> 서비스의 상품·콘텐츠를 A2에 등록하고, 변경 사항과 사용자 행동 데이터를 같은 ID로 연결하는 방법을 안내합니다.

서비스에서 사용하는 상품이나 콘텐츠의 이름·이미지·분류 정보를 A2에 등록하고, 변경 사항을 반영하는 과정을 다룹니다. A2에서는 이 목록을 **Catalog**로 관리합니다. 등록한 데이터는 추천 기능에 활용되며, 조회·구매 같은 사용자 행동 로그를 같은 항목 ID로 보내면 사용자 행동을 반영한 추천에도 활용됩니다.

Catalog API는 Data Management API이므로 액세스 토큰이 필요합니다. 토큰 발급 방법은 [API 접속과 인증](https://docs.aiderx.io/development/ko/api-access-and-auth.md)을 참고하세요.

## 데이터 준비와 식별자

항목 ID는 Catalog 항목과 사용자 행동 로그를 연결하는 기준입니다. 서비스에서 사용하는 상품·콘텐츠 ID를 그대로 사용하면 별도 변환 없이 데이터를 연결할 수 있습니다. 항목 ID는 A2 환경 전체에서 유일해야 하며, 등록한 뒤에는 바꿀 수 없습니다. 여러 데이터 소스에서 같은 ID를 사용한다면 등록 전에 소스별 접두어를 붙이는 등 겹치지 않게 정하세요.

`id`에는 항목 ID를 넣고, `metadata.id`에도 같은 값을 넣습니다. `metadata`에는 상품명·이미지·분류처럼 상품에 필요한 데이터를 넣으세요. 필드별 상세 속성은 API Reference의 [카탈로그 항목 생성](</ko/0.5.0/data management/catalogs/create-a-catalog-item>)을 참고하세요.

## 등록과 조회

### 등록

```bash theme={null}
curl -X POST "https://your_a2_service/api/manager/catalogs" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "1001",
    "schema": "creative.catalog",
    "status": "active",
    "metadata": {
      "id": "1001",
      "title": "데일리 러닝화",
      "thumbnail": "https://cdn.example.com/items/1001.jpg",
      "link": "https://shop.example.com/products/1001",
      "category": "신발",
      "brand": "Example",
      "ext": {"price": 89000}
    }
  }'
```

등록되면 `201`과 함께 등록된 항목이 반환됩니다. 같은 ID의 항목이 이미 있으면 `409`가 반환되며, 기존 항목은 변경되지 않습니다. 필드 형식이 맞지 않으면 `422`가 반환됩니다.

### 조회

단건 조회로 등록된 값을 확인합니다.

```bash theme={null}
curl "https://your_a2_service/api/manager/catalogs/1001" \
  -H "Authorization: Bearer <token>"
```

목록 조회(`GET /api/manager/catalogs`)에서는 `keyword`(`title` 검색), `category`, `source`로 항목을 찾을 수 있습니다. 한 번에 최대 100개씩 조회되며, `page`와 `page_size`로 페이지를 지정합니다. 상세 요청과 응답은 API Reference의 [목록 조회](</ko/0.5.0/data management/catalogs/list-catalog-items>)를 참고하세요.

> [!NOTE]
>
> 단건 조회와 일괄 등록·수정·삭제 API의 상세 명세는 업데이트 중입니다. 현재는 이 페이지의 요청·응답 예제를 참고하세요.

## 변경 사항 반영

서비스 데이터가 바뀌면 Catalog에도 반영합니다. 변경 내용은 A2의 각 기능에 비동기로 전달되므로 결과에 바로 나타나지 않을 수 있습니다.

| 서비스 데이터 변경 | Catalog 처리 |
| - | - |
| 새 상품 추가 | 등록 |
| 상품 정보 변경 | 수정 |
| 더 이상 사용하지 않는 상품 | 삭제 |

### 수정

수정 요청에는 바꿀 필드만 보냅니다. 다만 `metadata`는 보낸 값으로 전체가 교체되므로, 일부 속성만 바꿀 때도 유지할 속성을 함께 보내야 합니다.

```bash theme={null}
curl -X PATCH "https://your_a2_service/api/manager/catalogs/1001" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "id": "1001",
      "title": "데일리 러닝화",
      "thumbnail": "https://cdn.example.com/items/1001.jpg",
      "link": "https://shop.example.com/products/1001",
      "category": "신발",
      "brand": "Example",
      "ext": {"price": 79000}
    }
  }'
```

삭제는 `DELETE /api/manager/catalogs/{catalog_id}`로 요청하며, 성공하면 `204`가 반환됩니다. 상세 요청과 응답은 API Reference의 [항목 수정](</ko/0.5.0/data management/catalogs/update-a-catalog-item>), [항목 삭제](</ko/0.5.0/data management/catalogs/delete-a-catalog-item>)를 참고하세요.

### ID 변경

항목 ID는 등록 후 변경할 수 없습니다. 새 ID로 등록한 항목은 기존 항목과 다른 항목으로 취급되며, 기존 ID로 쌓인 행동 로그는 새 ID에 연결되지 않습니다. 서비스 코드와 로그에서 사용하는 ID도 함께 바꿔야 하므로, ID 변경이 필요하다면 연동 담당자와 전환 방법을 먼저 확인하세요.

## 일괄 연동

여러 항목은 일괄 API로 한 번에 최대 1,000개까지 처리합니다. 항목마다 따로 처리되므로 일부가 실패해도 나머지는 반영되며, 응답은 HTTP `200`과 함께 성공한 항목(`succeeded`)과 실패한 항목(`failed`)을 나눠 반환합니다. 항목 수가 1,000개를 넘거나 요청 형식이 잘못되면 요청 전체가 `422`로 거부됩니다.

| 작업 | 요청 | 본문 |
| - | - | - |
| 일괄 등록 | `POST /api/manager/catalogs/batch-create` | `items`: 등록 요청과 같은 항목의 배열 |
| 일괄 수정 | `POST /api/manager/catalogs/batch-update` | `items`: `id`와 수정할 필드를 담은 항목의 배열 |
| 일괄 삭제 | `POST /api/manager/catalogs/batch-delete` | `ids`: 삭제할 항목 ID 배열 |

다음은 `1002`가 이미 등록된 상태에서 두 항목을 일괄 등록한 예입니다.

```bash theme={null}
curl -X POST "https://your_a2_service/api/manager/catalogs/batch-create" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "1001",
        "schema": "creative.catalog",
        "status": "active",
        "metadata": {"id": "1001", "title": "데일리 러닝화"}
      },
      {
        "id": "1002",
        "schema": "creative.catalog",
        "status": "active",
        "metadata": {"id": "1002", "title": "트레일 러닝화"}
      }
    ]
  }'
```

```json Response theme={null}
{
  "succeeded": [
    {
      "id": "1001",
      "source": null,
      "status": "active",
      "schema": "creative.catalog",
      "metadata": {"id": "1001", "title": "데일리 러닝화"},
      "created_at": "2026-10-20T00:00:00Z",
      "updated_at": "2026-10-20T00:00:00Z"
    }
  ],
  "failed": [
    {"id": "1002", "reason": "Already exists."}
  ]
}
```

실패한 항목은 `failed[].id`로 원본 데이터와 연결합니다. 일괄 수정의 결과는 요청 순서가 아니라 ID 순서로 반환되므로 순서에 의존하지 마세요. 일괄 삭제의 `succeeded`에는 삭제된 항목 ID가 담깁니다.

`failed[].reason`은 사람이 읽기 위한 메시지이며, 현재 별도의 오류 코드는 제공되지 않습니다. 메시지 표현은 바뀔 수 있으므로 실패 원인을 확인하는 용도로만 사용하세요.

일괄 등록은 이미 등록된 항목을 덮어쓰지 않습니다. 서비스 데이터를 주기적으로 반영할 때는 바뀐 항목만 골라, 새 항목은 일괄 등록으로 보내고 기존 항목은 일괄 수정으로 보내세요.

전체를 삭제한 뒤 다시 등록하는 방식은 피하세요. 삭제하면 항목에서 추출한 특징 데이터도 함께 삭제되어, 다시 등록해도 바로 이전 상태로 돌아가지 않습니다.

## 행동 데이터 연결과 검증

Catalog에 등록한 데이터를 사용자 행동을 반영한 추천에 활용하려면 사용자 행동 로그와 연결해야 합니다. 조회·장바구니·구매 같은 사용자 행동 로그를 보낼 때 `catalogs[].id`에 등록한 항목 ID를 넣으세요. 행동 로그 전송 방법은 API Reference의 [활동 로그 기록](https://docs.aiderx.io/ko/0.5.0/decision/activity-log/record-activity-log.md)을 참고하세요.

추천 기능을 사용한다면 추천 요청의 `seed_item_id`, 추천 응답의 `items[].catalog_id`, 추천 이벤트 로그의 `event_items`에도 같은 항목 ID를 사용합니다.

항목 ID는 모든 요청에서 동일한 문자열로 전달하세요. 예를 들어 `"001001"`을 숫자로 변환하면 앞자리 0이 사라져 원래 항목과 연결되지 않을 수 있습니다.

연동한 뒤에는 다음을 확인하세요.

* 등록한 항목을 단건 조회해 `metadata`가 의도한 값으로 저장되었는지 확인합니다.
* 행동 로그에 보내는 항목 ID가 등록한 ID와 같은 문자열인지 확인합니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.