Skip to content

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, il tuo P&L con costo prodotto, 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à; crea o aggiorna il costo dei tuoi prodotti e registra i loro acquisti dai fornitori; salva modifiche a qualsiasi attributo dei tuoi listing Amazon e crea nuove offerte, prodotti nuovi e famiglie di varianti; e crea, modifica ed elimina prodotti e contenuti nei tuoi negozi Shopify e WooCommerce collegati. Nel tuo catalogo Amazon, ciò che salvi resta in sospeso e arriva su Amazon solo quando viene pubblicato, dall'app o dall'API con il suo permesso; quello dei tuoi negozi cambia direttamente, senza restare in sospeso. 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.

PermessoDà accesso a
catalog:readProdotti, brand, paesi, cluster, prompt personalizzati e identità di marca, con le relative metriche: vendite, commissioni Amazon e margine, resi, stock e, per Vendor, recensioni; e il tuo P&L, con il costo prodotto e le tue spese proprie se il tuo piano lo include
campaigns:readCampagne, portafogli, ad group, target, product ads e termini di ricerca
workflows:readI tuoi workflow, la loro configurazione e quali campagne raggiungono
connections:readLe connessioni del tuo account: Amazon, Shopify e WooCommerce
tasks:readTask di Epinium e i loro item
skills:readIl catalogo di playbook di marketing validati di Epinium
platform:readCiò 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:writeCreare, modificare ed eliminare cluster di keyword: il nome, le keyword positive e negative, i prodotti che raggruppano e i prompt che usano. Creare e modificare prompt personalizzati. Creare e modificare la tua identità di marca, con una scheda per concorrente. Salvare modifiche agli attributi dei tuoi listing Amazon da un file, come modifiche in attesa di pubblicazione. Salvare e scartare nuove offerte su Amazon (offerte su prodotti che esistono già, prodotti nuovi e famiglie) e caricare immagini di prodotto. Niente arriva su Amazon finché non lo pubblichi
costs:writeCreare o aggiornare il costo unitario e il costo di spedizione dei tuoi prodotti, e registrare, correggere ed eliminare i loro acquisti, uno alla volta o importandoli da un file; e creare, modificare ed eliminare le tue spese proprie e le loro categorie
campaigns:writeCreare e modificare campagne, portafogli, ad group, target e product ad su Amazon, e configurare cosa persegue l'ottimizzatore su ciascuna
platform:writeCreare, 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:writeCreare task, approvare o rifiutare i loro suggerimenti, chiuderli e applicare ciò che è stato approvato. Chiedere all'IA di Epinium di riscrivere schede come suggerimenti di un task
workflows:writeCreare, copiare, modificare, attivare, mettere in pausa, eliminare e ripristinare workflow, e lanciarli o simularli
catalog:publishPubblicare su Amazon le modifiche ai listing e le nuove offerte in sospeso che scegli (POST /v1/pending-listing-changes/publish), per la stessa strada del pulsante Pubblicare dell'app. Non si può annullare. Serve anche catalog:write

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 ​

EndpointCosa restituisce
/v1/productsI tuoi prodotti unificati
/v1/amazon-seller-productsLa vista Seller Central di ogni prodotto, e la categoria del suo ranking con expand=salesRanks
/v1/amazon-vendor-productsLa vista Vendor Central, la categoria del ranking con expand=salesRanks e le recensioni con expand=customerFeedback
/v1/amazon-advertising-productsLa vista Advertising
/v1/seller-product-metricsVendite, sessioni, Buy Box, rank, commissioni Amazon, margine, resi, stock, B2B e giorni di copertura per prodotto
/v1/vendor-product-metricsVendite Vendor per prodotto, con manufacturing e sourcing, resi, sell-in con Amazon, inventario e giorni di copertura
/v1/product-brandsI tuoi brand
/v1/countriesPaesi e marketplace
/v1/clustersI tuoi cluster di keyword; con catalog:write li crei e li modifichi anche
/v1/pnl/*Il tuo P&L: cascata, tabella per prodotto, per cluster, per canale di vendita, pubblicità incrociata, freschezza, perdite di margine e inventario - spiegato in Il P&L con costo prodotto
/v1/promptsI tuoi prompt personalizzati; con catalog:write li crei e li modifichi anche
/v1/brand-identitiesLa tua identità di marca, con una scheda per concorrente; con catalog:write la crei e la modifichi anche - spiegato in Scrivere la tua identità di marca
/v1/listing-filesI file di modifiche ai listing che hai caricato negli ultimi 7 giorni; caricarne uno richiede catalog:read, e salvare come file delle righe scritte a mano, catalog:write
/v1/listing-updatesPreparare e convalidare le modifiche di un file senza salvare nulla; con catalog:write, salvarle in attesa di pubblicazione - spiegato in Modificare i listing da un file
/v1/listing-draftsLe tue nuove offerte su Amazon e il loro stato; con catalog:write, salvarle e scartarle. Per cercare il prodotto e convalidarle, /v1/amazon-catalog/search, /v1/amazon-product-types/search, /v1/amazon-shipping-templates e /v1/listing-drafts/validate - spiegato in Creare nuove offerte su Amazon
/v1/listing-imagesCon catalog:write, caricare un'immagine di prodotto per un listing o una nuova offerta: JPG, PNG, GIF o TIFF, fino a 8 MB, conservata 30 giorni
/v1/pending-listing-changesCiò che è in attesa di pubblicazione su Amazon, modifiche e nuove offerte; con catalog:write e catalog:publish, pubblicarlo
/v1/publicationsOgni pubblicazione su Amazon e come va per paese, come il pannello Pubblicazioni dell'app

Advertising — campaigns:read ​

EndpointCosa restituisce
/v1/campaignsLe tue campagne Amazon Advertising
/v1/campaigns/budget-usageQuanto ha speso oggi ogni campagna del suo budget giornaliero, secondo Amazon, con al massimo mezz'ora di ritardo
/v1/campaign-metricsSpesa, vendite, ACOS e ROAS per campagna
/v1/portfoliosI tuoi portafogli e il tetto di budget che ciascuno impone alle sue campagne
/v1/portfolios/budget-usageQuanto ha speso ogni portafoglio del suo tetto nel periodo, a che ritmo va e quanto può spendere al giorno per chiudere esattamente sul tetto
/v1/adgroupsGli ad group di ogni campagna
/v1/adgroup-metricsPerformance per ad group
/v1/targetsKeyword e target di prodotto
/v1/target-metricsPerformance per target, con la sua keyword e il tipo di corrispondenza
/v1/product-adsIl collegamento tra un ad group e il prodotto che pubblicizza
/v1/product-ad-metricsPerformance per prodotto pubblicizzato, con il suo ASIN
/v1/search-termsLe ricerche reali degli acquirenti
/v1/search-term-metricsPerformance per ricerca, con il testo e il target che l'ha intercettata
/v1/campaigns/{id}/optimization-historyCosa ha cambiato l'automazione su una campagna, con l'effetto netto
/v1/advertising-changesTutto ciò che Epinium ha modificato su Amazon, da qualunque origine

Automazione — workflows:read ​

EndpointCosa restituisce
/v1/workflowsI 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}/campaignsQuali campagne raggiunge davvero, e perché ognuna ci rientra
/v1/workflows/{id}/performanceLa 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 ​

EndpointPermessoCosa restituisce
/v1/connectionsconnections:readLe tue connessioni: Amazon, Shopify e WooCommerce
POST /v1/platform-requestplatform:read, e platform:write per scrivereUna query a uno dei tuoi negozi o, con platform:write, una modifica: GraphQL su Shopify, REST su WooCommerce
/v1/platform-request/docs/{platform}platform:readLa versione dell'API di quella piattaforma, la sua documentazione di riferimento e i campi che ha il tuo negozio in questo momento
/v1/taskstasks:readTask di Epinium
/v1/task-itemstasks:readGli item di ogni task
/v1/skillsskills:readIl 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.

Il P&L con costo prodotto ​

È lo stesso conto economico che vedi in Redditività → P&L: vendite, commissioni e logistica Amazon, pubblicità e, se il tuo piano lo include, il costo dei tuoi prodotti e le tue spese proprie, con lo stesso calcolo e gli stessi numeri.

Ciò che vedi dipende dal tuo piano. In Free e Guru il P&L arriva fino a margin_before_ads: ciò che resta dopo Amazon, prima della pubblicità e prima del costo prodotto - non chiamarlo "profitto", perché non lo è. In Business e Master arriva fino in fondo: margine di contribuzione, ogni riga di costo prodotto e la sua copertura, e le tue spese proprie fino all'utile netto. includes_product_cost in ogni risposta ti dice quale dei due stai vedendo, così non devi indovinarlo a seconda che i numeri corrispondano a quanto ti aspettavi. Perdite di margine (/v1/pnl/margin-leaks e /v1/pnl/category-medians) è solo per Business e Master: in Free e Guru risponde 403 con code: "plan_feature_not_allowed", e le sue risposte non portano includes_product_cost, perché includono sempre il costo. Lo stesso vale per l'inventario (/v1/pnl/inventory), valorizzato al costo prodotto.

EndpointCosa restituisce
/v1/pnl/cascadeLa cascata del periodo: vendite, resi, commissioni, logistica, pubblicità, costo prodotto e spese proprie fino all'utile netto, mese per mese o giorno per giorno
/v1/pnl/productsUna riga per prodotto, con il suo margine di contribuzione e la sua copertura di costo
/v1/pnl/products/{id}Il dettaglio di un prodotto: la sua cascata, mese per mese
/v1/pnl/clustersUna riga per cluster, con il suo margine di contribuzione, la sua copertura dei costi e quanti prodotti ha
/v1/pnl/channelsUna riga per canale di vendita (Seller, Vendor…), con la sua pubblicità suddivisa per piattaforma
/v1/pnl/ads-matrixLa spesa pubblicitaria incrociata: su quale canale di vendita fa pubblicità ogni piattaforma
/v1/pnl/freshnessLa data dell'ultimo dato di ogni fonte -Amazon, pubblicità e costo prodotto- per sapere se ciò che leggi è già completo
/v1/pnl/margin-leaksI prodotti che hanno perso margine rispetto al periodo precedente, ordinati per denaro a rischio, con il loro stato, la causa principale e i totali di tutta la classifica: lo stesso di Perdite di margine
/v1/pnl/category-mediansL'abituale nel tuo account: la mediana del peso di ogni costo sulle vendite nette, per vedere se il costo di un prodotto è fuori dal normale
/v1/pnl/inventoryIl capitale immobilizzato nei magazzini di Amazon: lo stock FBA di oggi valorizzato al costo, con i suoi giorni di stock, la rotazione e lo stoccaggio fino alla vendita: lo stesso di Inventario

Nove cose da sapere prima della prima chiamata:

  • Questa è l'unica parte dell'API che converte la valuta. Le altre risorse restituiscono ogni importo nella valuta in cui si è verificato; qui chiedi una currency e tutto viene convertito in essa, al tasso di cambio del giorno in cui si è verificato ogni importo. Un giorno senza tasso di cambio ricade su uno approssimativo, mai su un errore.
  • Le spese proprie arrivano in own_expenses. Le variabili sono già sottratte nella sezione variable_expenses, prima del margine di contribuzione, e own_expenses.periods[].variable le suddivide per categoria. Le fisse (fixed) si sottraggono dopo, fino a net_profit. Siccome sono di tutto l'account, con connection, country o cluster, o con un token che non raggiunge tutte le connessioni di vendita, fixed e net_profit escono null e fixed_unavailable dice perché: filtered o partial_access. Se l'account non ha spese fisse non manca nulla, e net_profit esce anche con un filtro o con un token che non raggiunge tutte le connessioni. Nella tabella per prodotto, la colonna own_expenses è la parte delle spese variabili di ogni prodotto.
  • coverage dice quale parte delle vendite ha un costo reale. Un prodotto senza costo caricato non viene scartato né azzerato in silenzio: coverage.covered_sales su coverage.total_sales ti dice quale proporzione della cifra è attendibile. In coverage, estimated_sales è la parte di covered_sales con costo stimato: lo stock ha venduto più unità di quelle lasciate dagli acquisti registrati, e quelle vendite portano l'ultimo costo medio.
  • breakeven_acos, in /v1/seller-product-metrics, è fino a che ACOS puoi permetterti di spendere in pubblicità prima di perdere denaro su quel prodotto, calcolato con il tuo margine e il tuo costo reali -mai con una percentuale di commissione presunta. Esce null -mai un numero inventato- se il prodotto non ha un costo completo, non ha venduto nulla nel periodo, ha il costo registrato in una valuta diversa da quella del proprio marketplace (questa risorsa non converte le valute, a differenza di /v1/pnl/*), oppure se il tuo piano non include il costo prodotto (Free e Guru).
  • Il costo prodotto si conserva scendendo di piano, non viene eliminato. Se passi a Guru, il costo già caricato resta lì: smette solo di essere servito. Torna non appena risali di piano.
  • cluster restringe /v1/pnl/cascade, /v1/pnl/products, /v1/pnl/clusters, /v1/pnl/freshness, /v1/pnl/margin-leaks, /v1/pnl/category-medians e /v1/pnl/inventory ai prodotti di uno o più cluster, come nelle metriche: con più id, l'unione, e un cluster senza prodotti restituisce un risultato vuoto, non un errore. La pubblicità conta solo la spesa di quei prodotti: Sponsored Brands e la spesa di campagna che non corrisponde a un prodotto specifico restano esclusi, perché non appartengono a nessun cluster. In /v1/pnl/clusters un prodotto che è in due cluster conta in entrambi, e ciò che non è in nessun cluster non appare.
  • /v1/pnl/margin-leaks restituisce di default i prodotti di tutti e tre gli stati, come la schermata; con status tieni quelli che scegli. Nella stessa chiamata, summary dà quanti ce ne sono per stato e il totale a rischio dei prodotti in Perdita e Da monitorare di tutta la classifica, senza paginare, e ogni riga porta main_cause, il costo che ha tolto più margine, calcolato come nella schermata. Se il periodo precedente non ha vendite, has_previous_sales è false: l'elenco vuoto vuol dire che non c'è nulla da confrontare, non che non ci siano perdite.
  • /v1/pnl/inventory è lo stock di oggi, senza periodo: una riga per stock, e nell'UE uno SKU paneuropeo compare una sola volta, con tutti i suoi countries, quindi non sommare righe tra paesi. summary dà il capitale immobilizzato di tutto il perimetro e la sua ripartizione per rotazione, senza paginare e senza che rotation e search lo modifichino. currency è obbligatoria: il costo si converte all'ultimo tasso di cambio e lo stoccaggio a quello di ogni giorno. Conta solo lo stock FBA delle tue connessioni Seller.
  • Il costo valido oggi di ogni prodotto arriva in /v1/products. Il campo cost contiene cogs e shipping, ciascuno con l'importo unitario, la sua valuta, valid_from e source, oppure null se non ce l'ha. Con cost_state tieni i prodotti attivi with (con costo), missing (senza costo) o missing_with_sales (senza costo e con vendite negli ultimi 30 giorni, quelli che gonfiano di più il margine), e con include_total sai quanti sono. È lo stesso che vedi in Costi e spese. In Free e Guru cost arriva null e cost_state risponde 403.

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ì.
RottaCosa fa
POST /v1/campaignsCreare una campagna
POST /v1/campaigns/fullCampagna + ad group + target + product ad in una chiamata
PATCH /v1/campaigns/{id} · POST /v1/campaigns/batchStato, budget giornaliero, nome e portafoglio (il portafoglio, solo in Sponsored Products)
POST /v1/adgroups · PATCH /v1/adgroups/{id} · POST /v1/adgroups/batchCreare; stato, offerta predefinita e nome
POST /v1/targets · PATCH /v1/targets/{id} · POST /v1/targets/batchCreare 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/batchPubblicizzare 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.

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 producttargetType accettati
Sponsored ProductsKEYWORD, PRODUCT, PRODUCT_CATEGORY
Sponsored BrandsQuelli di Sponsored Products più THEME (themeMatchType KEYWORDS_RELATED_TO_YOUR_BRAND o KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES)
Sponsored DisplayKEYWORD; 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.

RottaCosa fa
PATCH /v1/campaigns/{id}/optimization-configCambiare la configurazione di ottimizzazione di una campagna
POST /v1/campaigns/optimization-config/batchLa 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.
RottaCosa fa
POST /v1/tasksCreare un task, con i suoi suggerimenti
PATCH /v1/tasks/{id}Titolo, descrizione, priorità e data di scadenza
POST /v1/tasks/{id}/resolveRisolverlo o scartarlo
PATCH /v1/task-items/{id} · POST /v1/task-items/batchApprovare o rifiutare suggerimenti, facoltativamente con un tuo valore in appliedValue
POST /v1/tasks/{id}/applyApplicare ciò che è stato approvato
POST /v1/tasks/listing-optimizationsChiedere all'IA di Epinium di riscrivere schede, come suggerimenti di un task - spiegato in Riscrivere le schede con l'IA di Epinium

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.

Riscrivere le schede con l'IA di Epinium ​

Con il permesso tasks:write, POST /v1/tasks/listing-optimizations chiede all'IA di Epinium di riscrivere il titolo (con i suoi punti salienti, gli Item Highlights), i bullet point, la descrizione e i termini di ricerca di 1-20 prodotti del tuo catalogo. È la stessa generazione dell'applicazione: segue i cluster di keyword di ogni prodotto, i prompt collegati a essi e la tua identità di marca. Il risultato non modifica nessuna scheda: resta come suggerimenti in un task, quello dell'onboarding, perché una persona li riveda.

Cinque cose da sapere prima della prima chiamata:

  • Risponde subito e genera dopo. La risposta è un 202 con l'id del task (task) e quanto resta del tetto (limit). Ogni suggerimento compare nel task quando è pronto: leggili in /v1/task-items filtrando per task.
  • Niente arriva su Amazon senza passare da te. Approvi o rifiuti ogni suggerimento e applichi il task (POST /v1/tasks/{id}/apply), come qualsiasi altro. Applicare lascia le modifiche in attesa di pubblicazione: arrivano su Amazon quando le pubblichi, dall'applicazione o con POST /v1/pending-listing-changes/publish, che richiede catalog:publish.
  • Non consuma i tuoi crediti, ma ha un tetto. La riscrittura la paga Epinium, fino a 20 prodotti per account in totale. Conta ogni prodotto di ogni chiamata, anche se ne rilanci uno o se la sua generazione fallisce. Una chiamata che chiede più prodotti di quelli che ti restano viene rifiutata per intero con un 403 il cui code è listing_optimization_limit_reached, senza generare nulla; limit (cap, used, remaining) ti dice in ogni risposta quanti te ne restano. Approvare o rifiutare i suggerimenti si addebita come in qualsiasi task.
  • Scegli tu prodotti e campi. products sono id di prodotti del catalogo, Seller o Vendor (/v1/products; quelli di pubblicità non valgono). fields accetta title, bullets, description e search_terms; senza, si riscrivono tutti e quattro. title riscrive anche i punti salienti.
  • Richiede Idempotency-Key. Riusa la stessa chiave quando riprovi, altrimenti consumeresti di nuovo prodotti del tetto.

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, addPrompts, removePrompts 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.
RottaCosa fa
POST /v1/clustersCreare un cluster, con le sue keyword, i suoi prodotti e i suoi prompt se già li hai
PATCH /v1/clusters/{id}Aggiungere o rimuovere keyword, prodotti e prompt, o rinominarlo
DELETE /v1/clusters/{id}Eliminarlo, senza possibilità di tornare indietro

Ogni prompt che colleghi deve essere del tuo account, altrimenti la chiamata viene rifiutata con un 400 che nomina gli id in eccesso. 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.

Scrivere prompt personalizzati ​

Con il permesso catalog:write l'API crea e modifica i tuoi prompt personalizzati, quelli della tua libreria di prompt: istruzioni con un nome che l'IA di Epinium segue quando redige il contenuto delle tue schede -tono, struttura, parole da usare o da evitare-. Leggerli richiede solo catalog:read, in /v1/prompts, e ogni cluster restituisce in prompts gli id dei suoi; con expand[]=prompts li restituisce interi.

Quattro cose da sapere prima della prima chiamata:

  • Un prompt da solo non cambia nulla. Non tocca Amazon né riscrive alcuna scheda quando viene salvato: si applica quando si genera il contenuto dei prodotti dei cluster a cui lo colleghi (addPrompts in PATCH /v1/clusters/{id}). Se più prompt dei cluster di un prodotto valgono per lo stesso campo, se ne usa solo uno, quindi lascia un prompt per campo.
  • fields indica a quali campi della scheda si applica: titleAndHighlights (il titolo e i punti salienti dell'articolo, che si redigono insieme), product_description, bullet_point o generic_keyword (i termini di ricerca). Senza fields, o con [], vale per tutti. Un prompt vecchio può portare ancora item_name, il titolo da solo, che si legge ma non si accetta più in scrittura.
  • L'istruzione ha un tetto: fino a 2.000 caratteri, gli stessi dell'applicazione. Il nome ne richiede almeno 3.
  • Quando modifichi, ciò che invii sostituisce ciò che c'era: PATCH /v1/prompts/{id} accetta name, instruction e fields, e fields sostituisce l'intera lista.
RottaCosa fa
POST /v1/promptsCreare un prompt
PATCH /v1/prompts/{id}Rinominarlo o cambiarne l'istruzione o i campi

Il prompt resta intestato alla persona dietro la credenziale. L'eliminazione dei prompt non è disponibile tramite l'API. Ogni scrittura costa un addebito fisso per chiamata, e la quota di prompt del piano si applica qui come nell'applicazione: se l'hai già raggiunta, la creazione risponde 403.

Scrivere la tua identità di marca ​

Con il permesso catalog:write l'API crea e modifica la tua identità di marca, quella di Configurazione → Marchio: il nome del marchio, il settore, i siti web, quelli dei tuoi concorrenti, le tue osservazioni (tono, pubblico, parole da usare o evitare) e i brand del tuo catalogo che copre. È il contesto che usa l'IA di Epinium per redigere le tue schede. Leggerla richiede solo catalog:read, in /v1/brand-identities. Non sono i brand del tuo catalogo, che si trovano in /v1/product-brands.

Oltre ai siti web sciolti di competitor_urls, ogni concorrente può avere la sua scheda in competitors, fino a 50:

CampoCos'è
nameNome del marchio o del venditore. Obbligatorio
urlIl suo sito web o il suo negozio su Amazon
asinsGli ASIN dei suoi prodotti in concorrenza con i tuoi, fino a 20
threatLa sua pericolosità: level (low, medium o high) e reason, il motivo visto nei dati. Il livello non va mai senza il suo motivo; se non ci sono ancora prove, si lascia fuori
price_positionIl suo prezzo rispetto al tuo: below, similar o above

Quattro cose da sapere prima della prima chiamata:

  • Le schede dei concorrenti non si vedono ancora nell'applicazione. Si salvano e si leggono tramite l'API e l'MCP; Configurazione → Marchio non le mostra ancora.
  • Quando modifichi, una lista sostituisce quella che c'era. PATCH /v1/brand-identities/{id} cambia solo i campi che invii, ma competitors, competitor_urls, brand_urls e product_brand_ids si sostituiscono per intero: per aggiungere un concorrente, invia quelli che avevi più il nuovo. I valori precedenti non vengono conservati da nessuna parte.
  • Le schede non sostituiscono competitor_urls. Sono due liste indipendenti, e i siti web che avevi già restano. Un'identità salvata prima che esistessero le schede ha competitors vuoto.
  • Niente arriva su Amazon. L'identità di marca vive in Epinium: salvarla non tocca né riscrive le tue schede. Tramite l'API non si può eliminare né caricarne il logo.
RottaCosa fa
POST /v1/brand-identitiesCreare un'identità di marca
PATCH /v1/brand-identities/{id}Modificarne i campi o le liste

Come ogni scrittura, richiede Idempotency-Key.

Modificare i listing da un file ​

Con il permesso catalog:write l'API salva modifiche agli attributi di molte schede Amazon in una volta, partendo da un Excel o da un CSV: qualsiasi attributo che Amazon permetta di modificare nel tipo di prodotto di ogni scheda, in Seller e in Vendor. È ciò che usa l'MCP di Epinium, dove il flusso completo è spiegato dal punto di vista di chi lo richiede.

RottaPermessoCosa fa
POST /v1/listing-filescatalog:readCarica il file (.xlsx, .xls o .csv) e restituisce il suo file_id. Viene conservato 7 giorni
POST /v1/listing-files/rowscatalog:writeSalva come file delle intestazioni e delle righe che hai già, senza caricare nulla
POST /v1/listing-updates/preparecatalog:readTrova i prodotti del file per SKU, ASIN o EAN e dice quali attributi accettano
POST /v1/listing-updates/validatecatalog:readConvalida le righe con le regole di Amazon di ogni tipo di prodotto, senza salvare nulla
POST /v1/listing-updates/applycatalog:writeSalva le righe valide come modifiche in attesa di pubblicazione, in background
GET /v1/listing-updates/apply/{file_id}catalog:readLo stato di quel salvataggio, cosa è stato inviato e quanto è costato

Cinque cose da sapere prima della prima chiamata:

  • Niente arriva su Amazon al salvataggio. apply lascia le modifiche in attesa di pubblicazione, e partono verso Amazon quando qualcuno le pubblica da Pubblica modifiche in Epinium o con POST /v1/pending-listing-changes/publish (vedi Creare nuove offerte su Amazon).
  • I dati che vanno insieme richiedono una persona. Un valore che obbliga a compilarne altri, come le batterie, viene salvato solo se il suo cascade_id arriva in confirmed_cascades; altrimenti finisce in un task da rivedere. Il resto della riga viene salvato comunque.
  • Si pagano 5 crediti per riga. Quando il file viene accettato si riservano 5 crediti per ogni riga, con un 402 se il saldo non basta. Alla fine si addebitano solo le righe inviate e il resto viene restituito, per intero se fallisce. Caricare, preparare, validare e consultare lo stato non si pagano.
  • I prezzi vanno per pubblico. Una colonna si dichiara con offer: { audience, field } (field: price, min, max, sale_price, sale_start o sale_end); clear: true fa sì che le sue celle vuote cancellino, e date_order (dmy o mdy) fissa l'ordine di date ambigue. validate restituisce in offer_clears le colonne di prezzo con celle vuote su prodotti che hanno quel valore, e le regole di prezzo come problemi bloccanti offer_*. In Vendor non si modifica nessun prezzo: quelle colonne arrivano in not_applicable con il motivo vendor_price. prepare offre i campi di prezzo in offer_fields.
  • Un file si applica una volta. Ripetere la chiamata con le stesse impostazioni restituisce lo stato; con impostazioni diverse, o con un file a cui restano meno di 24 ore, risponde 409. Come ogni scrittura, richiede Idempotency-Key.

I parametri di ogni rotta sono nel riferimento del catalogo.

Creare nuove offerte su Amazon ​

Con il permesso catalog:write l'API salva nuove offerte: prodotti che non sono ancora nel tuo account Amazon. Può essere un'offerta su un ASIN che esiste già (solo in Seller), un prodotto nuovo o una famiglia di varianti, in Seller e in Vendor. Cos'è ognuna, cosa chiede Amazon e come si pubblica una famiglia è spiegato in Nuove offerte di prodotti su Amazon.

RottaPermessoCosa fa
GET /v1/amazon-catalog/searchcatalog:readCerca un prodotto nel catalogo di Amazon per ASIN, EAN, UPC o GTIN, con le sue restrizioni per il tuo account
GET /v1/amazon-product-types/searchcatalog:readConsiglia tipi di prodotto a partire dal nome di un prodotto nuovo
GET /v1/amazon-shipping-templatescatalog:readI modelli di spedizione del tuo account Seller, per un'offerta che spedisci tu
POST /v1/listing-drafts/validatecatalog:readConvalida la nuova offerta con le regole di Amazon e con un'anteprima di Amazon, senza salvare nulla
POST /v1/listing-draftscatalog:writeSalva la nuova offerta in attesa di pubblicazione
GET /v1/listing-draftscatalog:readLe tue nuove offerte e il loro stato, con ciò che ha risposto Amazon
DELETE /v1/listing-drafts/{id}catalog:writeScarta una nuova offerta in sospeso
GET /v1/pending-listing-changescatalog:readCiò che è in attesa di pubblicazione, come in Pubblica modifiche
POST /v1/pending-listing-changes/publishcatalog:write e catalog:publishPubblica su Amazon le modifiche e le nuove offerte scelte, per la stessa strada del pulsante Pubblicare dell'app

Quattro cose da sapere prima della prima chiamata:

  • Salvare non è pubblicare. La nuova offerta resta in sospeso finché non viene pubblicata dall'app o con publish, che richiede anche catalog:publish e non si può annullare.
  • Lo SKU deve essere nuovo in quel marketplace (in Vendor, sotto quel vendor code): uno che esiste già, in Epinium o su Amazon, risponde 409.
  • Salvare interroga di nuovo Amazon e risponde 400, con ciò che manca, se Amazon rifiuterebbe la nuova offerta: convalida prima.
  • Si pagano la convalida (1 credito) e il salvataggio (5). Cercare, i modelli, elencare, scartare e pubblicare non si pagano. Come ogni scrittura, salvare e pubblicare richiedono Idempotency-Key.

I parametri di ogni rotta sono nel riferimento del catalogo.

Scrivere il costo di un prodotto ​

Con il permesso proprio costs:write -non catalog:write, che è per i cluster, i prompt e i listing- l'API crea o aggiorna il costo unitario e il costo di spedizione di un prodotto: la stessa azione che fai sulla scheda del prodotto o caricando il modello CSV dei costi, con la stessa semantica. Per molti prodotti alla volta, usa l'importazione.

RottaCosa fa
POST /v1/products/{id}/costsCrea o aggiorna il costo unitario (price) e il costo di spedizione (shipping_cost) di un prodotto

Quattro cose da sapere prima della prima chiamata:

  • La semantica è quella del CSV. Un campo vuoto non tocca il valore: se mandi solo price, il costo di spedizione già presente resta invariato. Uno 0 lo azzera davvero -non è lo stesso che non mandare il campo. Almeno uno tra price e shipping_cost è obbligatorio.
  • Una data passata ricalcola lo storico. date di default è oggi; se mandi una data precedente, il nuovo costo si applica da lì e il P&L dei periodi già chiusi successivi si ricalcola da solo. La risposta dice cosa è successo in recalculation: not_needed con data di oggi, queued se ha messo in coda il ricalcolo, o failed se non è riuscito a metterlo in coda -il costo si salva comunque, solo che il P&L metterà un po' a rifletterlo.
  • Solo nei piani che includono il costo prodotto. In Free e Guru questa rotta risponde 403, come qualsiasi altra scrittura su quei piani. Come ogni scrittura, richiede Idempotency-Key.
  • Un prodotto con acquisti non accetta price. Il suo costo del prodotto lo calcolano gli acquisti registrati, quindi risponde 409 con il codice COST_FROM_PURCHASES. Per cambiare solo la sua spedizione, invia shipping_cost da solo, senza price: con entrambi, si rifiuta tutto e la spedizione non viene salvata. Per cambiare il suo costo prodotto, registra o correggi un acquisto (Registrare gli acquisti di un prodotto).

Registrare gli acquisti di un prodotto ​

Quando un prodotto ha acquisti, il suo costo prodotto è il costo medio del suo stock: ogni acquisto lo ricalcola con le unità che avevi e quelle che acquisti. È lo stesso di Registrare gli acquisti sulla scheda del prodotto, con lo stesso calcolo. Leggere richiede catalog:read; registrare, correggere ed eliminare, costs:write. Entrambe le cose, solo nei piani che includono il costo prodotto.

RottaCosa fa
GET /v1/products/{id}/purchasesGli acquisti del prodotto, con il costo medio lasciato da ciascuno
GET /v1/products/{id}/stock-groupCon quali prodotti condivide lo stock, o con quali verrebbe raggruppato al suo primo acquisto
GET /v1/purchasesI tuoi acquisti, per account e per date
GET /v1/purchases/{id}Un acquisto
POST /v1/products/{id}/purchasesRegistra un acquisto
PATCH /v1/purchases/{id}Corregge un acquisto: invia solo ciò che cambia
DELETE /v1/purchases/{id}Elimina un acquisto
  • Lo stock condiviso ha un solo costo. Con il paneuropeo, lo stesso SKU nei paesi dell'UE è lo stesso stock, quindi un acquisto cambia il costo di tutti questi paesi (UK e Vendor vanno a parte). Il gruppo nasce con il primo acquisto; se oggi quei paesi hanno costi diversi, quell'acquisto richiede prior_stock_unit_cost, quanto valeva lo stock già presente, oppure risponde 400 con PRIOR_STOCK_VALUE_REQUIRED.
  • Lo stock prima dell'acquisto. Senza stock_on_hand si prende l'ultimo stock Amazon FBA dei 7 giorni precedenti, più gli acquisti registrati da allora. In FBM è obbligatorio.
  • Il numero d'ordine non si ripete. Con reference, lo stesso acquisto inviato di nuovo risponde 409 con DUPLICATE_PURCHASE_EXTERNAL_ID invece di duplicarsi.
  • Correggere o eliminare ricalcola. Cambia il costo medio di quell'acquisto e di quelli successivi, e il P&L dei periodi già chiusi, come un costo con data passata. L'eliminazione non si annulla; se era l'ultimo acquisto del gruppo, tornano a valere i costi di prima.
  • Con più account, leggere ne richiede uno e scrivere tutti. Se lo stock è condiviso da account a cui la chiave non arriva, puoi leggere i loro acquisti ma non modificarli: 400 con STOCK_GROUP_OUT_OF_SCOPE quando registri, 404 quando correggi o elimini.
  • Ogni scrittura costa quanto scrivere un costo, e come ogni scrittura richiede Idempotency-Key.

Importare i costi di molti prodotti ​

Per caricare il costo del tuo catalogo, usa l'importazione: è la stessa di Importare costi da un file nell'app, con lo stesso modello e le stesse regole, e ricalcola il P&L una sola volta, alla fine. Con lo stesso permesso costs:write.

Non farlo prodotto per prodotto con POST /v1/products/{id}/costs: ogni costo con una data passata ricalcola il P&L dell'intero account, e mentre è in corso l'API rifiuta i successivi con un 409.

RottaCosa fa
POST /v1/cost-imports/filesCarica il file dei costi e restituisce il suo file_id, senza importare nulla. Viene conservato 7 giorni. GET elenca quelli che hai caricato
POST /v1/cost-imports/previewControlla l'importazione senza salvare nulla: quali righe si applicherebbero, quali no e perché, quante sono senza data, quante conteranno solo fino a un costo successivo che il prodotto ha già e quanto costerebbe
POST /v1/cost-importsImporta i costi dei prodotti di un account, da file caricati o da righe
GET /v1/cost-imports/{id}Lo stato dell'importazione: quante righe sono state applicate, quante non cambiavano nulla e quante sono state rifiutate, con il motivo di ciascuna

Cosa conviene sapere:

  • Le righe arrivano in due modi. Con file_ids, i file che hai caricato con POST /v1/cost-imports/files (.xlsx, .xls o .csv, fino a 8 MB e 200.000 righe per importazione: un catalogo intero sta in un file; un Excel con molte colonne può non entrare, e allora si tolgono quelle in più o si carica come CSV). I file caricati per le modifiche ai listing non valgono qui. Oppure con headers e rows, fino a 5.000 righe, se non hai caricato nessun file.
  • Le colonne sono quelle del modello (sellerSku, marketplace, date, cogs, cogsCurrency, shippingCost e shippingCostCurrency) e vengono riconosciute come nell'app, anche con nomi comuni come "sku", "cost" o "date". Se una non viene riconosciuta, indica da quale intestazione viene ogni dato con columns. Ogni riga segue le regole del file dell'app.
  • Controllala prima, gratis. POST /v1/cost-imports/preview riceve lo stesso corpo e applica le stesse regole riga per riga, compreso il confronto con il tuo catalogo, ma non salva né addebita nulla. Ti dice quante righe si applicherebbero, verrebbero saltate (vuote, o con lo stesso costo che il prodotto aveva già nella loro data: unchanged) o rifiutate, con il motivo ed esempi, quante sarebbero senza data e quanti crediti costerebbe. Solo all'applicazione una riga può ancora essere rifiutata, se non c'è un tasso di cambio per la sua valuta alla sua data.
  • Una riga senza data vale da oggi. Se le tue righe non hanno data, passa in date il giorno da cui valgono i costi: si applica alle righe senza data, e quelle che ce l'hanno tengono la loro.
  • I prodotti padre di variazione vengono rifiutati con parent_product: non si vendono, quindi il loro costo non coprirebbe nessuna vendita. Il costo va sulle loro variazioni.
  • È asincrona. Risponde 202 con status: "processing". Consulta GET /v1/cost-imports/{id} finché non indica finished, finished_with_errors o error; consultarla non costa nulla. Le righe con una cella più lunga di quanto ammette il modello tornano in not_sent e non vengono importate.
  • Resta nella cronologia dell'app, nella Cronologia dell'importazione dei costi di quell'account, come se l'avessi caricata dall'app.
  • Un account per importazione. Mentre il P&L di quell'account si sta ricalcolando per una modifica di costo precedente, risponde 409 senza importare nulla: aspetta che finisca e rilanciala.
  • Ogni riga applicata costa quanto scrivere il costo di un prodotto. Alla creazione si riservano le righe che possono essere applicate e, se il tuo saldo non basta, risponde 402 senza importare nulla. Alla fine si addebitano solo le righe applicate e il resto viene restituito: le righe rifiutate e quelle che non cambiavano nulla non costano. Solo nei piani che includono il costo prodotto, e richiede Idempotency-Key.
  • Anche acquisti. Con kind: "purchases" importa acquisti con il modello degli acquisti dell'app (sellerSku, marketplace, date, units, currency, productCost, inboundShippingCost, tariffCost, otherCost, stockOnHand, reference), solo negli account Seller. Il controllo degli acquisti verifica solo il formato di ogni riga (checks: "format") e rifiuta già le righe malformate: lo SKU, il suo gruppo di stock e lo stock si verificano all'applicazione, quindi qualche riga in più può essere rifiutata in quel momento. Ogni acquisto applicato costa quanto registrarlo singolarmente.

Scrivere spese proprie ​

Le tue spese proprie (personale, agenzia, 3PL, software…) si leggono con catalog:read e si scrivono con lo stesso permesso costs:write del costo prodotto. Sono le stesse che registri in Costi e spese → Spese proprie, e il P&L le sottrae fino all'utile netto.

RottaCosa fa
GET /v1/expensesLe tue spese, filtrabili per basis, status (active, upcoming o ended) e category
GET /v1/expenses/{id}Una spesa, con lo storico dei suoi importi per mese
POST /v1/expensesCrea una spesa
POST /v1/expenses/batchCrea fino a 100 spese in una volta, da un elenco o da un foglio caricato (file_id), o le verifica senza creare nulla
POST /v1/expenses/filesCarica un foglio di spese e restituisce il suo file_id, senza creare nulla. Si conserva 7 giorni. GET elenca quelli che hai caricato
PATCH /v1/expenses/{id}Cambia la voce o la categoria, o la termina con valid_to (null la riapre). Terminarla elimina i cambi di importo programmati dopo quel mese, e riaprirla non li recupera
POST /v1/expenses/{id}/amountsCambia l'importo da un mese; i precedenti mantengono il loro
DELETE /v1/expenses/{id}La elimina da tutto lo storico
GET /v1/expense-categoriesLe categorie standard e le tue
POST, PATCH e DELETE /v1/expense-categoriesCrea, rinomina o elimina una tua categoria. Una categoria usata da qualche spesa non si può eliminare

basis dice come si calcola ogni spesa: fixed (un importo fisso, con frequency monthly, quarterly, yearly o once e, in quest'ultimo caso, spread_months 1, 3, 6 o 12), per_unit (per unità venduta netta), pct_net_sales o pct_ad_spend (in punti: 5 è il 5 %). Le tre variabili accettano scope per applicarsi solo ad alcune connessioni o paesi.

Cinque cose da sapere prima della prima chiamata:

  • Per più di una spesa, il batch. POST /v1/expenses/batch ne crea fino a 100 in una volta. dry_run è obbligatorio: mandalo prima con true, che non scrive nulla né consuma crediti, e poi con false. È tutto o niente: se una spesa fallisce non ne viene creata nessuna, e failure_details dice quali e perché. possible_duplicates avvisa di quelle che somigliano a una che hai già o a un'altra dello stesso batch, senza bloccarle. Si addebitano solo le spese create.
  • Un foglio di spese, come file. Caricalo con POST /v1/expenses/files (.xlsx, .xls o .csv, fino a 8 MB e 1.000 righe) e manda il suo file_id al batch: si legge con le stesse regole dell'importazione dell'app. Se le sue colonne non si chiamano come quelle del modello, indica da quale arriva ogni dato con columns, e passa in type e currency il tipo e la valuta delle righe che non li hanno. Una riga che non si può leggere torna in failure_details come row N, e allora non si crea nulla.
  • Il P&L le sottrae subito. Le spese si calcolano quando si legge il P&L, quindi una creazione, una modifica o un'eliminazione si vede alla richiesta successiva, anche nei mesi già passati.
  • Ogni token tocca le spese delle sue connessioni. Un token che non raggiunge tutte le connessioni di vendita dell'account vede e modifica solo le spese delle sue, e non può creare spese di tutto l'account (le fisse e le variabili senza connessioni in scope) né rinominare o eliminare categorie: risponde 403, e nel batch quella riga torna in failure_details. Una spesa che non può vedere risponde 404.
  • Solo nei piani che includono il costo prodotto. In Free e Guru queste rotte rispondono 403, compreso il caricamento del file. Tutte le scritture, tranne il caricamento del file, richiedono Idempotency-Key.

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:

HeaderCos'è
X-Epinium-Credits-CostQuanto è costata questa chiamata
X-Epinium-Credits-RemainingQuanto ti resta. È approssimativo: se hai altre cose che consumano contemporaneamente, può discostarsi
X-Epinium-Credits-BreakdownIl dettaglio, per risorsa e prezzo unitario: product=100x1,country=100x0
X-Epinium-Credits-MaxIl 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:

json
{
  "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.

Epinium Documentation