> ## 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. # 카탈로그 항목 일괄 생성 > 한 번의 요청으로 최대 1,000개 항목을 생성하며, 각 항목은 `POST /catalogs`와 같은 방식으로 검증됩니다. 각 항목은 개별적으로 성공하거나 실패하고 응답은 어느 경우든 200이므로, 항상 `failed`를 확인하세요. 이미 존재하는 `id`이거나 `metadata`가 `schema`와 일치하지 않는 항목은 사유와 함께 `failed`에 담기고 나머지 항목은 생성됩니다. 실패한 항목만 수정해서 다시 보내면 됩니다. 요청 스키마 검증에 실패하면 항목을 처리하기 전에 요청 전체가 422로 거부됩니다. 예를 들어 항목이 1,000개를 넘거나, 필수 필드가 빠졌거나, `status` 또는 `schema` 값이 유효하지 않거나, ID가 문자열이 아니거나, `metadata`가 객체가 아닌 경우입니다. 이 검증을 통과한 뒤 발생하는 항목별 실패는 `failed`에 담깁니다. ## OpenAPI ````yaml /openapi/adm.openapi.ko-dev.json post /api/manager/catalogs/batch-create openapi: 3.1.0 info: description: >- ## 소개 Data Management API는 광고 및 추천 시스템이 활용하는 **다양한 데이터를** 종합적으로 관리해, Decision API가 정확하고 효율적으로 작동할 수 있도록 돕습니다. 캠페인이나 지면을 신규 등록하고 수정·삭제하는 것은 물론, **로그 및 통계 분석을** 통해 시스템 운영에 필요한 인사이트를 확보합니다. 이렇게 확보된 데이터와 통계는 Decision API에서 최적화된 광고·콘텐츠를 결정하는 데 활용되며, 전체 광고·추천 시스템의 성능 향상에 이바지합니다. title: 데이터 관리 API version: dev servers: [] security: [] tags: - description: 인증 엔드포인트. 모든 역할(admin/operator/advertiser)이 로그인·토큰 갱신·본인 자격 증명 관리에 사용합니다. name: 인증 - description: >- 광고주 계정 관리. 운영자·관리자가 광고주를 온보딩하고 예산을 관리하며 계정을 비활성화합니다. 광고주는 본인 프로필과 잔액만 조회할 수 있습니다. name: 광고주 - description: >- 내부 사용자(운영자/관리자) 계정 관리. 관리자 전용. 운영자 계정 생성, 역할 변경, 활성화 상태 토글, 계정 영구 삭제를 다룹니다. name: 사용자 - description: >- 광고 단위 관리. 광고 단위와 관련 리소스를 관리합니다. 광고 단위는 code와 상위 경로에서 파생된 계층 경로 구조로 구성됩니다. admin·operator만 접근 가능하며 광고주는 원천 인벤토리에 접근할 수 없습니다. name: 광고 단위 - description: 광고 카탈로그 관리. 광고 카탈로그 CRUD와 공유 링크를 통한 공개 조회를 제공합니다. name: 광고 카탈로그 - description: 수요 파트너(광고 소스) 관리. 광고 단위에 수요를 공급하는 외부 광고 소스를 CRUD합니다. name: 수요 파트너 - description: 게재 할당 관리. 광고 항목을 광고 단위 등 게재 대상에 연결합니다. CRUD, 상태별 카운트, 단건 조회를 제공합니다. name: 게재 할당 - description: 연관 상품 풀(관리자). 추천 파이프라인에서 사용하는 연관 상품 풀의 일괄 저장/삭제 및 조회. name: 연관 상품 풀 - description: 커스텀 타게팅 세그먼트 관리. 커스텀 타게팅 세그먼트의 CRUD 및 일괄 작업. name: 커스텀 타게팅 세그먼트 - description: 감사 로그 조회. 관리 작업에 대한 시스템 감사 로그를 조회합니다. name: 감사 로그 - description: 소재 차단 목록. 소재를 차단/차단 해제해 게재에서 제외합니다. name: 차단 소재 - description: 카탈로그 항목 관리. 상품/데이터 카탈로그 항목을 조회·수정합니다. name: 카탈로그 - description: 광고 소재 관리. 운영자·관리자가 소재를 관리하며 광고주는 본인 소재만 조회합니다. 연결된 LICA가 있으면 삭제가 차단됩니다. name: 소재 - description: 대시보드 집계. 콘솔 대시보드용 요약·인벤토리·광고 항목 지표 롤업. name: 대시보드 - description: 실험 관리. A/B·최적화 실험의 CRUD. name: 실험 - description: 외부 소재 조회. 외부 수요 소스에서 수집된 소재를 읽기 전용으로 조회합니다. name: 외부 소재 - description: 외부 연동 관리. 연동 소스(외부 데이터/서빙 커넥터)를 관리하고 연결을 테스트하며, 민감 설정이 마스킹된 공개 설정을 조회합니다. name: 연동 - description: >- 소재-광고 항목 연결(LICA). 소재를 광고 항목에 연결하며, 일괄 생성/삭제(최대 100, 부분 실패 허용)와 대시보드 카운트를 제공합니다. name: 소재-광고 항목 연결(LICA) - description: 라이선스 정보. 사용 가능한 라이선스 기능과 사용량 지표를 조회합니다. name: 라이선스 - description: >- 광고 항목 관리. 생성·수정·삭제, 일괄 작업(최대 100, 부분 실패 허용), 상태 전환을 다룹니다. 광고 항목은 상위 주문 아래에서 예산·목표·일정·타게팅을 정의합니다. name: 광고 항목 - description: 미디어 라이브러리. 소재에 쓰이는 미디어 파일을 조회·업로드·삭제합니다. name: 미디어 라이브러리 - description: 지표 조회 엔드포인트. 광고 단위·소재·광고 항목 등 엔티티의 집계 지표를 조회합니다. name: 지표 - description: >- 주문 관리. 운영자·관리자가 예산 단위로 광고 항목을 묶는 주문을 생성·관리하며, 광고주는 본인 주문을 조회합니다. 일괄 작업(최대 100)과 draft 상태 삭제 규칙을 포함합니다. name: 주문 - description: 게재 위치 관리. 게재 위치는 광고 단위를 게재 표면에 매핑합니다. CRUD와 게재 위치에 연결된 광고 단위 교체를 제공합니다. name: 게재 위치 - description: 시스템 설정. 사이트 로고·Public URL·TLS·액세스 토큰 재생성을 포함한 시스템 구성을 조회·수정합니다. name: 설정 - description: 시스템 리소스. 사이트 로고 등 공개 정적 리소스. name: 시스템 - description: 개발자/운영용 제어 엔드포인트. 저수준 ext 변경과 헬스 체크. 일반 API 소비자가 아닌 내부 운영용입니다. name: 개발자/운영 - description: 운영용 게재 할당 제어. 게재 할당 ext/상태 강제 변경(관리자 전용). name: 개발자/게재 할당 제어 - description: 광고 서빙 모니터링(운영). 광고 서빙 현황·광고 단위 모니터링 이력·알림을 조회합니다. name: 개발자/모니터링 - description: 내부 헬스/프로브 엔드포인트. name: 내부 - description: '특정 리소스에 속하지 않는 매니저 공통 유틸리티 엔드포인트(예: 서비스 헬스).' name: 매니저(공통) - description: 광고 단위, 네이티브 포맷 및 네이티브 스타일 간의 매핑을 관리합니다. name: Ad Unit Native Style - description: 커스텀 타게팅 키와 활성화 상태를 관리하고 일괄 작업을 수행합니다. name: Custom Targeting Key - description: 커스텀 타게팅 키에 속한 값과 활성화 상태를 관리하고 일괄 작업을 수행합니다. name: Custom Targeting Value - description: 네이티브 포맷과 각 포맷을 구성하는 필드를 관리합니다. name: Native Format - description: 네이티브 스타일에 사용할 수 있는 템플릿을 조회합니다. name: Native Style Template - description: 네이티브 렌더링 스타일을 관리합니다. name: Native Style paths: /api/manager/catalogs/batch-create: post: tags: - 카탈로그 summary: 카탈로그 항목 일괄 생성 description: >- 한 번의 요청으로 최대 1,000개 항목을 생성하며, 각 항목은 `POST /catalogs`와 같은 방식으로 검증됩니다. 각 항목은 개별적으로 성공하거나 실패하고 응답은 어느 경우든 200이므로, 항상 `failed`를 확인하세요. 이미 존재하는 `id`이거나 `metadata`가 `schema`와 일치하지 않는 항목은 사유와 함께 `failed`에 담기고 나머지 항목은 생성됩니다. 실패한 항목만 수정해서 다시 보내면 됩니다. 요청 스키마 검증에 실패하면 항목을 처리하기 전에 요청 전체가 422로 거부됩니다. 예를 들어 항목이 1,000개를 넘거나, 필수 필드가 빠졌거나, `status` 또는 `schema` 값이 유효하지 않거나, ID가 문자열이 아니거나, `metadata`가 객체가 아닌 경우입니다. 이 검증을 통과한 뒤 발생하는 항목별 실패는 `failed`에 담깁니다. operationId: handle_batch_create_catalogs_api_manager_catalogs_batch_create_post requestBody: content: application/json: schema: $ref: '#/components/schemas/CatalogBatchCreate' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/CatalogBatchCreateResponse' description: '항목별 결과: 생성된 항목과 실패한 항목.' '403': content: application/json: schema: $ref: '#/components/schemas/HTTPExceptionResponse' description: 권한 없음 '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: 유효성 검사 오류 security: - HTTPBearer: [] components: schemas: CatalogBatchCreate: example: items: - id: '1001' metadata: brand: brand1 ext: price: 25000 id: '1001' title: product1 schema: creative.catalog source: manual status: active - id: '1002' metadata: brand: brand1 ext: price: 18000 id: '1002' title: product2 schema: creative.catalog source: manual status: active properties: items: description: 생성할 항목 목록. 각 항목은 `POST /catalogs` 요청 본문과 같은 형태이며, 최대 1,000개입니다. items: $ref: '#/components/schemas/CatalogCreate' maxItems: 1000 title: Items type: array required: - items title: CatalogBatchCreate type: object CatalogBatchCreateResponse: example: failed: - id: '1002' reason: Already exists. succeeded: - created_at: '2026-10-20T00:00:00Z' id: '1001' metadata: brand: brand1 ext: price: 25000 id: '1001' title: product1 schema: creative.catalog source: manual status: active updated_at: '2026-10-20T00:00:00Z' properties: failed: description: 생성되지 않은 항목과 그 사유. items: $ref: '#/components/schemas/CatalogBatchFailedItem' title: Failed type: array succeeded: description: 생성된 항목. items: $ref: '#/components/schemas/CatalogResponse' title: Succeeded type: array required: - succeeded - failed title: CatalogBatchCreateResponse type: object HTTPExceptionResponse: properties: detail: description: 오류에 대한 상세 설명 title: Detail type: string required: - detail title: HTTPExceptionResponse type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object CatalogCreate: description: |- 카탈로그 항목 생성 요청 스키마. `metadata`는 `schema`가 지정한 형태를 만족해야 합니다. example: id: '1001' metadata: brand: brand1 ext: price: 25000 id: '1001' title: product1 schema: creative.catalog source: manual status: active properties: id: description: 항목 ID. 숫자여도 문자열로 보냅니다(`1001`이 아니라 `"1001"`). title: Id type: string metadata: anyOf: - additionalProperties: false properties: brand: anyOf: - type: string - type: 'null' description: 항목의 브랜드. title: Brand category: anyOf: - type: string - type: 'null' description: 항목이 속한 카테고리. title: Category created_at: anyOf: - format: date-time type: string - type: 'null' description: 항목 생성 일시. title: Created At ext: anyOf: - {} - type: 'null' description: 표준 필드에 없는 값을 담는 사이트별 확장 영역. title: Ext id: description: 항목 식별자. `catalogs.id`와 같아야 합니다. title: Id type: string link: anyOf: - type: string - type: 'null' description: 항목 상세 페이지 URL. title: Link seller_name: anyOf: - type: string - type: 'null' description: 항목의 판매자. title: Seller Name thumbnail: anyOf: - type: string - type: 'null' description: 대표 이미지 URL. title: Thumbnail title: description: 항목 제목. title: Title type: string updated_at: anyOf: - format: date-time type: string - type: 'null' description: 항목 수정 일시. title: Updated At required: - id - title title: creative.catalog type: object - additionalProperties: false properties: author: anyOf: - type: string - type: 'null' description: 작품의 작가. title: Author catch_copy: anyOf: - type: string - type: 'null' description: 한 줄 홍보 문구. title: Catch Copy category: anyOf: - type: string - type: 'null' description: 작품이 속한 카테고리. title: Category created_at: anyOf: - format: date-time type: string - type: 'null' description: 작품 생성 일시. title: Created At description: anyOf: - type: string - type: 'null' description: 작품 설명. title: Description end_date: anyOf: - format: date-time type: string - type: 'null' description: 작품 노출 종료 일시. title: End Date exclusion_tags: anyOf: - items: type: string type: array - type: 'null' description: 작품을 제외할 때 쓰는 태그. title: Exclusion Tags ext: anyOf: - {} - type: 'null' description: 표준 필드에 없는 값을 담는 사이트별 확장 영역. title: Ext id: description: 작품 식별자. `catalogs.id`와 같아야 합니다. title: Id type: string link: anyOf: - type: string - type: 'null' description: 작품 상세 페이지 URL. title: Link rating: anyOf: - type: integer - type: 'null' description: '등급. 예: 연령 등급.' title: Rating start_date: anyOf: - format: date-time type: string - type: 'null' description: 작품 노출 시작 일시. title: Start Date tags: anyOf: - items: type: string type: array - type: 'null' description: 노출과 분류에 쓰는 태그. title: Tags thumbnail: description: 대표 이미지 URL. title: Thumbnail type: string title: description: 작품 제목. title: Title type: string updated_at: anyOf: - format: date-time type: string - type: 'null' description: 작품 수정 일시. title: Updated At required: - id - thumbnail - title title: webtoon type: object description: >- `schema` 값이 지정하는 형태의 항목 속성입니다. 그 값을 제목으로 가진 형태를 사용하세요. `metadata.id`는 `id`와 같아야 하며, 목록에 없는 값은 `ext`에 넣습니다. title: Metadata schema: $ref: '#/components/schemas/CatalogSchema' source: anyOf: - type: string - type: 'null' title: Source status: $ref: '#/components/schemas/CatalogStatus' required: - id - status - schema - metadata title: CatalogCreate type: object CatalogBatchFailedItem: description: 일괄 처리에서 반영되지 않은 항목과 그 사유. properties: id: description: 카탈로그 항목 ID. title: Id type: string reason: description: '실패 사유. 예: `Already exists.`, `Invalid value.`, `Not found.`' title: Reason type: string required: - id - reason title: CatalogBatchFailedItem type: object CatalogResponse: description: 카탈로그 항목 응답 스키마. example: created_at: '2026-10-20T00:00:00Z' id: '1001' metadata: brand: brand1 ext: price: 25000 id: '1001' title: product1 schema: creative.catalog source: manual status: active updated_at: '2026-10-20T00:00:00Z' properties: created_at: anyOf: - format: date-time type: string - type: 'null' title: Created At id: title: Id type: string metadata: anyOf: - properties: brand: anyOf: - type: string - type: 'null' description: 항목의 브랜드. title: Brand category: anyOf: - type: string - type: 'null' description: 항목이 속한 카테고리. title: Category created_at: anyOf: - format: date-time type: string - type: 'null' description: 항목 생성 일시. title: Created At ext: anyOf: - {} - type: 'null' description: 표준 필드에 없는 값을 담는 사이트별 확장 영역. title: Ext id: description: 항목 식별자. `catalogs.id`와 같아야 합니다. title: Id type: string link: anyOf: - type: string - type: 'null' description: 항목 상세 페이지 URL. title: Link seller_name: anyOf: - type: string - type: 'null' description: 항목의 판매자. title: Seller Name thumbnail: anyOf: - type: string - type: 'null' description: 대표 이미지 URL. title: Thumbnail title: description: 항목 제목. title: Title type: string updated_at: anyOf: - format: date-time type: string - type: 'null' description: 항목 수정 일시. title: Updated At required: - id - title title: creative.catalog type: object - properties: author: anyOf: - type: string - type: 'null' description: 작품의 작가. title: Author catch_copy: anyOf: - type: string - type: 'null' description: 한 줄 홍보 문구. title: Catch Copy category: anyOf: - type: string - type: 'null' description: 작품이 속한 카테고리. title: Category created_at: anyOf: - format: date-time type: string - type: 'null' description: 작품 생성 일시. title: Created At description: anyOf: - type: string - type: 'null' description: 작품 설명. title: Description end_date: anyOf: - format: date-time type: string - type: 'null' description: 작품 노출 종료 일시. title: End Date exclusion_tags: anyOf: - items: type: string type: array - type: 'null' description: 작품을 제외할 때 쓰는 태그. title: Exclusion Tags ext: anyOf: - {} - type: 'null' description: 표준 필드에 없는 값을 담는 사이트별 확장 영역. title: Ext id: description: 작품 식별자. `catalogs.id`와 같아야 합니다. title: Id type: string link: anyOf: - type: string - type: 'null' description: 작품 상세 페이지 URL. title: Link rating: anyOf: - type: integer - type: 'null' description: '등급. 예: 연령 등급.' title: Rating start_date: anyOf: - format: date-time type: string - type: 'null' description: 작품 노출 시작 일시. title: Start Date tags: anyOf: - items: type: string type: array - type: 'null' description: 노출과 분류에 쓰는 태그. title: Tags thumbnail: description: 대표 이미지 URL. title: Thumbnail type: string title: description: 작품 제목. title: Title type: string updated_at: anyOf: - format: date-time type: string - type: 'null' description: 작품 수정 일시. title: Updated At required: - id - thumbnail - title title: webtoon type: object description: '`schema` 값이 지정하는 형태의 항목 속성입니다. 그 값을 제목으로 가진 형태로 읽으면 됩니다.' title: Metadata schema: title: Schema type: string source: anyOf: - type: string - type: 'null' title: Source status: $ref: '#/components/schemas/CatalogStatus' updated_at: anyOf: - format: date-time type: string - type: 'null' title: Updated At required: - id - status - schema - metadata title: CatalogResponse type: object ValidationError: properties: loc: items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: ValidationError type: object CatalogSchema: enum: - creative.catalog - webtoon title: CatalogSchema type: string CatalogStatus: enum: - active - inactive title: CatalogStatus type: string securitySchemes: HTTPBearer: description: 'Bearer 인증. 액세스 토큰을 `Authorization: Bearer ` 헤더로 전달합니다.' scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.