A documentação a seguir descreve a

production.invoices tabela, um componente essencial da Veterinary Practice Data Platform. Esta tabela fornece acesso direto aos dados de faturas padronizados, testados e enriquecidos, ajudando-o a acelerar a análise e o reporte financeiro.

Referência detalhada das colunas

Identificadores principais

Coluna	Tipo	Descrição	Exemplos	Lógica de negócio
provet_id	STRING	O seu identificador único da prática	"pcus_1"	Chave de isolamento do tenant — filtre sempre por isto para obter desempenho
invoice_id	BIGINT	Identificador único da fatura dentro da prática	12345, 67890	Gerado pelo sistema, imutável após a criação
invoice_number	STRING	Número de fatura do negócio exibido aos clientes	"1001-2024-00123", "DEPT2-240915-456"	Formato: {department_id}-{date}-{sequence}. NULL até a fatura estar finalizada (status=3)

Classificação da fatura

Coluna	Tipo	Descrição	Exemplos	Lógica de negócio
invoice_type	STRING	Categoria da fatura derivada	"consultation", "countersale", "credit_note"	Lógica: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	Referência relacionada da consulta	98765, NULL	Liga-se ao registo da consulta. NULL para vendas ao balcão e notas de crédito
invoice_status	STRING	Estado atual da fatura	"pending", "paid", "cancelled"	Mapeamento: 0=Rascunho, 1=Enviado, 2=Aberto, 3=Finalizado, 4=Faturação, 99=Anulado. Nota: "pending"/"paid"/"cancelled" são termos de negócio simplificados

Informações financeiras

Coluna	Tipo	Descrição	Exemplos	Lógica de negócio
total_incl_vat	DECIMAL	Montante total incluindo IVA/imposto	125.50, 89.99	Montante final faturável incluindo todos os impostos
total_excl_vat	DECIMAL	Montante total excluindo IVA/imposto	100.40, 74.99	Valor base antes dos cálculos de imposto
amount_due	DECIMAL	Saldo em aberto remanescente	125.50, 0.00, 25.00	Reduz à medida que são aplicados pagamentos. 0.00 = totalmente pago
currency_code	STRING	Código de moeda ISO 4217	"EUR", "USD", "GBP", "CAD"	Mapeado automaticamente a partir do país da clínica
currency_name	STRING	Nome completo da moeda	"Euro", "US Dollar", "British Pound Sterling"	Descrição da moeda legível

Informações do cliente e do veterinário

Coluna	Tipo	Descrição	Exemplos	Lógica de negócio
client_name	STRING	Nome do cliente/pagador	"John Smith", "Pet Insurance Co", "Sarah Johnson"	A partir do campo payer_name nos dados de origem
supervising_veterinarian_name	STRING	Nome completo do veterinário supervisor	"Dr. Emily Watson", "Michael Chen DVM", NULL	Lógica: `first_name

Detalhes do método de pagamento

Coluna	Tipo	Descrição	Exemplos	Lógica de negócio
payment_method_type	STRING	Categoria de pagamento padronizada	"Card", "Cash or Check", "Digital Wallet", "Financing"	Lógica de categorização automática: Card flag → "Card", palavras-chave Cash/Check → "Cash or Check", CareCredit/Scratchpay → "Financing", etc.
payment_method_name	STRING	Nome original do método de pagamento	"Visa Credit Card", "Cash", "CareCredit"	Nome bruto do sistema de gestão da prática
payment_method_name_standardized	STRING	Nome padronizado do pagamento	"Visa", "Cash", "CareCredit"	Lógica de padronização: correspondência de padrões (p.ex., '%visa%' → 'Visa', '%mastercard%' → 'Mastercard')

Informações da clínica e da localização

Coluna	Tipo	Descrição	Exemplos	Lógica de negócio
department_id	BIGINT	Identificador do departamento/clínica	1001, 2005	Liga-se a localizações específicas da clínica
department_name	STRING	Nome do departamento/clínica	"Main Street Veterinary", "Emergency Clinic Downtown"	Nome comercial para a localização
department_timezone	STRING	Identificador de fuso horário IANA	"America/New_York", "Europe/London", "Australia/Sydney"	Usado para conversões de hora local

Campos de data (datas do negócio)

Coluna	Tipo	Descrição	Exemplos	Lógica de negócio
created_date	DATE	Data de criação da fatura	2024-09-15, 2024-08-22	Parte da data do carimbo de data/hora de criação
invoice_date	DATE	Data oficial da fatura	2024-09-15, 2024-08-22	Data do negócio exibida na fatura
invoice_due_date	DATE	Data de vencimento do pagamento	2024-10-15, 2024-09-22	Quando se espera o pagamento
invoice_paid_date	DATE	Data em que o pagamento foi recebido	2024-09-20, NULL	NULL para faturas não pagas

Carimbos de data/hora UTC (horas do sistema)

Coluna	Tipo	Descrição	Exemplos	Lógica de negócio
created_ts_utc	TIMESTAMP	Carimbo de data/hora de criação (UTC)	2024-09-15 14:30:25.123	Hora de criação do sistema em UTC
invoice_date_ts_utc	TIMESTAMP	Carimbo de data/hora da fatura (UTC)	2024-09-15 12:00:00.000	Data da fatura convertida para UTC
invoice_due_date_ts_utc	TIMESTAMP	Carimbo de data/hora de vencimento (UTC)	2024-10-15 23:59:59.000	Data de vencimento convertida para UTC
invoice_paid_date_ts_utc	TIMESTAMP	Carimbo de data/hora do pagamento (UTC)	2024-09-20 16:45:30.456, NULL	Hora de recebimento do pagamento em UTC

Carimbos de data/hora locais (fuso horário do departamento)

Coluna	Tipo	Descrição	Exemplos	Lógica de negócio
created_ts_local	TIMESTAMP	Carimbo de data/hora de criação (local)	2024-09-15 10:30:25.123
invoice_date_ts_local	TIMESTAMP	Carimbo de data/hora da fatura (local)	2024-09-15 08:00:00.000
invoice_due_date_ts_local	TIMESTAMP	Carimbo de data/hora de vencimento (local)	2024-10-15 19:59:59.000
invoice_paid_date_ts_local	TIMESTAMP	Carimbo de data/hora do pagamento (local)	2024-09-20 12:45:30.456, NULL

Padrões comuns de consulta

Análise de receita

-- Receita mensal por método de pagamentoSELECT     DATE_TRUNC('month', invoice_date) as month,    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;

Contas a receber em aberto

-- Análise de envelhecimento (aging) de faturas não pagasSELECT     CASE         WHEN DATEDIFF(CURRENT_DATE(), invoice_due_date) <= 0 THEN 'Current'        WHEN DATEDIFF(CURRENT_DATE(), invoice_due_date) <= 30 THEN '1-30 days'        WHEN DATEDIFF(CURRENT_DATE(), invoice_due_date) <= 60 THEN '31-60 days'        ELSE 'Over 60 days'    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;

Desempenho do veterinário

-- Principais veterinários com base na receita de consultaSELECT     supervising_veterinarian_name,    COUNT(DISTINCT invoice_id) as consultations,    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;

Notas de utilização importantes

Gestão de múltiplas moedas

Inclua sempre currency_code ao agregar dados financeiros entre departamentos:

-- 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  -- Pode misturar EUR + USD + GBPFROM production.invoices;

Boas práticas de fuso horário

Use os campos *_ts_local para reporte do negócio e interfaces do utilizador
Use os campos *_ts_utc para integração do sistema e processamento de dados
Considere sempre o fuso horário do departamento ao interpretar carimbos de data/hora locais