> 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/pt-br/bulk-operation-api/bulk-operation-overview.md). # Visão geral das Operações em Massa ## Campanhas em lote As APIs de ação em lote foram projetadas para ajudar usuários como AdOps, Serviços Gerenciados e Fornecedores a realizar operações de criação e atualização em grande escala em **campanhas**, **carteiras** e **equipes** em uma única chamada de API. Essa abordagem de API assíncrona otimiza os fluxos de trabalho, reduz o esforço manual e aumenta a eficiência operacional. Essas APIs são especialmente valiosas para cenários de grande volume, como integração, lançamentos sazonais ou grandes ajustes de campanha, onde fazer chamadas de API individuais consumiria muito tempo e seria propenso a erros. ### Principais benefícios * Eficiência: Reduz o número de chamadas de API e elimina etapas manuais desnecessárias ao permitir múltiplas operações em uma única solicitação. * Desempenho: As APIs em lote minimizam a sobrecarga de idas e voltas (round-trip) do HTTP. Em vez de enviar muitas solicitações individuais (por exemplo, 100 chamadas separadas), uma única solicitação em lote reduz a carga da rede e diminui as chances de atingir os limites de taxa (rate limits). * Idempotência: Garante que cada operação na solicitação em lote seja idempotente, evitando efeitos colaterais indesejados durante novas tentativas (como aquelas disparadas por ações da interface do usuário). * Modelo de autorização e segurança granular: Aplica os controles de acesso corretos para cada operação e tipo de entidade dentro do payload em lote, garantindo a manipulação segura de todas as ações. * Auditoria e log: Mantém logs e trilhas de auditoria adequados para todas as operações dentro de uma solicitação em lote, garantindo a rastreabilidade. * Capacidade de visualização prévia: Algumas implementações suportam a visualização prévia das alterações antes de aplicá-las, ajudando a identificar erros antecipadamente. * Integridade transacional: Uma API em lote permite que os clientes agrupem um conjunto de ações em uma única chamada de API, o que pode garantir que: * Cada entidade na solicitação em lote seja validada independentemente. * Mensagens de erro granulares sejam retornadas para identificar quais entidades falharam e o motivo. * A operação inteira não seja bloqueada se uma entidade falhar. ### Como usar as APIs de campanhas em lote #### 1. Enviar uma solicitação em lote Você envia uma solicitação para criar, editar ou aprovar várias campanhas de uma só vez. * Para criação: `/v3/campaigns/bulk/create` * Para edição: `/v3/campaigns/bulk/update` * Para aprovações: `/v3/campaigns/bulk/approve` Assim que você envia a solicitação, o sistema fornece um ID de lote e um status como `submitted`. O processamento real ocorre em segundo plano. **Exemplo (Atualizar campanhas em lote):** ```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" } ] } ``` Resposta: ```json { "bulkId": "c40f4f98-9b6b-11ee-b9d1-0242ac120002", "status": "BULK_OPERATION_SUBMITTED", "message": "Bulk campaign update request received and is being processed." } ``` #### 2. Verificar o status Use o ID de lote para verificar o progresso em: `/v3/campaigns/bulk/status/{bulkId}` Você verá: * Quais campanhas tiveram sucesso ou falharam, com detalhes para cada uma. * Mensagens de erro (se houver). **Exemplo:** ```http GET /v3/campaigns/bulk/status/c40f4f98-9b6b-11ee-b9d1-0242ac120002 ``` {% hint style="info" %} Observações: * As APIs são assíncronas: você envia uma tarefa e faz polling para obter os resultados. * Cada entidade na solicitação em lote é validada independentemente; os erros são relatados por item. * As APIs em lote estão disponíveis para campanhas, carteiras e equipes, com padrões semelhantes para cada recurso. {% endhint %} ### Matriz de acesso a operações em lote | Operação | Método | Quem pode criar | Quem pode ver o status | | ------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ------------------------------------------------------------- | ------------------------------------------------------------------ | | Campanhas | | | | | [Create campaigns in bulk](/retail-media-interface/partner/pt-br/bulk-operation-api/bulkcampaignoperations/bulkcreatecampaign.md) | POST | Administrador, Varejista principal, Fornecedor, Usuário geral | Administrador, Varejista principal, Criador (incluindo Fornecedor) | | [Update campaigns in bulk](/retail-media-interface/partner/pt-br/bulk-operation-api/bulkcampaignoperations/bulkupdatecampaign-1.md) | PATCH | Administrador, Varejista principal, Fornecedor, Usuário geral | Administrador, Varejista principal, Criador (incluindo Fornecedor) | | [Update campaign approval state](/retail-media-interface/partner/pt-br/bulk-operation-api/bulkcampaignoperations/bulkcampaignapproval.md) | POST | Administrador, Varejista principal | Administrador, Varejista principal | | [Retrieve bulk operation status](/retail-media-interface/partner/pt-br/bulk-operation-api/bulkcampaignoperations/bulkcampaignstatus-1.md) | GET | — | Administrador, Varejista principal, Criador (incluindo Fornecedor) | | Carteira | | | | | [Create wallets in bulk](/retail-media-interface/partner/pt-br/bulk-operation-api/bulkwalletoperations/bulkcreatewallet.md) | POST | Administrador, Varejista principal, Fornecedor, Usuário geral | Administrador, Varejista principal, Criador (incluindo Fornecedor) | | [Update wallets in bulk](/retail-media-interface/partner/pt-br/bulk-operation-api/bulkwalletoperations/bulkupdatewallet.md) | PATCH | Administrador, Varejista principal, Fornecedor, Usuário geral | Administrador, Varejista principal, Criador (incluindo Fornecedor) | | [Retrieve bulk wallet operation status](/retail-media-interface/partner/pt-br/bulk-operation-api/bulkwalletoperations/bulkwalletstatus.md) | GET | — | Administrador, Varejista principal, Criador (incluindo Fornecedor) | | Equipe | | | | | [Create teams in bulk](/retail-media-interface/partner/pt-br/bulk-operation-api/bulkwalletoperations-1/bulkcreateteam.md) | POST | Administrador, Varejista principal, Fornecedor, Usuário geral | Administrador, Varejista principal, Criador (incluindo Fornecedor) | | [Update teams in bulk](/retail-media-interface/partner/pt-br/bulk-operation-api/bulkwalletoperations-1/bulkupdateteam.md) | PATCH | Administrador, Varejista principal, Fornecedor, Usuário geral | Administrador, Varejista principal, Criador (incluindo Fornecedor) | | [Retrieve bulk team operation status](/retail-media-interface/partner/pt-br/bulk-operation-api/bulkwalletoperations-1/bulkteamstatus.md) | GET | — | Administrador, Varejista principal, Criador (incluindo Fornecedor) | {% hint style="info" %} Criar e atualizar equipes em lote: Quando um fornecedor tenta atualizar registros em lote, a API permite um máximo de 50 registros por solicitação. Se a solicitação contiver mais de 50 registros, a API retornará uma mensagem de erro indicando que o limite foi excedido. {% 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/pt-br/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.