================================================================================
BrightAccountsController - Summary & Response Structures
File: SonWinCommonAPI/Controllers/BrightAccountsController.cs
================================================================================
--------------------------------------------------------------------------------
WHAT THE CONTROLLER DOES
--------------------------------------------------------------------------------
BrightAccountsController exposes the customer ("kunde") account data from the
SonWin/Sonlinc system to the "Bright" integration. It lets a caller look up a
customer (by SSN or customer id) and update a customer's contact info. All
endpoints require authorization ([Authorize]) and all of them return data shaped
into the same BrightAccount contract.
All three methods delegate to BrightAccountService and, on any thrown exception,
go through CustomBase.HandleError which logs the error and returns
HTTP 500 with the exception message in the body.
The response object (BrightAccount) is identical for every method, because they
all use the same internal mapper (MapToAccount). The structure is documented
once at the bottom under "RESPONSE STRUCTURE".
--------------------------------------------------------------------------------
METHODS
--------------------------------------------------------------------------------
1) SearchAccounts
Route: GET /bright/accounts/search
Params: ssn, CustomerID, email, phone (+ CancellationToken)
Returns: 200 OK -> IEnumerable<BrightAccount>
401 Unauthorized
What it does:
Searches for accounts by SSN or customer id. Supplying email or phone
causes a validation exception (they cannot uniquely identify a customer).
Requires at least one of CustomerID or ssn. Calls
service.GetBySearchAsync(...) and returns the result.
2) GetAccounts
Route: GET /bright/accounts
Params: CustomerID (+ CancellationToken)
Returns: 200 OK -> IEnumerable<BrightAccount>
401 Unauthorized
What it does:
Gets the account for a single CustomerID. It reuses the exact same
underlying method as SearchAccounts (GetBySearchAsync) with ssn/email/phone
forced to null, so it behaves as "search by customer id only".
3) UpdateCustomer
Route: PATCH /v2/customers
Body: UpdateCustomerRequest { CustomerID, Email1, Phone1 }
Returns: 200 OK -> IEnumerable<BrightAccount>
400 BadRequest
401 Unauthorized
What it does:
Intended to update the email and/or phone number for a customer.
--------------------------------------------------------------------------------
RESPONSE STRUCTURE (BrightAccount) - applies to all methods
--------------------------------------------------------------------------------
Returned as a JSON ARRAY (IEnumerable<BrightAccount>); a successful single
lookup is expected to contain exactly one element.
[
{
"Id": <value> // Data: SonWin customer number (AKUNDE.KUNDENR)
"DisplayName": <value> // Data: customer name (AKUNDE.NAVN2 if Navn2 setting is true, else NAVN1)
"UserRoles": [
{
"Role": "owner" // Hardcoded: literal string 'owner' (set in SQL; mapper also defaults to "owner")
"User": {
"Id": <value> // Data: same SonWin customer number (KUNDENR)
"FirstName": null // Hardcoded null: SonWin has no separate first name
"LastName": null // Hardcoded null: SonWin has no separate last name
"Email": <value> // Data: customer e-mail (AKUNDE.EMAIL)
"PhoneNumber": <value> // Data: customer phone (AKUNDE.TELEFONNR)
"Language": null // Hardcoded null: not available in SonWin
"Username": null // Hardcoded null: not available in SonWin
"Ssn": null // Hardcoded null: intentionally not returned
"OrgNumber": null // Hardcoded null: not available in SonWin
}
}
],
"ContactInfo": {
"Email": <value> // Data: customer e-mail (AKUNDE.EMAIL) - same source as User.Email
"phonenumber": <value> // Data: customer phone (AKUNDE.TELEFONNR); JSON key is lowercase "phonenumber"
}
}
]
Notes:
- Email and phone are duplicated: once inside UserRoles[].User and once inside
ContactInfo. Both come from the same source columns (EMAIL / TELEFONNR).
- ContactInfo.phonenumber is serialized lowercase (forced via JsonPropertyName);
the C# property is "Phonenumber".
- Role is the only non-null hardcoded value ("owner"); all other hardcoded
fields are null.
================================================================================