Invoice Controller

================================================================================

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:

[FromRoute] string accountId
[FromQuery] DateTime dateFrom
[FromQuery] DateTime dateTo
[FromQuery] int? limit (defaults to 100 in the repository)
CancellationToken ct

Body: none (GET)

Returns:

200 OK -> IEnumerable<BrightInvoice>
400 BadRequest -> DECLARED, never produced (catch commented out)
401 Unauthorized -> produced by [Authorize] framework, not by code
404 NotFound -> DECLARED, never produced (catch commented out)
500 -> any thrown exception (validation, SQL, mapping)

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):

0 customer rows -> "No customer found with Id '{id}'."
1 customer rows -> "Unique active customer could not be identified. Id: '{id}'."
row has blank CustomerId -> "The customer returned did not have any CustomerId."
returned id != requested -> "Returned customer '{row}' does not match requested '{id}'."
MitId deactivated -> "The customer with Id '{id}' does not have an active MitId registration." (skipped if Settings.IgnoreMitIdStatus)

InvoicesValidator.ValidateGetInvoicesInput (invoked as "GetInvoices"):

blank customerId -> "Missing parameter 'AccountId'."
dateFrom out of SQL range -> "Missing or invalid parameter 'DateFrom'.
Provide a date between 1753-01-01 and 9999-12-31 (e.g. 2000-01-01)."
dateTo out of SQL range -> "Missing or invalid parameter 'DateTo'.
Provide a date between 1753-01-01 and 9999-12-31 (e.g. 2030-12-31)."
dateFrom > dateTo -> "Parameter outside of allowed range:
'DateFrom' must be earlier than or equal to 'DateTo'."
limit < 1 -> "Parameter outside of allowed range: 'Limit' must be 1 or greater."

(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).

ExcludeParked = Settings.InvoiceExcludeParked ?? BCHEC VISEJPARKEREDE -> AND (UDSMARK IS NULL OR UDSMARK <= 25) (hide UDSMARK > 25)
CheckUdsmark = Settings.InvoiceCheckUdsmark ?? BCHEC CHECKUDSMARK -> AND (UDSMARK IS NULL OR = 0 OR BETWEEN 2 AND 25) (also drops UDSMARK = 1)
ShowOnlyDelivered = Settings.InvoiceShowOnlyDelivered ?? BCHEC VISKUNUDSKREVNE -> UDSMARK <= 25 + SNEX/DSEND delivery check (DELIVERYSTATE IN (5,9))
ExcludeFutureDated = Settings.InvoiceExcludeFutureDated ?? BCHEC EJFREMTID -> AND BILAGSDATO <= @Today
ExcludeAfregnTypes = Settings.InvoiceExcludeAfregnTypes (non-empty) ?? BCHEC W11_W12EJAFRTYP -> AND AFREGNTYPE NOT IN @ExcludeAfregnTypes
OnlyRendered = !Settings.InvoiceShowAlsoInvoicesWithoutPdf (default true) -> AND EXISTS (AKONDDOC -> BDOC, DOCTYPE=1, DATALENGTH(PAYLOAD)>0, MIMETYPE LIKE @PdfMimeType) → @PdfMimeType defaults to application/pdf

Always-applied (Base query) filters, independent of the toggles above:

FIRMANR = @CompanyId, KUNDENR = @CustomerId
TARIFART IN ('A-TOT','A-FAK') (header rows only; S-TOT excluded)
(SWIBASVIS IS NULL OR SWIBASVIS = 1) (exclude SWIB-internal, non-visible)
(SAMLREGNINGNR IS NULL OR SAMLREGNINGNR <= 0) (hide bills folded into a collective invoice)
BILAGSDATO BETWEEN @DateFrom AND @DateTo
ORDER BY BILAGSDATO DESC, REGNINGNR DESC, SWCOUNT DESC
OFFSET 0 ROWS FETCH NEXT @Limit ROWS ONLY (@Limit = limit ?? 100)

--------------------------------------------------------------------------------

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):

Id <- composite "{InstNr}-{ForbnNr}-{UdebNr}-{Id}" (Id = REGNINGNR)
ServiceId <- ForsyningsartMapper.MapToBrightServiceType(ForsyningsArt, AfregnType)
DueDate <- AKOND.FORFDATO
InvoiceDate <- AKOND.BILAGSDATO
Period <- MapPeriod(DATOFRA, DATOTIL)
StartDate <- AKOND.DATOFRA
EndDate <- AKOND.DATOTIL
RemainingAmount <- AKOND.KR - PBSI PaidAmount (null unless both present)
TotalAmount <- AKOND.KR
InvoiceStatus <- MapInvoiceStatus(row).GetDisplayName()
InvoiceType <- MapInvoiceType(row) ("pdf" if HasPdf else "missing")
Info <- list assembled in the mapper (see above)

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

Page tree

Invoice Controller