상품·콘텐츠 데이터 연동

서비스에서 사용하는 상품이나 콘텐츠의 이름·이미지·분류 정보를 A2에 등록하고, 변경 사항을 반영하는 과정을 다룹니다. A2에서는 이 목록을 Catalog로 관리합니다. 등록한 데이터는 추천 기능에 활용되며, 조회·구매 같은 사용자 행동 로그를 같은 항목 ID로 보내면 사용자 행동을 반영한 추천에도 활용됩니다. Catalog API는 Data Management API이므로 액세스 토큰이 필요합니다. 토큰 발급 방법은 API 접속과 인증을 참고하세요.

데이터 준비와 식별자

항목 ID는 Catalog 항목과 사용자 행동 로그를 연결하는 기준입니다. 서비스에서 사용하는 상품·콘텐츠 ID를 그대로 사용하면 별도 변환 없이 데이터를 연결할 수 있습니다. 항목 ID는 A2 환경 전체에서 유일해야 하며, 등록한 뒤에는 바꿀 수 없습니다. 여러 데이터 소스에서 같은 ID를 사용한다면 등록 전에 소스별 접두어를 붙이는 등 겹치지 않게 정하세요. id에는 항목 ID를 넣고, metadata.id에도 같은 값을 넣습니다. metadata에는 상품명·이미지·분류처럼 상품에 필요한 데이터를 넣으세요. 필드별 상세 속성은 API Reference의 카탈로그 항목 생성을 참고하세요.

등록과 조회

등록

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가 반환됩니다.

조회

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

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의 목록 조회를 참고하세요.

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

변경 사항 반영

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

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

수정

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

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의 항목 수정, 항목 삭제를 참고하세요.

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가 이미 등록된 상태에서 두 항목을 일괄 등록한 예입니다.

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": "트레일 러닝화"}
      }
    ]
  }'

Response

{
  "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의 활동 로그 기록을 참고하세요. 추천 기능을 사용한다면 추천 요청의 seed_item_id, 추천 응답의 items[].catalog_id, 추천 이벤트 로그의 event_items에도 같은 항목 ID를 사용합니다. 항목 ID는 모든 요청에서 동일한 문자열로 전달하세요. 예를 들어 "001001"을 숫자로 변환하면 앞자리 0이 사라져 원래 항목과 연결되지 않을 수 있습니다. 연동한 뒤에는 다음을 확인하세요.

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

시작하기

연동 가이드

상품·콘텐츠 데이터 연동

데이터 준비와 식별자

등록과 조회

등록

조회

변경 사항 반영

수정

ID 변경

일괄 연동

행동 데이터 연결과 검증

​데이터 준비와 식별자

​등록과 조회

​등록

​조회

​변경 사항 반영

​수정

​ID 변경

​일괄 연동

​행동 데이터 연결과 검증

데이터 준비와 식별자

등록과 조회

등록

조회

변경 사항 반영

수정

ID 변경

일괄 연동

행동 데이터 연결과 검증