Video Central

Il set di dati sulle vendite TVOD fornisce dati di vendita a livello di transazione per la tua attività di video transazionale 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 per set di dati Slate, offrendoti la massima flessibilità per creare analisi personalizzate e calcolare metriche su misura per le tue esigenze aziendali.

Principali vantaggi

Informazioni più rapide: i dati di vendita vengono raggruppati più volte al giorno, con la maggior parte delle transazioni consegnate entro circa 9 ore dal completamento.
Separazione costi e vendite: i segnali di vendita arrivano in batch di 4 ore; le informazioni sui costi (net_cogs) si aggiornano quotidianamente, in modo da ottenere segnali di fatturato il più velocemente possibile.
Coerenza: formattazione standardizzata in tutti i territori in un’unica fonte.
Inserimento semplificato: modello changelog di sola aggiunta con un semplice schema di upsert per l’inserimento manuale e automatico.
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 tuoi sistemi interni, data warehouse e strumenti di BI.

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

Introduzione

Prerequisiti

Collaborazione attiva con Prime Video TVOD
Un accesso con il profilo di sicurezza Amazon (LWA)
ID cliente registrato presso il tuo 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 devi prima eseguire l’onboarding nella suite API Dataset. Maggiori dettagli sono disponibili qui.

Endpoint API

Endpoint di scoperta
Utilizza questi endpoint per cercare gli ID del tuo account e del contratto in modo programmatico:

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

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

Parametri della richiesta

Parametro	Descrizione
ACADIA_ID	L’ID del tuo account Slate. Trovalo usando GET /v2/accounts.
CONTRACT_ID	L’ID del tuo contratto TVOD.
startDateTime	Impostato sull’ultima volta che hai estratto. Formato: AAAA-MM-GGThh:mm:ssZ (UTC).
endDateTime	Impostato sull’ora corrente. Formato: AAAA-MM-GGThh:mm:ssZ (UTC).
limite	Massimo 1000 link per pagina.

Questo endpoint restituisce i collegamenti ai file CSV scaricabili (compressi con gzip) che contengono i log delle transazioni, non direttamente le transazioni.

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

Parametro	Default	Descrizione
limite	10	Numero di documenti restituiti per pagina. Massimo 1000.
offset	0	Numero di pagine da saltare.

Tutte le risposte impaginate contengono i seguenti campi:

Campo	Descrizione
total	Numero totale di documenti su tutte le pagine.
next	L’URL della pagina successiva. Null se si trova nell’ultima pagina.

Modello di dati

Concetti chiave

Concetto	Descrizione
Transazione	Un evento di ordine completato (acquisto o noleggio). Ogni transazione è identificata da un order_item_id univoco.
Modello Changelog	I dati sono di sola aggiunta. 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 last_update_time_utc più recente.
Chiave primaria	order_item_id è l’identificatore univoco per ogni transazione. Deduplica sempre su questo campo.
Costo vs. Vendite	I dati di vendita arrivano in batch di 4 ore. La determinazione dei costi (net_cogs) si aggiorna quotidianamente, quindi i record vengono aggiornati con i costi quando disponibili.

Attualità dei dati

Attributo	Target
Consegna 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

Accuratezza dei dati

Attributo	Dettagli
Fonte di verità	Gli utili e i rendiconti finanziari rimangono l’ultima fonte di verità per i pagamenti e i costi.
Varianza prevista	Potrebbe esserci una varianza minore a causa della sfumatura tra data e ora e delle differenze di aggregazione rispetto ai report finanziari/sulle royalty.
Ambito	Ordini completati al momento della 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. Aspettati variazioni minori rispetto ai report finanziari (ad esempio, Video ASIN Daily Level Summary) a causa della sfumatura 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	Tipo	Annullabile	Descrizione	Esempio
id_articolo_ordine	STRINGA	No	Identificatore univoco per ogni transazione. Chiave primaria per la deduplicazione.	ABC123XYZ
transaction_datetime_utc	TIMESTAMP	No	Tempo di transazione in UTC.	2026-01-14T 00:04:41.575
transazione_datetime_local	TIMESTAMP	No	Ora della transazione nel fuso orario locale.	2026-01-14T 01:04:41.575
pv_title_id	STRINGA	No	Identificatore univoco del titolo.	tt1234567
content_type	STRINGA	No	Tipo di contenuto acquistato.	Film, episodio TV, stagione televisiva
purchase_type	STRINGA	No	Indicatore di acquisto o noleggio.	EST (acquisto), VOD (noleggio)
content_quality	STRINGA	No	Livello di qualità video.	SD, HD, UHD
territory	STRINGA	No	Codice territorio	US, GB, DE, JP, AU
device_class	STRINGA	Sì	Categoria di dispositivo.	Fire TV, dispositivi mobili, Web
nome_titolo	STRINGA	No	Nome del titolo.	La grande avventura
Valuta	STRINGA	No	Codice valuta ISO 4217	USD, EUR, JPY
vendor_sku	STRINGA	Sì	SKU fornito dal partner.	WB-MOV-001
net_cogs	DECIMALE	Sì	Costo netto della merce venduta, IVA esclusa. Si aggiorna ogni giorno. Inizialmente può essere NULL.	4,99
net_revenue	DECIMALE	No	Ricavi netti, tasse escluse.	14,99
create_time_utc	TIMESTAMP	No	Registra l’ora di creazione in UTC.	2026-01-14T01:39:06.619
last_update_time_utc	TIMESTAMP	No	Registra l’ora dell’ultimo aggiornamento. Utilizzato per la logica di deduplicazione.	2026-01-14T01:39:06.619

Note sul campo
I seguenti campi presentano importanti caratteristiche comportamentali che i partner dovrebbero conoscere:

Campo	Calcolo/Logica	Note
net_cogs	Si aggiorna ogni giorno	Può inizialmente apparire come NULL o 0; si aggiorna entro 24 ore dall’arrivo della determinazione dei costi.
last_update_time_utc	L’ultimo timestamp è quello valido	Quando esistono più record per lo stesso subscription_event_id, conserva solo il record con il più recente last_update_time_utc.
territory	Un unico set di dati per tutti i territori	Nessun file per territorio; filtra per codice territoriale in base alle necessità.
purchase_type	Valori enum fissi	EST = Electronic Sell-Through (acquisto permanente). VOD = noleggio a tempo limitato.

Deduplicazione

Panoramica
Il set di dati utilizza un modello changelog. 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 a destinazione.

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

Modello Upsert
Usa 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.
Upsert to Destination: unisce i record deduplicati nella tabella di destinazione utilizzando order_item_id come chiave. Vedere lo schema di upsert nella Sezione 6.3.
Elaborazione incrementale: per i carichi di dati continui, imposta startDateTime sull’ultima volta che hai eseguito l’estrazione 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 recuperi giornalmente o settimanalmente, assicurati di elaborare tutti i file per l’intero periodo per evitare la perdita di record.
Ora di inizio consigliata	Per i lavori giornalieri, inizia alle 1:00 UTC per acquisire i completamenti del giorno precedente.

Query di esempio

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

I primi 10 titoli per fatturato in un periodo

Ricavi totali per tipo di acquisto

Riepilogo giornaliero delle vendite

Entrate per territorio

Standard di qualità

Obiettivi di qualità dei dati

Dimensione della qualità	Target	Misurazione
Completezza	> 99% delle transazioni acquisite	Confronto con i report finanziari
Tempestività	~9 ore di latenza end-to-end	Tempo dalla transazione alla disponibilità dei dati
Coerenza	Formato unico standardizzato	Tutti i territori in un unico set di dati

Limitazioni note

Limitazione	Descrizione	Impatto
Ritardo nella determinazione dei costi	net_cogs si aggiorna giornalmente, non in tempo reale.	I record possono inizialmente mostrare un costo NULL o 0; si aggiorna entro 24 ore.
Conservazione dei dati	Massimo 2 anni di dati storici.	Le richieste con timestamp più vecchi di 2 anni non daranno risultati.
Scadenza del token	I token di accesso LWA scadono dopo 1 ora.	È necessario implementare la logica del 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.
Varianza finanziaria	Varianza minore rispetto ai report finanziari/sulle royalty.	Comportamento previsto dovuto a sfumature tra data e ora; non 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