> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/partner/ko/bulk-operation-api/bulk-operation-overview.md). # 일괄 작업 개요 ## 대량 캠페인 대량 작업 API는 AdOps, 매니지드 서비스 및 공급업체와 같은 사용자가 단일 API 호출로 **캠페인**, **지갑** 및 **팀**에 대한 대규모 업데이트 및 생성 작업을 수행할 수 있도록 지원하도록 설계되었습니다. 이 비동기 API 방식은 워크플로를 간소화하고 수작업을 줄이며 운영 효율성을 향상시킵니다. 이러한 API는 개별 API를 호출할 경우 시간이 많이 걸리고 오류가 발생하기 쉬운 온보딩, 시즌 출시 또는 주요 캠페인 조정과 같은 대용량 시나리오에 특히 유용합니다. ### 주요 혜택 * 효율성: 단일 요청으로 여러 작업을 수행할 수 있도록 하여 API 호출 횟수를 줄이고 불필요한 수작업 단계를 제거합니다. * 성능: 대량 API는 HTTP 라운드트립 오버헤드를 최소화합니다. 개별 요청을 여러 번 보내는 대신(예: 100개의 별도 호출) 단일 대량 요청을 통해 네트워크 부하를 줄이고 속도 제한(rate limit)에 도달할 가능성을 낮춥니다. * 멱등성: 대량 요청의 각 작업이 멱등성을 보장하도록 하여 재시도(UI 작업에 의해 트리거된 재시도 등) 중에 의도치 않은 부작용이 발생하는 것을 방지합니다. * 세분화된 보안 및 권한 부여 모델: 대량 페이로드 내의 각 작업 및 엔티티 유형에 대해 올바른 액세스 제어를 적용하여 모든 작업을 안전하게 처리합니다. * 감사 및 로깅: 대량 요청 내 모든 작업에 대한 적절한 로깅 및 감사 추적을 유지하여 추적 가능성을 보장합니다. * 미리보기 기능: 일부 구현에서는 변경 사항을 적용하기 전에 미리보는 기능을 지원하므로 오류를 조기에 파악하는 데 도움이 됩니다. * 트랜잭션 무결성: 대량 API를 사용하면 클라이언트가 여러 작업을 단일 API 호출로 묶을 수 있으며, 이를 통해 다음을 보장할 수 있습니다. * 대량 요청의 각 엔티티는 개별적으로 검증됩니다. * 어떤 엔티티가 왜 실패했는지 식별할 수 있도록 세분화된 오류 메시지가 반환됩니다. * 하나의 엔티티가 실패하더라도 전체 작업이 차단되지 않습니다. ### 대량 캠페인 API 사용 방법 #### 1. 대량 요청 제출 여러 캠페인을 한 번에 생성, 수정 또는 승인하는 요청을 보냅니다. * 생성 시: `/v3/campaigns/bulk/create` * 수정 시: `/v3/campaigns/bulk/update` * 승인 시: `/v3/campaigns/bulk/approve` 요청을 보내면 시스템에서 대량 ID와 함께 다음과 같은 상태를 제공합니다: `submitted`. 실제 처리는 백그라운드에서 진행됩니다. **예시(캠페인 대량 업데이트):** ```http PATCH /v3/campaigns/bulk/update { "campaigns": [ { "campaign": { "id": "campaign_123", "name": "Updated Summer Sale Campaign", "startTime": "2025-08-01T00:00:00Z", "endTime": "2025-08-31T23:59:59Z", "campaignState": "CAMPAIGN_STATE_ACTIVE", "strategy": { "auction": { "maxBid": "6.5" } } }, "mask": "name,startTime,endTime,campaignState,strategy.auction.maxBid", "campaignType": "CAMPAIGN_TYPE_BANNER" }, { "campaign": { "id": "campaign_456", "name": "Holiday Promotion", "campaignState": "CAMPAIGN_STATE_PAUSED", "strategy": { "auction": { "maxBid": "5.0" } } }, "mask": "name,campaignState,strategy.auction.maxBid", "campaignType": "CAMPAIGN_TYPE_BANNER" } ] } ``` 응답: ```json { "bulkId": "c40f4f98-9b6b-11ee-b9d1-0242ac120002", "status": "BULK_OPERATION_SUBMITTED", "message": "Bulk campaign update request received and is being processed." } ``` #### 2. 상태 확인 대량 ID를 사용하여 진행 상황을 확인합니다: `/v3/campaigns/bulk/status/{bulkId}` 다음과 같은 내용을 확인할 수 있습니다: * 성공하거나 실패한 캠페인과 각 캠페인에 대한 세부 정보. * 오류 메시지(있는 경우). **예시:** ```http GET /v3/campaigns/bulk/status/c40f4f98-9b6b-11ee-b9d1-0242ac120002 ``` {% hint style="info" %} 참고사항: * API는 비동기식입니다. 작업을 제출하고 결과를 폴링합니다. * 대량 요청의 각 엔티티는 개별적으로 검증되며, 오류는 항목별로 보고됩니다. * 대량 API는 캠페인, 지갑 및 팀에 대해 제공되며 각 리소스에 대해 유사한 패턴을 가집니다. {% endhint %} ### 대량 작업 액세스 매트릭스 | 작업 | 메서드 | 생성 가능 권한 | 상태 조회 가능 권한 | | --------------------------------------------------------------------------------------------------------------------------------------- | ----- | ----------------------------------------------- | ---------------------------------------------- | | 캠페인 | | | | | [Create campaigns in bulk](/retail-media-interface/partner/ko/bulk-operation-api/bulkcampaignoperations/bulkcreatecampaign.md) | POST | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (Supplier 포함) | | [Update campaigns in bulk](/retail-media-interface/partner/ko/bulk-operation-api/bulkcampaignoperations/bulkupdatecampaign-1.md) | PATCH | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (Supplier 포함) | | [Update campaign approval state](/retail-media-interface/partner/ko/bulk-operation-api/bulkcampaignoperations/bulkcampaignapproval.md) | POST | Admin, Primary Retailer | Admin, Primary Retailer | | [Retrieve bulk operation status](/retail-media-interface/partner/ko/bulk-operation-api/bulkcampaignoperations/bulkcampaignstatus-1.md) | GET | — | Admin, Primary Retailer, Creator (Supplier 포함) | | 지갑 | | | | | [Create wallets in bulk](/retail-media-interface/partner/ko/bulk-operation-api/bulkwalletoperations/bulkcreatewallet.md) | POST | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (Supplier 포함) | | [Update wallets in bulk](/retail-media-interface/partner/ko/bulk-operation-api/bulkwalletoperations/bulkupdatewallet.md) | PATCH | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (Supplier 포함) | | [Retrieve bulk wallet operation status](/retail-media-interface/partner/ko/bulk-operation-api/bulkwalletoperations/bulkwalletstatus.md) | GET | — | Admin, Primary Retailer, Creator (Supplier 포함) | | 팀 | | | | | [Create teams in bulk](/retail-media-interface/partner/ko/bulk-operation-api/bulkwalletoperations-1/bulkcreateteam.md) | POST | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (Supplier 포함) | | [Update teams in bulk](/retail-media-interface/partner/ko/bulk-operation-api/bulkwalletoperations-1/bulkupdateteam.md) | PATCH | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (Supplier 포함) | | [Retrieve bulk team operation status](/retail-media-interface/partner/ko/bulk-operation-api/bulkwalletoperations-1/bulkteamstatus.md) | GET | — | Admin, Primary Retailer, Creator (Supplier 포함) | {% hint style="info" %} 팀 대량 생성 및 업데이트: 공급업체가 레코드를 대량으로 업데이트하려고 할 때 API는 요청당 최대 50개의 레코드를 허용합니다. 요청에 50개 이상의 레코드가 포함된 경우 API는 제한이 초과되었음을 나타내는 오류 메시지를 반환합니다. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.citrusad.com/retail-media-interface/partner/ko/bulk-operation-api/bulk-operation-overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.