Video Central

Il set di dati di vendita TVOD fornisce dati di vendita a livello di transazione per la tua attività di video transazionale di video on demand (TVOD) di Prime Video. Ogni record rappresenta una transazione completata (acquisto o noleggio). I dati vengono forniti come changelog di sola aggiunta tramite l’API Slate Datasets, che ti offre la flessibilità completa per creare analisi personalizzate e calcolare metriche su misura per le tue esigenze aziendali.

Vantaggi principali

Informazioni più rapide: i dati di vendita vengono raggruppati più volte al giorno, e la maggior parte delle transazioni viene effettuata entro circa 9 ore dal completamento.
Separazione dei costi e delle vendite: i segnali di vendita arrivano in lotti di 4 ore; le informazioni sui costi (net_cogs) vengono aggiornate ogni giorno, in modo da ricevere segnali di fatturato il più velocemente possibile.
Coerenza: formattazione standardizzata in tutti i territori in un’unica fonte.
Inserimento semplificato: modello di log delle modifiche in sola aggiunta con un semplice schema di upsert per un’integrazione automatica e immediata.
Granularità a livello di transazione: accedi ai singoli dati a livello di ordine per potenziare analisi personalizzate, monitoraggio delle prestazioni a livello di titolo e integrazioni di sistema interne.
Integrazione flessibile: integra i dati di vendita TVOD con i sistemi interni, i data warehouse e gli strumenti di BI.

Funzionalità	API Slate Datasets
Tipo di accesso	Programmatico (API REST)
Ideale per	Pipeline automatizzate, reportistica aziendale, analisi personalizzate
Autenticazione	Accedi con il profilo di sicurezza di Amazon (LWA)
Formato dei dati	File CSV (compressi con gzip)

Guida introduttiva

Prerequisiti

Collaborazione attiva con Prime Video TVOD
Un accesso con Amazon (LWA) Security Profile
ID cliente registrato presso il Content Account Manager (CAM)
Un codice di autorizzazione per richiedere un token
Un token di autenticazione LWA valido per tutte le richieste API

Configurazione dell’autenticazione
Per recuperare i set di dati è necessario prima effettuare l’onboarding alla suite di API Datasets. Maggiori dettagli possono essere trovati qui.

Endpoint API

Discovery Endpoints
Utilizza questi endpoint per cercare gli ID degli account e dei contratti in modo programmatico:

Endpoint	Restituisce
OTTIENI /v2/accounts	Elenco degli account Slate a cui puoi accedere
OTTIENI /v2/accounts/ {ACADIA_ID}	Linee di business disponibili (ad es. canali, transazioni)
OTTIENI /v2/accounts/ {ACADIA_ID} /transactions	Elenco degli ID dei contratti TVOD presenti nel tuo account
OTTIENI /v2/accounts/ {ACADIA_ID} /transactions/ {CONTRACT_ID} /datasets	Set di dati disponibili per un contratto

Recupero dei file del set di dati
Utilizza questo endpoint per recuperare i collegamenti ai file del set di dati delle transazioni per il tuo contratto:

Parametri della richiesta

Parametro	Description
ACADIA_ID	L’ID del tuo account Slate. Trovalo usando GET /v2/accounts.
ID_CONTRATTO	Il tuo ID del contratto TVOD.
Data/ora di inizio	Imposta l’ultima volta che hai tirato. Formato: aaaa-mm-ggthh:mm:ssz (UTC).
Data e ora di fine	Imposta sull’ora corrente. Formato: aaaa-mm-ggthh:mm:ssz (UTC).
limite	Massimo 1000 link per pagina.

Questo endpoint restituisce collegamenti a file CSV scaricabili (compressi con gzip) che contengono i registri delle transazioni, non le transazioni dirette.

Impaginazione Tutte le
risposte sono suddivise in pagine. Utilizza i seguenti parametri di interrogazione per navigare tra i risultati:

Parametro	Predefinito	Description
limite	10	Numero di documenti restituiti per pagina. Massimo 1000.
compensare	0	Numero di pagine da saltare.

Tutti le risposte suddivise in pagine contengono i seguenti campi:

Campo	Description
totale	Numero totale di documenti su tutte le pagine.
prossimo	URL alla pagina successiva. Null se si trova nell’ultima pagina.

Modello di dati

Concetti chiave

Concetto	Description
Transazione	Un evento relativo all’ordine completato (acquisto o noleggio). Ogni transazione è identificata da un order_item_id univoco.
Modello Changelog	I dati possono essere aggiunti solo. Se gli attributi di un record cambiano (ad esempio, arriva il costo), viene pubblicato un nuovo record con lo stesso order_item_id ma un nuovo last_update_time_utc.
Chiave primaria	order_item_id è l’identificatore univoco per ogni transazione. Esegui sempre la deduplicazione su questo campo.
Costo vs. vendite	I dati di vendita arrivano in lotti di 4 ore. Il calcolo dei costi (net_cogs) viene aggiornato ogni giorno, quindi i record vengono aggiornati con i costi quando disponibili.

Freschezza dei dati

Attributo	Obiettivo
Fornitura dei dati di vendita	Ogni 4 ore (in batch)
Aggiornamento dei costi (net_cogs)	Ogni 24 ore
Latenza end-to-end	~ 9 ore dalla transazione alla disponibilità dei dati
Conservazione dei dati	Massimo 2 anni

Precisione dei dati

Attributo	Dettagli
Fonte della verità	Gli utili e i rendiconti finanziari rimangono l’ultima fonte di verità per i pagamenti e la determinazione dei costi.
Varianza prevista	È possibile che esistano lievi variazioni dovute alle sfumature tra data e ora e alle differenze di aggregazione rispetto ai report finanziari/sulle royalty.
Ambito	Completata la procedura di transazione per il monitoraggio delle prestazioni. Non sostituisce i report finanziari o sulle royalty.

Questo set di dati è progettato per un monitoraggio delle prestazioni più rapido e continuo. Aspettatevi variazioni minori rispetto ai report finanziari (ad esempio, Video ASIN Daily Level Summary) a causa delle sfumature tra data e ora e delle differenze di aggregazione. Si tratta di un comportamento previsto, non di un problema di qualità dei dati.

Definizioni dei dati

Campi principali
La tabella seguente descrive tutti i campi disponibili nel set di dati transactions_event_log:

Nome campo	Type	Annullabile	Description	Esempio
order_item_id	CORDA	No	Identificatore univoco per ogni transazione. Chiave primaria per la deduplicazione.	ABC123.XYZ.
transaction_datetime_utc	TIMESTAMP	No	Orario della transazione in UTC.	2026-01-14T 00:04:41.575
transaction_datetime_local	TIMESTAMP	No	Ora della transazione nel fuso orario locale.	2026-01-14T 01:04:41.575
pv_title_id	CORDA	No	Identificatore univoco del titolo.	tt1234567
tipo_contenuto	CORDA	No	Type di contenuto acquistato.	Film, Episodio TV, Stagione TV
tipo_acquisto	CORDA	No	Indicatore di acquisto o noleggio.	EST (acquisto), VOD (noleggio)
qualità_dei contenuti	CORDA	No	Livello di qualità video.	SD, HD, UHD
territorio	CORDA	No	Codice del Territorio.	USA, GB, DE, JP, AU
classe del dispositivo	CORDA	sì	Categoria di dispositivo.	Fire TV, dispositivi mobili, Web
nome_titolo	CORDA	No	Nome del titolo.	La grande avventura
moneta	CORDA	No	Codice valuta ISO 4217.	USD, EUR, JPY
vendor_sku	CORDA	sì	SKU fornito dal partner.	WB-MOV-001
netcogs	DECIMALE	sì	Costo netto della merce venduta, IVA esclusa. Si rinfresca ogni giorno. Inizialmente può essere NULL.	4,99
ricavi netti	DECIMALE	No	Entrate nette, tasse escluse.	14,99
create_time_utc	TIMESTAMP	No	Registra l’ora di creazione in UTC.	2026-01-14T 01:39:06.619
time_last_update_utc	TIMESTAMP	No	Registra l’ora dell’ultimo aggiornamento. Utilizzato per la logica di deduplicazione.	2026-01-14T 01:39:06.619

Note sul campo
I seguenti campi presentano importanti caratteristiche comportamentali di cui i partner devono essere consapevoli:

Campo	Calcolo/Logica	Note
net_cogs	Si aggiorna ogni giorno	Inizialmente può apparire come NULL o 0; si aggiorna entro 24 ore dall’arrivo dei costi.
last_update_time_utc	L’ultimo timestamp vince	Quando esistono più record per lo stesso order_item_id, conserva solo il record con la data last_update_time_utc più recente.
territorio	Un unico set di dati per tutti i territori	Nessun file per territorio; filtra per codice territoriale, se necessario.
tipo_acquisto	Valori enum fissi	EST = Electronic Sell-Through (acquisto permanente). VOD = noleggio a tempo limitato.

Deduplicazione

Panoramica
Il set di dati utilizza un modello di log delle modifiche. Quando un record viene aggiornato (ad esempio, arriva la determinazione dei costi), viene pubblicata una nuova versione con lo stesso order_item_id e un last_update_time_utc più recente. Per mantenere dati accurati, applica sempre la logica di deduplicazione prima di scrivere i record nella destinazione.

Query di deduplicazione
Utilizza il seguente modello SQL per deduplicare e conservare solo la versione più recente di ogni transazione:

Upsert Pattern
Utilizzate questo modello per mantenere una tabella locale con lo stato più recente di ogni transazione:

Pipeline ETL

Panoramica
Segui questo processo in quattro fasi per creare una pipeline di ingestione affidabile e automatizzata per i dati di vendita TVOD.

Fasi della pipeline

Estrazione iniziale dei dati: recupera tutti i file del contratto entro l’intervallo di tempo desiderato utilizzando l’endpoint API. Scarica tutti i file restituiti. Ogni file contiene i record delle transazioni in formato CSV (compresso con gzip).
Deduplicazione: quando esistono più record per lo stesso order_item_id durante l’elaborazione di più giorni di dati, conserva solo il record last_update_time_utc più recente utilizzando la query di deduplicazione nella Sezione 6.2.
Converti in destinazione: unisci i record deduplicati nella tabella di destinazione utilizzando order_item_id come chiave. Vedi lo schema upsert nella Sezione 6.3.
Elaborazione incrementale: per caricamenti di dati continui, imposta startDateTime sull’ultima volta che hai estratto e endDateTime sull’ora corrente. Elabora tutti i file restituiti e trasferiscili nella tua destinazione.

Imposta i seguenti parametri per le esecuzioni incrementali:

Cadenza di ingestione consigliata

raccomandazione	Dettagli
Cadenza consigliata	Ogni 4-6 ore per rimanere il più aggiornato possibile.
Strategia di elaborazione incrementale	Imposta startDateTime sull’ultimo timestamp recuperato e endDateTime sull’ora corrente. Elabora tutti i file restituiti.
Consumatori giornalieri/settimanali	Se esegui il recupero giornalmente o settimanalmente, assicurati di elaborare tutti i file per l’intero periodo per evitare la perdita di record.
Ora di inizio consigliata	Per le attività quotidiane, inizia alle 1:00 UTC per registrare i lavori completati il giorno precedente.

Domande di esempio

Usa questi modelli SQL per iniziare con i casi d’uso comuni di analisi. Sostituisci [START_DATE], [END_DATE] e [X] con i valori desiderati.

I 10 migliori titoli per fatturato in un periodo

Ricavi totali per Tipo di acquisto

Riepilogo delle vendite giornaliere

Entrate per Territorio

Standard di Qualità

Obiettivi di Qualità dei Dati

Dimensione della Qualità	Obiettivo	Misurazione
Completezza	> 99% delle transazioni acquisite	Confronto con i report finanziari
Tempestività	~ 9 ore di latenza end-to-end	Tempo che intercorre tra la transazione e la disponibilità dei dati
Coerenza	Formato unico standardizzato	Tutti i territori in un unico set di dati

Limitazioni note

Limitazione	Description	Impatto
Ritardo nella determinazione dei costi	net_cogs si aggiorna ogni giorno, non in tempo reale.	I record possono inizialmente mostrare un costo NULL o 0; gli aggiornamenti vengono aggiornati entro 24 ore.
Conservazione dei dati	Massimo 2 anni di dati storici.	Le richieste con timestamp più vecchi di 2 anni non restituiranno risultati.
Scadenza del token	I token di accesso LWA scadono dopo 1 ora.	È necessario implementare la logica dei token di aggiornamento per un accesso ininterrotto.
Distribuzione basata su file	L’API restituisce collegamenti ai file, non righe di dati dirette.	Richiede una fase di download nella pipeline prima dell’elaborazione.
Dati finanziari	Varianza minore rispetto ai rapporti finanziari/sulle royalty.	Comportamento previsto dovuto a differenze tra data e ora, non a un problema di qualità dei dati.

Domande frequenti

Questo set di dati fornisce gli ordini completati nel corso della transazione per un monitoraggio delle prestazioni più rapido e continuo. Non sostituisce i report finanziari o sulle royalty. Gli utili e i rendiconti finanziari rimangono l’ultima fonte di verità per i pagamenti e la determinazione dei costi. Aspettatevi variazioni minori dovute alle sfumature tra data e ora e alle differenze di aggregazione.

API del set di dati di vendita TVOD