La documentazione seguente descrive la

tabella production.invoices, un componente fondamentale della Veterinary Practice Data Platform. Questa tabella offre accesso diretto a dati di fatturazione standardizzati, testati e arricchiti, per aiutarvi ad accelerare le analisi e la reportistica finanziaria.

Riferimento dettagliato delle colonne

Identificatori principali

Colonna	Tipo	Descrizione	Esempi	Logica aziendale
provet_id	STRING	Identificatore univoco della clinica	"pcus_1"	Chiave di isolamento tenant: filtrare sempre per questa per le prestazioni
invoice_id	BIGINT	Identificatore univoco della fattura all’interno della clinica	12345, 67890	Generato dal sistema, immutabile una volta creato
invoice_number	STRING	Numero fattura visibile ai clienti	"1001-2024-00123", "DEPT2-240915-456"	Formato: {department_id}-{date}-{sequence}. NULL fino a quando la fattura non è finalizzata (status=3)

Classificazione della fattura

Colonna	Tipo	Descrizione	Esempi	Logica aziendale
invoice_type	STRING	Categoria fattura derivata	"consultation", "countersale", "credit_note"	Logica:CASE WHEN countersale=1 THEN 'Countersale' WHEN credit_note=0 THEN 'Consultation' WHEN credit_note=1 THEN 'Credit Note' ELSE 'Unknown' END
consultation_id	BIGINT	Riferimento alla visita associata	98765, NULL	Collegamenti alla registrazione della visita. NULL per vendite libere e note di credito
invoice_status	STRING	Stato attuale della fattura	"pending", "paid", "cancelled"	Mappatura: 0=Pro forma, 1=Inviato, 2=Aperto, 3=Finalizzato, 4=Fatturazione, 99=Annullato. Nota: "pending"/"paid"/"cancelled" sono termini aziendali semplificati

Informazioni finanziarie

Colonna	Tipo	Descrizione	Esempi	Logica aziendale
total_incl_vat	DECIMALE	Importo totale inclusivo di Iva/tassa	125.50, 89.99	Importo totale fatturabile finale inclusivo di tutte le tasse
total_excl_vat	DECIMALE	Importo totale esclusivo di Iva/tassa	100.40, 74.99	Importo di base prima dei calcoli della tassa
amount_due	DECIMALE	Saldo in sospeso rimanente	125.50, 0.00, 25.00	Si riduce man mano che vengono applicati i pagamenti. 0.00 = interamente pagato
currency_code	STRING	Codice valuta ISO 4217	"EUR", "USD", "GBP", "CAD"	Mappato automaticamente dal paese della struttura
currency_name	STRING	Nome completo della valuta	"Euro", "US Dollar", "British Pound Sterling"	Descrizione valuta leggibile

Informazioni su Cliente e Veterinario

Colonna	Tipo	Descrizione	Esempi	Logica aziendale
client_name	STRING	Nome Cliente/pagante	"John Smith", "Pet Insurance Co", "Sarah Johnson"	Da campo payer_name nei dati di origine
supervising_veterinarian_name	STRING	Nome completo del Veterinario Supervisore	"Dr. Emily Watson", "Michael Chen DVM", NULL	Logica: `first_name

Dettagli del metodo di pagamento

Colonna	Tipo	Descrizione	Esempi	Logica aziendale
payment_method_type	STRING	Categoria di pagamento standardizzata	"Card", "Cash or Check", "Digital Wallet", "Financing"	Logica di categorizzazione automatica: flag Card → "Card", parole chiave Cash/Check → "Cash or Check", CareCredit/Scratchpay → "Financing", ecc.
payment_method_name	STRING	Nome del metodo di pagamento originale	"Visa Credit Card", "Cash", "CareCredit"	Nome grezzo dal sistema di gestione della clinica
payment_method_name_standardized	STRING	Nome del metodo di pagamento standardizzato	"Visa", "Cash", "CareCredit"	Logica di standardizzazione: corrispondenza di pattern (es., '%visa%' → 'Visa', '%mastercard%' → 'Mastercard')

Informazioni su struttura e ubicazione

Colonna	Tipo	Descrizione	Esempi	Logica aziendale
department_id	BIGINT	Identificatore della struttura/clinica	1001, 2005	Collegamenti a specifiche ubicazioni della clinica
department_name	STRING	Nome struttura/clinica	"Main Street Veterinary", "Emergency Clinic Downtown"	Nome aziendale per l’ubicazione
department_timezone	STRING	Identificatore fuso orario IANA	"America/New_York", "Europe/London", "Australia/Sydney"	Usato per conversioni orario locali

Campi data (date aziendali)

Colonna	Tipo	Descrizione	Esempi	Logica aziendale
created_date	DATA	Data di creazione della fattura	2024-09-15, 2024-08-22	Parte data del timestamp di creazione
invoice_date	DATA	Data ufficiale della fattura	2024-09-15, 2024-08-22	Data aziendale mostrata nella fattura
invoice_due_date	DATA	Data di scadenza del pagamento	2024-10-15, 2024-09-22	Quando ci si aspetta il pagamento
invoice_paid_date	DATA	Data di ricezione del pagamento	2024-09-20, NULL	NULL per fatture non pagate

Timestamp UTC (orari di sistema)

Colonna	Tipo	Descrizione	Esempi	Logica aziendale
created_ts_utc	TIMESTAMP	Timestamp di creazione (UTC)	2024-09-15 14:30:25.123	Orario di creazione del sistema in UTC
invoice_date_ts_utc	TIMESTAMP	Timestamp della fattura (UTC)	2024-09-15 12:00:00.000	Data fattura convertita in UTC
invoice_due_date_ts_utc	TIMESTAMP	Timestamp di scadenza (UTC)	2024-10-15 23:59:59.000	Data di scadenza convertita in UTC
invoice_paid_date_ts_utc	TIMESTAMP	Timestamp del pagamento (UTC)	2024-09-20 16:45:30.456, NULL	Orario di ricezione del pagamento in UTC

Timestamp locali (fuso orario della struttura)

Colonna	Tipo	Descrizione	Esempi	Logica aziendale
created_ts_local	TIMESTAMP	Timestamp di creazione (locale)	2024-09-15 10:30:25.123
invoice_date_ts_local	TIMESTAMP	Timestamp della fattura (locale)	2024-09-15 08:00:00.000
invoice_due_date_ts_local	TIMESTAMP	Timestamp di scadenza (locale)	2024-10-15 19:59:59.000
invoice_paid_date_ts_local	TIMESTAMP	Timestamp del pagamento (locale)	2024-09-20 12:45:30.456, NULL

Pattern di query comuni

Analisi delle entrate

-- Monthly revenue by payment methodSELECT     DATE_TRUNC('month', invoice_date) as mese,    payment_method_type,    COUNT(*) as invoice_count,    SUM(total_incl_vat) as revenue,    currency_codeFROM production.invoices WHERE provet_id = 'your_practice_id'    AND invoice_status IN ('paid', 'finalized')    AND invoice_date >= '2024-01-01'GROUP BY 1, 2, 5ORDER BY 1 DESC, 4 DESC;

Esigibili in sospeso

-- Aging analysis of unpaid invoicesSELECT     CASE         WHEN DATEDIFF(CURRENT_DATE(), invoice_due_date) <= 0 THEN 'Current'        WHEN DATEDIFF(CURRENT_DATE(), invoice_due_date) <= 30 THEN '1-30 giorni'        WHEN DATEDIFF(CURRENT_DATE(), invoice_due_date) <= 60 THEN '31-60 giorni'        ELSE 'Over 60 giorni'    END as aging_bucket,    COUNT(*) as invoice_count,    SUM(amount_due) as total_outstanding,    currency_codeFROM production.invoicesWHERE provet_id = 'your_practice_id'    AND amount_due > 0GROUP BY 1, 4ORDER BY 1;

Performance del Veterinario

-- Top performing veterinarians by consultation revenueSELECT     supervising_veterinarian_name,    COUNT(DISTINCT invoice_id) as consultazioni,    SUM(total_incl_vat) as total_revenue,    AVG(total_incl_vat) as avg_consultation_value,    currency_codeFROM production.invoicesWHERE provet_id = 'your_practice_id'    AND invoice_type = 'consultation'    AND supervising_veterinarian_name IS NOT NULL    AND invoice_date >= DATE_SUB(CURRENT_DATE(), 30)GROUP BY 1, 5ORDER BY 3 DESC;

Note importanti sull’utilizzo

Gestione multivaluta

Quando sommi i dati finanziari tra strutture, includi sempre currency_code:

-- CORRECT: Group by currencySELECT currency_code, SUM(total_incl_vat) as revenueFROM production.invoices GROUP BY currency_code;-- INCORRECT: Mixing currenciesSELECT SUM(total_incl_vat) as revenue  -- May mix EUR + USD + GBPFROM production.invoices;

Best practice per il fuso orario

Usa i campi *_ts_local per reportistica aziendale e interfacce utente
Usa i campi *_ts_utc per integrazione di sistema e elaborazione dei dati
Considera sempre il fuso orario della struttura quando interpreti i timestamp locali