================================================================================
BrightInvoicesController - Summary & Response Structures
File: SonWinCommonAPI/Controllers/BrightInvoicesController.cs
================================================================================
--------------------------------------------------------------------------------
WHAT THE CONTROLLER DOES
--------------------------------------------------------------------------------
Exposes a single read-only endpoint that returns a customer's invoices within a date range.
The domain is SonWin billing: invoice header rows live in Sonlinc.AKOND, enriched with supply type (AUDEBFORS), PBSI payment rows (also in AKOND), and a "has a rendered PDF" existence check (AKONDDOC -> BDOC).
The result is mapped into the Bright-facing BrightInvoice model.
Visibility/filtering is configuration-driven. Each filter toggle is resolved as "local appsettings config wins, otherwise defer to the company's BCHEC flag"
(Sonlinc.BCHED, cached in memory). The SQL is assembled from pure-SQL fragments so only the active clauses appear in the executed statement.
--------------------------------------------------------------------------------
METHODS
--------------------------------------------------------------------------------
1) GetInvoices
Route: GET accounts/{accountId}/invoices
Auth: [Authorize] (class-level); [ApiController]
Params:
Body: none (GET)
Returns:
What it does:
Validates the customer and the input range, resolves the company's invoice visibility filters, runs the list query, and maps each row to a BrightInvoice.
Returns the (possibly empty) list with 200.
Validation that affects the result (all failures THROW -> surface as HTTP 500):
Validation that affects the result (all surface as HTTP 500 with a message):
InvoicesValidator.ValidateGetInvoicesInput (invoked as "GetInvoices"):
(A missing/unparseable date query param binds to DateTime.MinValue, which is below SQL Server's datetime min; the range check catches this up front to avoid a cryptic SQL error.)
--------------------------------------------------------------------------------
FILTER RESOLUTION (InvoiceListFilters)
--------------------------------------------------------------------------------
Resolved in BrightInvoiceRepository.GetByCustomerAsync as "local appsettings config (Settings.Invoices:*) ?? company BCHEC flag".
The three UDSMARK visibility variants are independent and compose. Each active flag appends its own SQL clause; inactive flags add nothing (no runtime OR-gates).
Always-applied (Base query) filters, independent of the toggles above:
--------------------------------------------------------------------------------
RESPONSE STRUCTURE (IEnumerable<BrightInvoice>)
--------------------------------------------------------------------------------
The endpoint returns a JSON array of invoice objects (no wrapper). Each object contains a nested `Info` array of supplementary key/value (or title/value) entries.
[
{
"Id": "<InstNr>-<ForbnNr>-<UdebNr>-<Id>", // Data: composite of AKOND.INSTNR + FORBNR + UDEBNR + REGNINGNR (REGNINGNR cast to varchar AS Id)
"ServiceId": "consumption_trade", // Data: AUDEBFORS.FORSYNINGSART (+ AKOND.AFREGNTYPE for KØL) via ForsyningsartMapper; null for unmapped/unknown/null supply types
"DueDate": "2026-01-31T00:00:00+00:00", // Data: AKOND.FORFDATO (DateTimeOffset, UTC offset 0); null if NULL
"InvoiceDate": "2026-01-01T00:00:00+00:00", // Data: AKOND.BILAGSDATO (DateTimeOffset, UTC offset 0); null if NULL
"Period": "1month", // Data: derived from AKOND.DATOFRA/DATOTIL month span (1/2/3/6/12month); defaults "1month" if either date null or span unmatched
"StartDate": "2026-01-01T00:00:00+00:00", // Data: AKOND.DATOFRA (DateTimeOffset, UTC offset 0); null if NULL
"EndDate": "2026-01-31T00:00:00+00:00", // Data: AKOND.DATOTIL (DateTimeOffset, UTC offset 0); null if NULL
"RemainingAmount": 0.00, // Data: AKOND.KR (TotalAmount) - PBSI PaidAmount; null unless BOTH present
"TotalAmount": 1953.12, // Data: AKOND.KR
"InvoiceStatus": "paid", // Data: derived (see MapInvoiceStatus); one of unpaid/paid/partly_paid/overdue/cancelled/credited only
"InvoiceType": "pdf", // Data: derived from HasPdf EXISTS check -> "pdf" or "missing" ("html" never produced)
"Info": [
{ "Key": "invoiceNumber", "Value": "<REGNINGNR>" }, // Data: AKOND.REGNINGNR (as Id) — NOTE: raw value, NOT the composite top-level Id
{ "Key": "invoiceDate", "Value": "<offset>" }, // Data: AKOND.BILAGSDATO (DateTimeOffset) or null
{ "Key": "dueDate", "Value": "<offset>" }, // Data: AKOND.FORFDATO (DateTimeOffset) or null
{ "Key": "totalAmount", "Value": "1953.12" }, // Data: AKOND.KR (.ToString(), so a STRING here vs decimal at top level)
{ "Key": "period", "Value": "1month" }, // Data: same derivation as top-level Period
{ "Key": "remainingAmount", "Value": "0.00" }, // Data: TotalAmount - PaidAmount (.ToString(); null unless both present)
{ "Key": "status", "Value": "paid" }, // Data: same derivation as top-level InvoiceStatus
{ "Key": "description", "Value": "<Tekst>" }, // Data: AKOND.TEKST
{ "Title": "Tekst", "Value": "<Tekst>" } // Data: AKOND.TEKST (DUPLICATE of description; uses Title (untranslated) instead of Key)
// "ocr" -> Not mapped (TODO: source field in SonWin not yet identified)
]
}
] |
Field origin detail (top-level BrightInvoice):
InvoiceStatus derivation (MapInvoiceStatus), in order:
1. KORTSTATUS == 99 -> "cancelled"
2. TotalAmount (KR) < 0 -> "credited"
3. SettlementDate (UDLIGNDATO) set -> "paid" (regardless of PaidAmount)
4. PaidAmount >= TotalAmount -> "paid"
5. DueDate < today (and not fully paid)-> "overdue"
6. PaidAmount > 0 -> "partly_paid"
7. otherwise -> "unpaid"
(collection / reminder / deferred_* / investigation / paid_out are never returned — TODO.)
PaidAmount source: OUTER APPLY over Sonlinc.AKOND where TARIFART='PBSI' for the same INSTNR+FORBNR+UDEBNR+REGNINGNR+FIRMANR; SUM(KR*ANTAL)*-1
(PBSI rows are negative), ISNULL(...,0). Not exposed as its own response field — only feeds RemainingAmount and the status derivation.
DbInvoice columns selected but NOT surfaced as their own response field:
- AfregnType (AKOND.AFREGNTYPE) used only by ServiceId (KØL -> cooling)
- KortStatus (AKOND.KORTSTATUS) used only by status (== 99 -> cancelled)
- KortType (AKOND.KORTTYPE) selected, currently unused in mapping
- SettlementDate (AKOND.UDLIGNDATO) used only by status
- CollectiveBillNr (AKOND.SAMLREGNINGNR) selected; also used as a WHERE filter
- HasPdf (EXISTS check) used only by InvoiceType
- PaidAmount (PBSI sum) used by RemainingAmount + status