> 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/it/bulk-operation-api/bulk-operation-overview.md). # Panoramica sulle operazioni in blocco ## Campagne in blocco Le API di azione in blocco sono progettate per aiutare utenti come AdOps, Managed Services e fornitori a eseguire operazioni di creazione e aggiornamento su larga scala di **campagne**, **wallet** e **team** in un'unica chiamata API. Questo approccio basato su API asincrone semplifica i flussi di lavoro, riduce lo sforzo manuale e migliora l'efficienza operativa. Queste API sono particolarmente utili per scenari ad alto volume come l'onboarding, i lanci stagionali o le modifiche importanti alle campagne, in cui l'esecuzione di singole chiamate API richiederebbe molto tempo e sarebbe soggetta a errori. ### Vantaggi principali * Efficienza: riduce il numero di chiamate API e rimuove i passaggi manuali non necessari consentendo più operazioni in una singola richiesta. * Prestazioni: le API in blocco riducono al minimo l'overhead dei round-trip HTTP. Invece di inviare molte singole richieste (ad esempio, 100 chiamate separate), un'unica richiesta in blocco riduce il carico di rete e abbassa le probabilità di raggiungere i limiti di frequenza (rate limit). * Idempotenza: garantisce che ciascuna operazione nella richiesta in blocco sia idempotente, prevenendo effetti collaterali indesiderati durante i tentativi di rinvio (come quelli attivati dalle azioni dell'interfaccia utente). * Modello di autorizzazione e sicurezza granulare: applica i controlli di accesso corretti per ciascuna operazione e tipo di entità all'interno del payload in blocco, garantendo una gestione sicura di tutte le azioni. * Audit e registrazione: mantiene un tracciamento di audit e una registrazione adeguati per tutte le operazioni all'interno di una richiesta in blocco, garantendo la tracciabilità. * Capacità di anteprima: alcune implementazioni supportano l'anteprima delle modifiche prima di applicarle, aiutando a rilevare gli errori in anticipo. * Integrità transazionale: un'API in blocco consente ai clienti di raggruppare un insieme di azioni in un'unica chiamata API, il che può garantire che: * Ogni entità nella richiesta in blocco venga convalidata in modo indipendente. * Vengano restituiti messaggi di errore granulari per identificare quali entità non hanno avuto successo e perché. * L'intera operazione non venga bloccata se un'entità fallisce. ### Come utilizzare le API delle campagne in blocco #### 1. Inviare una richiesta in blocco Invii una richiesta per creare, modificare o approvare più campagne contemporaneamente. * Per la creazione: `/v3/campaigns/bulk/create` * Per la modifica: `/v3/campaigns/bulk/update` * Per le approvazioni: `/v3/campaigns/bulk/approve` Una volta inviata la richiesta, il sistema fornisce un ID del processo in blocco e uno stato come `submitted`. L'elaborazione effettiva avviene in background. **Esempio (Aggiornamento campagne in blocco):** ```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" } ] } ``` Risposta: ```json { "bulkId": "c40f4f98-9b6b-11ee-b9d1-0242ac120002", "status": "BULK_OPERATION_SUBMITTED", "message": "Bulk campaign update request received and is being processed." } ``` #### 2. Verificare lo stato Utilizzare l'ID del processo in blocco per verificare l'avanzamento su: `/v3/campaigns/bulk/status/{bulkId}` Visualizzerai: * Quali campagne hanno avuto successo o sono fallite, con dettagli per ciascuna. * Messaggi di errore (se presenti). **Esempio:** ```http GET /v3/campaigns/bulk/status/c40f4f98-9b6b-11ee-b9d1-0242ac120002 ``` {% hint style="info" %} Note: * Le API sono asincrone: invii un processo e verifichi periodicamente (poll) i risultati. * Ogni entità nella richiesta in blocco viene convalidata in modo indipendente; gli errori vengono segnalati per ciascun elemento. * Le API in blocco sono disponibili per campagne, wallet e team, con modelli simili per ciascuna risorsa. {% endhint %} ### Matrice di accesso alle operazioni in blocco | Operazione | Metodo | Chi può creare | Chi può visualizzare lo stato | | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------- | --------------------------------------------------- | | Campagne | | | | | [Crea campagne in blocco](/retail-media-interface/partner/it/bulk-operation-api/bulkcampaignoperations/bulkcreatecampaign.md) | POST | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (incluso Supplier) | | [Aggiorna campagne in blocco](/retail-media-interface/partner/it/bulk-operation-api/bulkcampaignoperations/bulkupdatecampaign-1.md) | PATCH | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (incluso Supplier) | | [Aggiorna lo stato di approvazione della campagna](/retail-media-interface/partner/it/bulk-operation-api/bulkcampaignoperations/bulkcampaignapproval.md) | POST | Admin, Primary Retailer | Admin, Primary Retailer | | [Recupera lo stato dell'operazione in blocco](/retail-media-interface/partner/it/bulk-operation-api/bulkcampaignoperations/bulkcampaignstatus-1.md) | GET | — | Admin, Primary Retailer, Creator (incluso Supplier) | | Wallet | | | | | [Crea wallet in blocco](/retail-media-interface/partner/it/bulk-operation-api/bulkwalletoperations/bulkcreatewallet.md) | POST | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (incluso Supplier) | | [Aggiorna wallet in blocco](/retail-media-interface/partner/it/bulk-operation-api/bulkwalletoperations/bulkupdatewallet.md) | PATCH | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (incluso Supplier) | | [Recupera lo stato dell'operazione di wallet in blocco](/retail-media-interface/partner/it/bulk-operation-api/bulkwalletoperations/bulkwalletstatus.md) | GET | — | Admin, Primary Retailer, Creator (incluso Supplier) | | Team | | | | | [Crea team in blocco](/retail-media-interface/partner/it/bulk-operation-api/bulkwalletoperations-1/bulkcreateteam.md) | POST | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (incluso Supplier) | | [Aggiorna team in blocco](/retail-media-interface/partner/it/bulk-operation-api/bulkwalletoperations-1/bulkupdateteam.md) | PATCH | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (incluso Supplier) | | [Recupera lo stato dell'operazione di team in blocco](/retail-media-interface/partner/it/bulk-operation-api/bulkwalletoperations-1/bulkteamstatus.md) | GET | — | Admin, Primary Retailer, Creator (incluso Supplier) | {% hint style="info" %} Creazione e aggiornamento del team in blocco: quando un fornitore tenta di aggiornare i record in blocco, l'API consente un massimo di 50 record per richiesta. Se la richiesta contiene più di 50 record, l'API restituisce un messaggio di errore che indica che il limite è stato superato. {% 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/it/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.