API di Epinium

Accesso: Impostazioni → API Keys

Epinium espone i tuoi dati tramite un'API REST così puoi leggerli dai tuoi strumenti: una dashboard tua, uno script di analisi o un assistente IA. Sono le stesse informazioni che vedi nell'app, con gli stessi numeri.

L'API legge i tuoi dati e scrive su Amazon e nei tuoi negozi: consulta catalogo, campagne e metriche, e ciò che c'è dentro i tuoi negozi Shopify e WooCommerce; crea e modifica campagne Sponsored Products e modifica quelle Sponsored Brands e Display; crea e modifica portafogli; crea, modifica, clona ed esegue workflow; crea, risolve e applica attività; e crea, modifica ed elimina prodotti e contenuti nei tuoi negozi Shopify e WooCommerce collegati. Il tuo catalogo Amazon cambia solo quando si applica un'attività approvata; quello dei tuoi negozi cambia direttamente, senza attività. Ogni area ha il suo permesso, e quelli di scrittura li concedi tu quando crei la chiave.

Vuoi usarla da un assistente IA?

Non serve programmare nulla. L'MCP di Epinium collega questi stessi dati a Claude e ad altri assistenti compatibili.

Generare un token

1. Vai su Impostazioni → API Keys
2. Clicca su Crea API key e dalle un nome che ti ricordi a cosa serve
3. Seleziona i permessi necessari
4. Copia la chiave e conservala in un posto sicuro
5. Usala nell'header Authorization di ogni richiesta

La chiave si mostra una sola volta

Il valore completo appare una volta sola alla creazione. Se la perdi non è recuperabile: bisogna revocarla e crearne un'altra.

Permessi

Ogni token porta i permessi che selezioni alla creazione. Concedi solo quelli che serve all'integrazione.

Permesso	Dà accesso a
catalog:read	Prodotti, brand, paesi e cluster, con le relative metriche: vendite, commissioni Amazon e margine, resi, stock e, per Vendor, recensioni
campaigns:read	Campagne, portafogli, ad group, target, product ads e termini di ricerca
workflows:read	I tuoi workflow, la loro configurazione e quali campagne raggiungono
connections:read	Le connessioni del tuo account: Amazon, Shopify e WooCommerce
tasks:read	Task di Epinium e i loro item
skills:read	Il catalogo di playbook di marketing validati di Epinium
platform:read	Ciò che c'è dentro i tuoi negozi Shopify e WooCommerce: prodotti, scorte, prezzi e il resto di ciò che espone ogni negozio, letto in diretta dalla sua API. Include il registro delle modifiche fatte in essi (/v1/platform-changes, 1 credito per riga restituita)
catalog:write	Creare, modificare ed eliminare cluster di keyword: il nome, le keyword positive e negative e i prodotti che raggruppano. Niente arriva su Amazon
campaigns:write	Creare e modificare campagne, portafogli, ad group, target e product ad su Amazon, e configurare cosa persegue l'ottimizzatore su ciascuna
platform:write	Creare, modificare ed eliminare prodotti e contenuti nei tuoi negozi Shopify e WooCommerce collegati, direttamente e senza revisione preventiva, per la stessa route con cui si consultano (POST /v1/platform-request): una mutation in Shopify, o un metodo diverso da GET in WooCommerce, con l'intestazione Idempotency-Key. Serve anche platform:read (il livello Modificare della schermata API Keys concede entrambi). Ogni modifica viene registrata per 12 mesi e costa quanto una consultazione: 5 crediti per chiamata più 1 per KB restituito
tasks:write	Creare task, approvare o rifiutare i loro suggerimenti, chiuderli e applicare ciò che è stato approvato
workflows:write	Creare, copiare, modificare, attivare, mettere in pausa, eliminare e ripristinare workflow, e lanciarli o simularli

Scrivere è dei piani Business e Master. In Free e Guru i token leggono: non si può creare una chiave né autorizzare un assistente con permessi di scrittura, e se passi a uno di questi piani, quelli che avevi già continuano a leggere ma le loro scritture vengono rifiutate con un 403.

Un token raggiunge tutte le connessioni del tuo account. Se sei un'agenzia, raggiunge le connessioni che ogni cliente ti ha condiviso accettando il tuo invito.

Se sei un'agenzia: scegli l'account a ogni chiamata

Un token di agenzia raggiunge più account, quindi ogni richiesta deve dire su quale opera. Con l'header Epinium-Account: <id dell'account>, oppure con il parametro account_id se chiami dal MCP.

/v1/me e /v1/accounts sono l'eccezione: rispondono senza scegliere un account, e sono proprio quelli che ti dicono quali account raggiungi e come si chiamano.

Scelto l'account, lo vedi per intero: i suoi prodotti e le sue campagne sono limitati alle connessioni che ti ha condiviso, e le sue risorse di account — workflow, task e cluster, che non dipendono da nessuna connessione — sono limitate all'account. Quello che è fuori dalla tua portata non viene filtrato in silenzio: un account_id a cui non sei stato invitato restituisce un errore esplicito, non una lista vuota.

Quali endpoint copre

Ogni risorsa ha un elenco, e la maggior parte permette anche di recuperare un elemento tramite il suo id. Le risorse di metriche hanno solo l'elenco: una riga aggregata su un intervallo di date non ha un identificatore proprio.

Catalogo — catalog:read

Endpoint	Cosa restituisce
/v1/products	I tuoi prodotti unificati
/v1/amazon-seller-products	La vista Seller Central di ogni prodotto, e la categoria del suo ranking con expand=salesRanks
/v1/amazon-vendor-products	La vista Vendor Central, la categoria del ranking con expand=salesRanks e le recensioni con expand=customerFeedback
/v1/amazon-advertising-products	La vista Advertising
/v1/seller-product-metrics	Vendite, sessioni, Buy Box, rank, commissioni Amazon, margine, resi, stock, B2B e giorni di copertura per prodotto
/v1/vendor-product-metrics	Vendite Vendor per prodotto, con manufacturing e sourcing, resi, sell-in con Amazon, inventario e giorni di copertura
/v1/product-brands	I tuoi brand
/v1/countries	Paesi e marketplace
/v1/clusters	I tuoi cluster di keyword; con catalog:write li crei e li modifichi anche

Advertising — campaigns:read

Endpoint	Cosa restituisce
/v1/campaigns	Le tue campagne Amazon Advertising
/v1/campaign-metrics	Spesa, vendite, ACOS e ROAS per campagna
/v1/portfolios	I tuoi portafogli e il tetto di budget che ciascuno impone alle sue campagne
/v1/adgroups	Gli ad group di ogni campagna
/v1/adgroup-metrics	Performance per ad group
/v1/targets	Keyword e target di prodotto
/v1/target-metrics	Performance per target, con la sua keyword e il tipo di corrispondenza
/v1/product-ads	Il collegamento tra un ad group e il prodotto che pubblicizza
/v1/product-ad-metrics	Performance per prodotto pubblicizzato, con il suo ASIN
/v1/search-terms	Le ricerche reali degli acquirenti
/v1/search-term-metrics	Performance per ricerca, con il testo e il target che l'ha intercettata
/v1/campaigns/{id}/optimization-history	Cosa ha cambiato l'automazione su una campagna, con l'effetto netto
/v1/advertising-changes	Tutto ciò che Epinium ha modificato su Amazon, da qualunque origine

Automazione — workflows:read

Endpoint	Cosa restituisce
/v1/workflows	I tuoi workflow, con la loro pianificazione e se sono attivi
/v1/workflows/{id}	La configurazione completa di uno: il suo diagramma e ogni variabile con il valore effettivo
/v1/workflows/{id}/campaigns	Quali campagne raggiunge davvero, e perché ognuna ci rientra
/v1/workflows/{id}/performance	La performance di quelle campagne, con il loro obiettivo accanto per poterla giudicare

Un workflow può essere pianificato ogni notte e non toccare nessuna campagna: /campaigns è ciò che lo rivela, e quando l'insieme torna vuoto ne dice il motivo.

Connessioni, task e skills

Endpoint	Permesso	Cosa restituisce
/v1/connections	connections:read	Le tue connessioni: Amazon, Shopify e WooCommerce
POST /v1/platform-request	platform:read, e platform:write per scrivere	Una query a uno dei tuoi negozi o, con platform:write, una modifica: GraphQL su Shopify, REST su WooCommerce
/v1/platform-request/docs/{platform}	platform:read	La versione dell'API di quella piattaforma, la sua documentazione di riferimento e i campi che ha il tuo negozio in questo momento
/v1/tasks	tasks:read	Task di Epinium
/v1/task-items	tasks:read	Gli item di ogni task
/v1/skills	skills:read	Il catalogo di playbook di marketing di Epinium

Il catalogo di skills è contenuto scritto da Epinium, non dati del tuo account: è lo stesso per tutti i clienti. Quali parti di ogni playbook ricevi dipende dal tuo piano.

Le query ai tuoi negozi non restituiscono dati personali: nomi, email, telefoni e indirizzi vengono rifiutati prima che la richiesta arrivi al negozio. Si pagano in base alla dimensione della risposta, come le modifiche. Queste due rotte non sono nel riferimento navigabile: di solito si usano dall'MCP di Epinium.

Esiste anche /v1/me, che indica quali permessi e quali account raggiunge il tuo token. È la prima chiamata utile per verificare che la chiave funzioni.

Tre regole per leggere i dati

Queste tre spiegano quasi tutti i dubbi di interpretazione:

• Gli importi sono testo, non numeri. "cost": "8.22" arriva come stringa di proposito, per non perdere precisione nella conversione a decimale binario.
• I rapporti sono in frazione, non in percentuale. Un ACOS del 90,83 % arriva come 0.908287. Moltiplica per 100 per mostrarlo.
• null non è 0. null significa che Amazon non ha riportato quel dato; 0 significa uno zero reale. Un acos a null è una campagna che ha speso senza vendere, non pubblicità gratis. E new_to_brand_sales arriva a null su Sponsored Products perché Amazon non lo misura per quel formato.

Redditività, stock e recensioni dei tuoi prodotti

Le metriche di prodotto non si fermano alle vendite: dicono anche quanto trattiene Amazon, quanto stock resta e cosa pensano gli acquirenti. Quattro cose prima di trarre conclusioni:

• Le commissioni e il margine Seller sono al netto dell'IVA, mentre sales la include dove si applica: non sottrarre le une dall'altro. margin_before_ads è ciò che resta dopo aver pagato Amazon, prima della pubblicità e del costo del prodotto: per il margine dopo la pubblicità, sottraigli la spesa di /v1/product-ad-metrics. Amazon imputa lo stoccaggio a un solo giorno del mese e i resi alla data del rimborso, quindi il margine si legge per mese, non per giorno.
• days_of_coverage sono i giorni che dura lo stock al ritmo del periodo: lo stock dell'ultimo giorno diviso per le unità medie giornaliere dell'intervallo richiesto. È null con qualsiasi granularità diversa da total, se il prodotto non ha venduto nulla o, quando si raggruppa, se group_by non include il paese. Con order_by=days_of_coverage&order=asc ottieni prima quelli che stanno per esaurirsi.
• In Vendor c'è anche il sell-in: le unità che hai confermato ad Amazon, quelle degli ordini di acquisto aperti, il fill rate e i tempi di consegna, oltre ai resi separati tra manufacturing e sourcing e alla salute dell'inventario.
• La categoria del ranking e le recensioni si chiedono al prodotto, non alle metriche. expand=salesRanks indica a quale categoria appartiene ogni posizione del Best Seller Rank, e in Vendor expand=customerFeedback restituisce i temi positivi e negativi delle recensioni e i motivi di reso della categoria. È la fotografia della settimana, con la tendenza di sei mesi calcolata da Amazon, non uno storico.

Totali dell'account, per periodo e per cluster

Per sapere quanto ha venduto l'account a settembre non serve paginare il catalogo e sommare: le sette risorse di metriche aggregano da sole.

• group_by somma tra entità. account dà il totale dell'account; country e connection suddividono per paese o per connessione, e si combinano ripetendo il parametro (group_by[]=connection&group_by[]=country). account non si combina con nient'altro. Le righe restano separate per valuta — gli importi non vengono mai convertiti — e, nella pubblicità, per tipo di annuncio (SP, SB, SD).
• granularity divide l'intervallo in periodi di calendario. Oltre a total e daily accetta weekly, monthly, quarterly e yearly, e ogni riga porta in date l'inizio del suo periodo: il lunedì della settimana o il primo giorno del mese, del trimestre o dell'anno. I periodi agli estremi sono parziali: dal 15 gennaio al 10 marzo con monthly restituisce gennaio dal 15 al 31, febbraio intero e marzo dall'1 al 10.
• cluster restringe a una famiglia di prodotti. Nelle metriche Seller, Vendor e di prodotto pubblicizzato, cluster=<id> lascia solo i prodotti di quel cluster; con più id, l'unione. Si combina con quanto sopra: group_by=account&granularity=monthly&cluster=<id> è la serie mensile di quella famiglia.
• group_by=cluster dà una riga per cluster. Nelle stesse tre metriche, group_by=cluster restituisce in una sola chiamata i dati di ciascuno dei tuoi cluster, con il suo id in cluster e il suo nome in cluster_name. Un prodotto presente in più cluster conta per intero in ognuno, quindi le righe non sommano il totale dell'account, e i prodotti senza cluster non compaiono. Si combina con country e connection, e con il filtro cluster per scegliere quali cluster restituire; se i tuoi cluster superano le 2.000 appartenenze prodotto-cluster, l'API ti chiede di restringerli con quel filtro.

Nelle righe raggruppate, i campi che identificano un'entità (product, asin, campaign…) arrivano a null, come ciò che non si può sommare: il rank, il prezzo, il canale e i tassi Vendor. Lo stock Seller si somma solo se raggruppi per paese: con l'inventario paneuropeo di FBA, Amazon riporta lo stesso stock in ogni marketplace, e sommarlo tra paesi conterebbe le stesse unità più volte. Per questo, con group_by=account o connection, stock e days_of_coverage arrivano a null.

Un cluster raggruppa prodotti del catalogo, non ASIN singoli: lo stesso ASIN su un'altra connessione resta fuori a meno che anche il suo prodotto non sia nel cluster. E le righe che Amazon non è riuscito ad associare a un prodotto del catalogo non entrano nel filtro: circa il 5 % delle vendite Vendor e il 3 % della spesa dei prodotti pubblicizzati.

Quanto fa risparmiare in crediti lo trovi in Crediti.

Cosa ha cambiato l'automazione su una campagna

/v1/campaigns/{id}/optimization-history risponde a cosa ha cambiato il workflow su una campagna, non a cosa ha deciso. La differenza conta: in uno storico di decisioni lo stesso target può comparire con un rialzo e un ribasso nella stessa notte, e lì non si vede che si annullano.

Per questo ogni riga arriva aggregata all'effetto netto dell'entità: l'offerta di prima del primo cambio del periodo contro quella di dopo l'ultimo, più quante volte si è mossa lungo il percorso. Un target salito da 0,18 € a 0,45 € e riportato a 0,18 € quella stessa notte torna con un netto di zero e due movimenti — che è la lettura utile, e proprio quella che un elenco nasconde.

Tre cose delimitano ciò che restituisce:

• Solo cambiamenti reali. Le simulazioni non sono esposte qui, con nessun parametro: sono offerte che non hanno mai raggiunto Amazon.
• Solo ciò che è stato applicato, non ciò che è stato proposto. L'ottimizzatore calcola un'offerta che un tetto può poi tagliare; viene riportato solo ciò che è stato inviato.
• Finestra di 90 giorni al massimo. È quanto vengono conservati questi record. Senza date, restituisce gli ultimi 90 giorni.

I cambiamenti che non sono di offerta — keyword raccolte, negativi, aggiustamenti di posizionamento, target in quarantena o bloccati — sono contati a parte in other_changes, perché non hanno un'offerta precedente con cui confrontarsi.

Tutto ciò che Epinium ha modificato su Amazon

/v1/advertising-changes risponde a una domanda diversa dalla precedente: non perché l'automazione ha deciso, ma cosa è stato toccato e se Amazon l'ha accettato. E non solo ciò che fa l'automazione: anche ciò che ha fatto una persona dall'applicazione, un processo interno o questa stessa API.

La regola sta in una riga: se è stato inviato ad Amazon, c'è una riga. Ne derivano tre conseguenze, ed è bene averle chiare:

• Anche ciò che Amazon ha rifiutato lascia una riga, con result: "failed" e il messaggio di Amazon in error. È il primo posto dove guardare quando una modifica non ha avuto effetto.
• Ciò che non è stato nemmeno tentato non lascia riga: un budget sotto il minimo del paese, o un'offerta che era già quella richiesta.
• Le modifiche di configurazione dentro Epinium restano fuori, perché non arrivano ad Amazon.

Ogni riga dice da dove viene. source distingue l'applicazione (front), l'ottimizzatore (workflow), un processo interno (system) e questo canale (public-api, mcp), e actor identifica la persona o la credenziale specifica — quando la modifica l'ha fatta qualcuno dall'applicazione, lì c'è la sua email. Se viene da un workflow, correlation_id è l'identificatore di quella esecuzione, la chiave per incrociare questa risposta con optimization-history.

Puoi filtrare per campaign, adgroup, entity, entity_type, source, result, field e correlation_id, e restringere la finestra con start_date e end_date (YYYY-MM-DD, entrambi inclusi). I record si conservano dodici mesi.

Scrivere su Amazon

Con il permesso campaigns:write l'API smette di essere in sola lettura: crea campagne, ad group, target e product ad, e muove i loro stati, budget e offerte. Ciò che scrivi arriva davvero ad Amazon e lascia la sua riga in /v1/advertising-changes.

Cinque cose da sapere prima della prima chiamata:

• Tutto nasce in pausa. Una campagna o un ad group si creano PAUSED salvo che chieda ENABLED esplicitamente, perché ciò che è attivo inizia a spendere appena Amazon lo accetta.
• Archiviare ha un verbo proprio: DELETE /v1/<risorsa>/{id}. È l'unica operazione irreversibile di questa API: su Amazon archiviare non si annulla. Per questo non è un valore di state che potresti impostare per sbaglio accanto a un cambio di offerta, ma una chiamata separata con un verbo separato. Se vuoi solo fermare la spesa usa state: "PAUSED", che è reversibile.
• Ogni scrittura richiede un header Idempotency-Key. Riusa lo stesso valore se ritenti la stessa intenzione: senza, un timeout di rete diventa due campagne.
• Un lotto non è tutto-o-niente. POST /v1/<risorsa>/batch accetta fino a 1000 entità e risponde una riga per entità, nell'ordine in cui le hai inviate. applied è ciò che è arrivato ad Amazon, ed è l'unica cosa che si addebita. Un risultato parziale è la norma, non un errore: leggilo invece di ritentare tutto il lotto, perché un nuovo tentativo duplicherebbe ciò che era già passato.
• Un'entità conta come applicata solo se è passato tutto ciò che hai chiesto. Se un PATCH cambia stato e budget e Amazon accetta il primo e rifiuta il secondo, quell'entità torna failed con il motivo — dirla applicata è come finire per credere che l'offerta si sia mossa quando non è così.

Rotta	Cosa fa
POST /v1/campaigns	Creare una campagna
POST /v1/campaigns/full	Campagna + ad group + target + product ad in una chiamata
PATCH /v1/campaigns/{id} · POST /v1/campaigns/batch	Stato, budget giornaliero, nome e portafoglio (il portafoglio, solo in Sponsored Products)
POST /v1/adgroups · PATCH /v1/adgroups/{id} · POST /v1/adgroups/batch	Creare; stato, offerta predefinita e nome
POST /v1/targets · PATCH /v1/targets/{id} · POST /v1/targets/batch	Creare target (i tipi dipendono dall'ad product dell'ad group); stato e offerta
POST /v1/product-ads · PATCH /v1/product-ads/{id} · POST /v1/product-ads/batch	Pubblicizzare prodotti; stato
POST /v1/portfolios · PATCH /v1/portfolios/{id}	Creare un portafoglio; nome, stato e tetto di budget
DELETE /v1/campaigns/{id} · DELETE /v1/adgroups/{id} · DELETE /v1/targets/{id} · DELETE /v1/product-ads/{id}	Archiviare - irreversibile

Ciò che non si può cambiare, e perché: ciò che definisce un target — la sua keyword, il suo ASIN, la sua corrispondenza — non è modificabile su Amazon, quindi per cambiarlo se ne crea un altro e si archivia il precedente. Un product ad accetta solo lo stato: è il collegamento tra un prodotto e un ad group, senza offerta né nome propri. E le entità gestite dall'ottimizzatore vengono rifiutate, perché la sua esecuzione delle 03:00 UTC riscriverebbe sopra.

Il tetto di un portafoglio limita quanto spendono insieme tutte le sue campagne. MONTHLY_RECURRING si azzera ogni mese, DATE_RANGE vale tra startDate e endDate e NO_CAP lo toglie; la valuta è quella del marketplace e non si invia. In un PATCH, budget si sostituisce per intero: manda il tetto completo che vuoi, non solo l'importo. Per spostare una campagna Sponsored Products dentro o fuori da un portafoglio, cambia il suo portfolioId con PATCH /v1/campaigns/{id}.

Due codici da distinguere. Un'entità che non esiste, o che appartiene a un altro account, risponde 404 — mai 403, che confermerebbe che esiste. Un rifiuto di Amazon risponde 200 con result: "failed" e il motivo: la chiamata è arrivata, ciò che è fallito è il cambiamento.

Tutti e tre gli ad product si scrivono, ma non allo stesso modo:

• Sponsored Brands e Sponsored Display si modificano e si archiviano con le stesse rotte di Sponsored Products: stato, budget, nome e offerte di campagne, ad group, target e product ad. Quello che ancora non si può fare è crearli: POST /v1/campaigns, /v1/campaigns/full, /v1/adgroups e /v1/product-ads sono solo per Sponsored Products.
• Gli ad group di Sponsored Brands non hanno offerta predefinita. Una modifica di defaultBid su uno di essi viene rifiutata con un messaggio che lo spiega. Quelli di Sponsored Display invece ce l'hanno.
• Target e target negativi si creano anche negli ad group SB e SD, con POST /v1/targets. Il targetType accettato dipende dall'ad product dell'ad group (tabella qui sotto). Solo a livello di ad group: SB e SD non hanno target negativi di campagna.
• Epinium controlla i limiti di offerta e budget del marketplace solo per Sponsored Products, prima dell'invio. Per Brands e Display non applica limiti propri: valida Amazon, e il suo motivo torna nella risposta, per entità con result: "failed" oppure, alla creazione di target, in failure_details, dove reference identifica il target (keyword, ASIN, SKU o l'id di audience, categoria o località).

Ad product	targetType accettati
Sponsored Products	KEYWORD, PRODUCT, PRODUCT_CATEGORY
Sponsored Brands	Quelli di Sponsored Products più THEME (themeMatchType KEYWORDS_RELATED_TO_YOUR_BRAND o KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES)
Sponsored Display	KEYWORD; PRODUCT per ASIN o per sku, con productMatchType PRODUCT_EXACT o PRODUCT_SIMILAR; PRODUCT_CATEGORY con affinamenti (marca, prezzo, valutazione, fascia d'età, idoneità Prime); THEME (INTERESTED_AUDIENCE); PRODUCT_AUDIENCE (ASIN + event PURCHASE o VIEW + lookback di 7, 14, 30, 60, 90, 180 o 365 giorni); AUDIENCE (audienceId), CONTENT_CATEGORY (contentCategoryId) e LOCATION (locationId)

Gli id di AUDIENCE, CONTENT_CATEGORY e LOCATION si ricavano dalla console di Amazon Ads: l'API non li elenca ancora.

Configurazione dell'ottimizzazione

Con lo stesso permesso campaigns:write, oltre a scrivere su Amazon puoi leggere e cambiare la configurazione che usa l'ottimizzatore di Epinium: cosa persegue in ogni campagna. È una superficie diversa da quella della sezione precedente, e conviene non confonderle.

Non arriva ad Amazon. È una configurazione propria di Epinium, che l'ottimizzatore consuma nella sua esecuzione di ogni notte, non un dato dell'account Amazon. Per questo qui non valgono due regole di "Scrivere su Amazon": non serve l'header Idempotency-Key - non c'è nessun andata-e-ritorno verso Amazon che un nuovo tentativo possa duplicare - e il cambio non lascia riga in /v1/advertising-changes, che registra solo ciò che è stato inviato ad Amazon.

Si legge con expand, non di default. GET /v1/campaigns e GET /v1/campaigns/{id} restituiscono optimizationConfig solo se chiedi ?expand[]=optimizationConfig. È opt-in perché pochissime campagne hanno questa configurazione salvata: senza expand, la colonna tornerebbe quasi sempre null.

Cosa si può impostare con PATCH /v1/campaigns/{id}/optimization-config, in linguaggio di business:

• L'obiettivo: un ACOS o un ROAS target, oppure un obiettivo di volume - impression o ordini - con un tetto di ACOS che lo accompagna.
• I limiti di offerta: il pavimento e il tetto che non può superare, il tetto del moltiplicatore di placement, e la spesa minima prima di negativizzare un target.
• Il budget mensile che persegue l'ottimizzatore - non il budget giornaliero della campagna su Amazon, che si cambia con PATCH /v1/campaigns/{id} ed è un dato diverso con lo stesso nome.
• Gli override di harvesting della campagna: il suo livello di discovery e se permette di puntare ad ASIN della concorrenza.
• Quali workflow la ottimizzano.

Quest'ultimo punto è quello che conta davvero: assegnare workflow è ciò che mette la campagna sotto ottimizzazione, non nessun altro campo di questo blocco. linkedWorkflowDefinitionIds la forza a entrare - il workflow la processa ogni notte anche se il suo filtro non l'avrebbe scelta - ed è la via con cui un workflow muove offerte reali su Amazon; confermalo con la persona prima di scriverlo, esattamente come per attivare un'automazione. Un workflow con selezione automatica può anche raccoglierla per conto suo, e workflowsOptOut: true è ciò che declina quella selezione automatica. L'unica cosa che la toglie con garanzia è excludedWorkflowDefinitionIds: vince sempre, qualunque cosa dica il resto.

aiEnabled non è l'interruttore dell'ottimizzatore

È il consenso del titolare dell'account, e viaggia verso Amazon come il tag epinium:ai_enabled. Metterlo a false non toglie la campagna dall'ottimizzazione: per questo c'è excludedWorkflowDefinitionIds, oppure toglierla da linkedWorkflowDefinitionIds.

optimizeDate e optimizingSince sono di sola lettura - li timbra l'ottimizzatore stesso - e scrivere uno dei due risponde con un 400.

POST /v1/campaigns/optimization-config/batch applica lo stesso patch fino a 1000 campagne, e non è tutto-o-niente: risponde una riga per campagna, nell'ordine in cui le hai inviate, e ognuna si valida contro il proprio stato salvato - un tetto obbligatorio per un obiettivo può essere facoltativo per un altro - quindi una riga può fallire senza che le altre ne risentano.

Due codici da distinguere, come per la scrittura su Amazon: un rifiuto di validazione - un obiettivo fuori intervallo, un workflow che non è tuo - risponde 200 con result: "failed" e il motivo in reason. Una campagna che non esiste o è di un altro account risponde 404 nel PATCH singolo; nel lotto, invece, quella stessa campagna torna come riga failed con reason: "not_found", proprio perché una riga fallita non affondi le altre 999.

Rotta	Cosa fa
PATCH /v1/campaigns/{id}/optimization-config	Cambiare la configurazione di ottimizzazione di una campagna
POST /v1/campaigns/optimization-config/batch	La stessa configurazione su fino a 1000 campagne, una riga per risultato

Scrivere task

Con il permesso tasks:write l'API crea task e decide sui loro suggerimenti, come fai tu in Processi → Attività. È il pezzo che permette a un assistente o a un'integrazione di proporre modifiche e a una persona di rivederle prima che arrivino ad Amazon.

Quattro cose da sapere prima della prima chiamata:

• Approvare non applica. Sono due passaggi: approvare o rifiutare ogni suggerimento, e poi POST /v1/tasks/{id}/apply. A quel punto le modifiche di campagna — budget giornaliero, stato e nome — vanno ad Amazon subito, e la risposta dice quali sono entrate (applied) e quali ha rifiutato (failed). Quelle di prodotto vengono messe in coda (enqueued) e applicate in background: per sapere se sono entrate, rileggi i suggerimenti e guarda appliedAt e applyError.
• Un suggerimento che niente sa applicare è una nota. Oggi si applicano quelli di prodotto e quelli di campagna che hanno un fieldPath; quelli che non ce l'hanno, e quelli di ad group, target, product ad e termini di ricerca, restano note. Approvarli lascia traccia della decisione e non cambia nulla, e la risposta lo dice con autoApplySkipped: true. Non è un errore. Alla creazione, invece, un suggerimento di campagna con un campo diverso da dailyBudget, state o name, o con un valore che non si può applicare, viene rifiutato con un 400: salvarlo significherebbe promettere una modifica che nessuno farà.
• I suggerimenti vanno con il task. Fino a 50 in items quando lo crei, ognuno riferito a un'entità del tuo account; non se ne aggiungono dopo. Un'entità che non esiste o che è di un altro account fa rifiutare l'intero task, senza creare nulla.
• Risolvere un task è definitivo. I suoi suggerimenti in sospeso non si risolvono con lui: restano congelati e non si possono più approvare. Decidi prima quelli che ti interessano e chiudi il task dopo. Risolverlo non fa nemmeno ripartire alcun workflow.

Rotta	Cosa fa
POST /v1/tasks	Creare un task, con i suoi suggerimenti
PATCH /v1/tasks/{id}	Titolo, descrizione, priorità e data di scadenza
POST /v1/tasks/{id}/resolve	Risolverlo o scartarlo
PATCH /v1/task-items/{id} · POST /v1/task-items/batch	Approvare o rifiutare suggerimenti, facoltativamente con un tuo valore in appliedValue
POST /v1/tasks/{id}/apply	Applicare ciò che è stato approvato

Come su Amazon, ogni scrittura richiede Idempotency-Key, e il lotto di suggerimenti non è tutto-o-niente: risponde una riga per suggerimento e applied conta quelli che sono stati registrati. Creare, modificare o risolvere un task costa un addebito fisso per chiamata; approvare o rifiutare si addebita per suggerimento registrato. Applicare non si addebita a parte: ogni suggerimento è già stato addebitato quando è stato approvato.

Scrivere cluster di keyword

Con il permesso catalog:write l'API crea e modifica i tuoi cluster di keyword, gli stessi che gestisci in Segmentazione → Cluster: un gruppo di prodotti con un nome, le keyword positive per cui dovrebbero posizionarsi o essere pubblicizzati e quelle negative da cui stare lontani. È il modo in cui un assistente che ha trovato un vuoto di keyword può lasciarlo salvato dove lo raccoglieranno i prompt SEO di Epinium, la scoperta di keyword dell'ottimizzatore e il filtro per cluster dei grafici di prodotto.

Quattro cose da sapere prima della prima chiamata:

• Niente arriva su Amazon. Un cluster vive in Epinium. Per questo queste scritture non lasciano righe in /v1/advertising-changes, e per questo il tuo client di IA non ti chiederà conferma per farle.
• Si modifica per delta, non per sostituzione. PATCH /v1/clusters/{id} accetta addPositiveKeywords, removePositiveKeywords, addNegativeKeywords, removeNegativeKeywords, addProducts, removeProducts e name; invia solo ciò che cambia. Aggiungere una keyword già presente ne aggiorna lingua, punteggio e scopo, abbinata per testo; rimuoverne una che non c'è non fa nulla. Un cluster ammette fino a 100 keyword positive e 50 negative, contate dopo la modifica, e una keyword non può essere positiva e negativa allo stesso tempo.
• Le keyword seguono le regole dell'applicazione. In minuscolo, fino a 80 caratteri, il set di caratteri di Amazon, senza - né . all'inizio né -, + o . alla fine; i duplicati vengono uniti. language è un codice come es-ES o en-GB, epiniumScore va da 1 a 5 e purpose è SEO, PPC o entrambi (entrambi per impostazione predefinita).
• Un cluster protetto viene rifiutato con 409. Proteggere un cluster dall'applicazione è una decisione di una persona, e questa API non può annullarla: rimuovi prima la protezione in Segmentazione → Cluster. Il campo protected della risposta te lo dice prima di provare.

Rotta	Cosa fa
POST /v1/clusters	Creare un cluster, con le sue keyword e i suoi prodotti se già li hai
PATCH /v1/clusters/{id}	Aggiungere o rimuovere keyword e prodotti, o rinominarlo
DELETE /v1/clusters/{id}	Eliminarlo, senza possibilità di tornare indietro

Ogni prodotto che colleghi deve essere del tuo account — per un'agenzia, delle connessioni che l'account ti ha condiviso — e di catalogo (type seller o vendor in /v1/products; quelli pubblicitari vengono rifiutati), altrimenti l'intera chiamata viene rifiutata con un 400 che nomina gli id in eccesso, senza scrivere nulla. Il cluster resta intestato alla persona dietro la credenziale, quindi compare nella tabella dell'applicazione a suo nome. L'eliminazione è definitiva - non c'è cestino - e viene rifiutata con un 409 finché il cluster è protetto o una smart campaign lo usa come cluster di base; l'errore nomina quelle smart campaign, che vanno modificate o eliminate prima. Ogni scrittura costa un addebito fisso per chiamata, e la quota di cluster del piano si applica qui come nell'applicazione.

Limiti

• Le metriche richiedono un intervallo di date. start_date e end_date sono obbligatori su tutte le risorse di metriche.
• L'intervallo ha un massimo, e dipende dalla granularità. Con granularity=daily, 93 giorni; con total o con i periodi di calendario (weekly, monthly, quarterly, yearly), 366. Su target e termini di ricerca, le risorse più pesanti, scendono a 31 e 93. Chiedere di più restituisce un errore che indica il limite esatto. Entrambe le date sono incluse nell'intervallo.
• Gli elenchi si paginano in due modi. Le risorse di catalogo e struttura usano un cursore (starting_after); quelle di metriche usano limit e offset. In entrambi i casi has_more indica se c'è un'altra pagina.
• C'è un limite di richieste per token. Se lo superi ricevi un 429 e basta riprovare più lentamente.
• C'è anche un limite di richieste simultanee. Un 429 può significare "troppe insieme", non solo "troppe al minuto"; un 503 significa che il server è momentaneamente saturo. Entrambi portano Retry-After ed entrambi sono transitori: riprova con meno richieste in parallelo.
• Una risposta non può espandere più di 5.000 oggetti. expand su liste — i prodotti di un cluster, i paesi di una connessione — si moltiplica a ogni livello. Superandolo ricevi un 400 che dice quanti oggetti avrebbe restituito: abbassa limit, togli un expand, oppure chiedi quei dati al loro endpoint.

Crediti

Le chiamate a questa API consumano crediti del tuo account. Quanto costa ogni risorsa lo vedi nell'applicazione, in Impostazioni → Crediti.

Ogni risposta ti dice quanto hai speso:

Header	Cos'è
X-Epinium-Credits-Cost	Quanto è costata questa chiamata
X-Epinium-Credits-Remaining	Quanto ti resta. È approssimativo: se hai altre cose che consumano contemporaneamente, può discostarsi
X-Epinium-Credits-Breakdown	Il dettaglio, per risorsa e prezzo unitario: product=100x1,country=100x0
X-Epinium-Credits-Max	Il massimo che poteva costare, calcolato prima di eseguirla

Tre cose da sapere:

• Si paga solo ciò che viene consegnato. Una chiamata che va in errore non consuma nulla, e nemmeno un expand che non restituisce dati — perché il tuo token non ha quello scope, o il record è di un altro account.
• Nelle metriche costa anche l'intervallo di date, non solo le righe. Chiedere un anno con limit=1 non è economico: oltre a ogni riga restituita si paga ogni giorno dell'intervallo, perché è quello che bisogna leggere per rispondere, con un minimo di 3 giorni per chiamata. Per spendere meno, accorcia l'intervallo.
• Per un totale, group_by invece di paginare. Un totale di account è fatto di poche righe, una per valuta, mentre paginare il catalogo per sommarlo paga ogni prodotto in ogni pagina. In un account reale, il totale delle vendite di un mese costa 157 crediti con group_by=account e circa 17.600 paginando.

Se i crediti non bastano ricevi un 402 prima di eseguire la chiamata: non ti ritroverai mai con mezza risposta. E non dice solo di no, dice cosa cambiare e a quale valore:

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_credits",
    "message": "insufficient credits: needs up to 366 (campaignMetrics=1x1,campaignMetrics:window=365x1), 120 available. Shorten the date range to 119 days or less.",
    "param": "end_date"
  }
}

param è lo stesso rimedio in forma leggibile da una macchina: limit, end_date o include_total. Se manca, nessun parametro fa entrare la chiamata e bisogna ricaricare.

Parametri e risposte di ogni endpoint

La tabella sopra dice quali risorse esistono. Per vedere i parametri di input e la forma esatta di ogni risposta ci sono due strade:

• Riferimento navigabile — ogni endpoint con i suoi parametri, i loro tipi e un esempio di risposta. È generato dall'API stessa, quindi non può diventare obsoleto. È in inglese.
• Schema OpenAPI — il documento OpenAPI 3.0 grezzo, da importare in Postman, Insomnia o un generatore di client. Non serve token.