Kundenportfolio

So folgen Sie diesem Kapitel

Eingaben: userId, portfolioId und ein CLIENT-Token aus den vorherigen Schritten.

Schritte und erwartetes Ergebnis: Listen Sie die Portfolios auf und wählen Sie eines aus. Lesen Sie anschliessend dessen Snapshot und zugehörige Daten. Laden Sie ein ausgewähltes Dokument anhand seiner Referenz und Portfolio-ID aus den Metadaten herunter.

Alternativen und spätere Aktionen: Werte, Geldkonten und Dokumente können zeitversetzt verfügbar werden. Solange die Portfolioverarbeitung läuft, sind leere Listen oder noch nicht verfügbare Daten möglich.

DTO-Quellcode: BankAccountTypeOutputModel, BookingCodeOutputModel, CashAccountMovementOutputModel, CashAccountOutputModel, PortfolioOutputModel, PortfolioValuesContainerOutputModel, UserBankDocumentInfoOutputModel

In früheren Codeblöcken zugewiesene Variablen werden später wiederverwendet. Kundeneingaben stammen aus Ihrer Oberfläche. Bewahren Sie IDs und Referenzwerte im Kontext des jeweiligen Kunden auf; legen Sie nicht für jeden Schritt einen neuen Kontext an.

Die Beispiele verwenden gemeinsame Hilfsklassen. Lesen Sie Gemeinsame Hilfsklassen: vollständiger C#- und Java-Quellcode bevor Sie ein Beispiel übernehmen.
Voraussetzungen: userId, die ausgewählte portfolioId und ein CLIENT-Token oder ein zum Lesen dieser Ressourcen berechtigter administrativer Token.
Für den nächsten Schritt aufbewahren: Portfolio-Snapshots, Performancewerte, Kontobewegungen und herunterladbare Bankdokumente.
In diesem Kapitel erfahren Sie, wie Sie die Portfoliodaten eines Kunden abrufen.

Portfolioliste

Eingaben: userId und CLIENT-Token.
Aktion: Lesen Sie die aktuelle Portfolioliste mit Snapshot aus.
Aufbewahren / erwartetes Ergebnis: Bewahren Sie die vom Kunden ausgewählte portfolioId auf.
Setzen Sie für diesen Aufruf im Authorization-Header einen Token mit der Rolle CLIENT oder ADMIN. 

httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
// Assuming this is our client ID
// Use the userId returned by registration.
var clientPortfolios = await httpClient.GetFromJsonAsync<IList<PortfolioOutputModel>>($"api/v1/user-portfolios/user-id/{userId}?portfolio-view-as=Snapshot");


								
// Assuming this is our client ID
// Use the userId returned by registration.

HttpRequest portfolioRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("user-portfolios/user-id/" + userId + "?portfolio-view-as=Snapshot"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .build();

var response = httpClient.send(portfolioRequest, BodyHandlers.ofString());
Api.requireSuccess(response);

Type listType = new TypeToken<ArrayList<PortfolioOutputModel>>(){}.getType();
List<PortfolioOutputModel> portfolioObjs = new Gson().fromJson(response.body(), listType);

Portfolio anhand der ID

Eingaben: Die ausgewählte portfolioId.
Aktion: Lesen Sie den aktuellen Portfolio-Snapshot aus.
Aufbewahren / erwartetes Ergebnis: Verwenden Sie den zurückgegebenen Zustand und HasPendingOrder, um verfügbare Aktionen anzuzeigen.
Rufen Sie den ausgewählten Portfolio-Snapshot mit aktuellen Eigenschaften und verfügbaren Werten ab. Die Beispiele fordern ausdrücklich Snapshot an. Ohne portfolio-view-as verwendet die API standardmässig Forecast.

// Assuming this is the portfolio ID
// portfolioId is selected from the returned client portfolio list.
var clientPortfolio = await httpClient.GetFromJsonAsync<PortfolioOutputModel>($"api/v1/user-portfolios/portfolio-id/{portfolioId}?portfolio-view-as=Snapshot");


								
// Assuming this is the portfolio ID
// portfolioId is selected from the returned client portfolio list.

HttpRequest portfolioRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("user-portfolios/portfolio-id/" + portfolioId + "?portfolio-view-as=Snapshot"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .build();

response = httpClient.send(portfolioRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
PortfolioOutputModel portfolioObj = new Gson().fromJson(response.body(), PortfolioOutputModel.class);
Mit diesen Daten können Sie eine erste Portfolioansicht erstellen:
Beispiel von Portfoliodetails

Portfoliowerte

Eingaben: portfolioId und der gewünschte Zeitraum.
Aktion: Lesen Sie den Container für Performance- und Wertdaten aus.
Aufbewahren / erwartetes Ergebnis: Lesen Sie dessen Values-Sammlung. Für den angeforderten Zeitraum sind möglicherweise noch keine Daten verfügbar.
Historische Performance, Marktwerte, Gesamtvermögen, Gewinn und Verlust sowie Liquidität können über den Performance-Endpunkt abgerufen werden. Die Antwort ist ein PortfolioValuesContainerOutputModel mit datierten Werten in der Values-Sammlung. Die optionalen Abfrageparameter startingDate und endingDate verwenden yyyyMMdd; Datumswerte in der Antwort entsprechen dem JSON-Schema. HTTP 404 kann bedeuten, dass noch keine Performancedaten für das Portfolio verfügbar sind.
Performance Beispiel eines Performancediagramms
Marktwerte Beispiel eines Marktwertdiagramms 

// Assuming this is the portfolio ID we want to display
// portfolioId is selected from the returned client portfolio list.
var portfolioValues = await httpClient.GetFromJsonAsync<PortfolioValuesContainerOutputModel>($"api/v1/user-portfolios/portfolio-id/{portfolioId}/performances");


								
// Assuming this is the portfolio ID we want to display
// Use the same selected portfolioId.

HttpRequest portfolioPerformanceRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("user-portfolios/portfolio-id/" + portfolioId + "/performances"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .build();

response = httpClient.send(portfolioPerformanceRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
PortfolioValuesContainerOutputModel portfolioPerformanceObj = new Gson().fromJson(response.body(), PortfolioValuesContainerOutputModel.class);

Liquidität des Portfolios

Eingaben: portfolioId.
Aktion: Ermitteln Sie das zugehörige Geldkonto und lesen Sie dessen Saldo und Bewegungen aus.
Aufbewahren / erwartetes Ergebnis: Bewahren Sie die Geldkonto-ID auf und zeigen Sie den Saldo zusammen mit seinem Stichtag an.
Rufen Sie die Geldkonten des ausgewählten Portfolios ab. Verwenden Sie IBAN und Saldo des passenden CASH-ACCOUNT-Eintrags. Ein noch fehlendes Geldkonto kann durch den Portfolio-Lebenszyklus oder die Konfiguration bedingt sein. Auf dieses Konto zahlt der Kunde beispielsweise seinen jährlichen Säule-3a-Beitrag ein. Salden beziehen sich auf den vom Dienst gelieferten Buchungsstichtag. Zahlungen oder Transaktionen können erst später sichtbar werden, während Daten der Depotbank verarbeitet werden. Die folgenden Beispiele ermitteln das Geldkonto des Portfolios: 

// Get bank account types: Cash account/Custody account
var bankAccountTypes = await httpClient.GetFromJsonAsync<List<BankAccountTypeOutputModel>>($"api/v1/cash-account-types");
var cashAccountType = bankAccountTypes.First(x => x.Code == "CASH-ACCOUNT");
// Get portfolio's bank accounts
var bankAccounts = await httpClient.GetFromJsonAsync<List<CashAccountOutputModel>>($"api/v1/user-cash-accounts/portfolio-id/{portfolioId}");
var cashAccount = bankAccounts.First(x => x.AccountTypeId == cashAccountType.Id);


								
// Portfolio cash amount

HttpRequest bankAccountTypesRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("cash-account-types"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.GUEST_TOKEN)
    .header("Content-Type", "application/json")
    .build();

// Get bank account types: Cash account/Custody account
response = httpClient.send(bankAccountTypesRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
Type listBankAccountTypes = new TypeToken<ArrayList<BankAccountTypeOutputModel>>(){}.getType();
List<BankAccountTypeOutputModel> bankAccountTypes = new Gson().fromJson(response.body(), listBankAccountTypes);
var bankAccountType = bankAccountTypes.stream().filter(x -> "CASH-ACCOUNT".equals(x.Code)).findFirst().orElseThrow(() -> new IllegalStateException("Required reference data is unavailable"));

// Get portfolio's bank accounts
HttpRequest portfolioBankAccountRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("user-cash-accounts/portfolio-id/" + portfolioId))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .build();

response = httpClient.send(portfolioBankAccountRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
Type cashAccountType = new TypeToken<ArrayList<CashAccountOutputModel>>(){}.getType();
List<CashAccountOutputModel> cashAccountObjs = new Gson().fromJson(response.body(), cashAccountType);
CashAccountOutputModel cashAccountObj = cashAccountObjs.stream().filter(x -> x.AccountTypeId == bankAccountType.Id).findFirst().orElseThrow(() -> new IllegalStateException("Required reference data is unavailable"));
CashAccountOutputModel enthält Iban, Balance und BalanceDate. Das Geldkonto besitzt eine eigene ID; verwenden Sie diese Id zum Abrufen seiner Bewegungen.
Zusätzlich können Sie Kontobewegungen abrufen. Beispielsweise können verbuchte Käufe und Verkäufe des Portfolios darin erscheinen. Das folgende Beispiel zeigt den Abruf: 
									
var bankAccountMovements = await httpClient.GetFromJsonAsync<List<CashAccountMovementOutputModel>>($"api/v1/user-cash-accounts/cash-account-id/{cashAccount.Id}/movements");


									
HttpRequest cashAccountMovementsRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("user-cash-accounts/cash-account-id/" + cashAccountObj.Id + "/movements"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .build();

response = httpClient.send(cashAccountMovementsRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
Type cashAccountMovementType = new TypeToken<ArrayList<CashAccountMovementOutputModel>>(){}.getType();
List<CashAccountMovementOutputModel> cashAccountMovementObjs = new Gson().fromJson(response.body(), cashAccountMovementType);
CashAccountMovementOutputModel enthält BookingCodeId. Über diese Eigenschaft können Sie die Beschreibung der Bewegungsart ermitteln: 
									
foreach (var bankAccountMovement in bankAccountMovements)
{
    var bookingCode = await httpClient.GetFromJsonAsync<BookingCodeOutputModel>($"api/v1/booking-codes/id/{bankAccountMovement.BookingCodeId}");
    var bookingCodeValue = bookingCode.Code;
    var bookingCodeDescription = bookingCode.Description;
// Continue with the data returned by the API.
}

	
									
HttpRequest bookingCodeRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("booking-codes"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .build();

response = httpClient.send(bookingCodeRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
Type bookingCodeTypes = new TypeToken<ArrayList<BookingCodeOutputModel>>(){}.getType();
List<BookingCodeOutputModel> bookingCodeTypeObjs = new Gson().fromJson(response.body(), bookingCodeTypes);

cashAccountMovementObjs.forEach(bankAccountMovement -> {
    BookingCodeOutputModel bookingCodeTypeObj = bookingCodeTypeObjs.stream().filter(x -> x.Id == bankAccountMovement.BookingCodeId).findFirst().orElseThrow(() -> new IllegalStateException("Required reference data is unavailable"));

    var bookingCode = bookingCodeTypeObj.Code;
    var bookingCodeDescription = bookingCodeTypeObj.Description;
    // Continue with the data returned by the API.
});
Beispiel von Geldkontobewegungen

Bankdokumente des Portfolios

Eingaben: userId und anschliessend die aus den Metadaten ausgewählte Dokument-ID.
Aktion: Listen Sie die Dokumente auf und laden Sie das ausgewählte PDF als Binärdaten herunter.
Aufbewahren / erwartetes Ergebnis: Verwenden Sie UserPortfolioId und Reference aus den Metadaten. Gehen Sie nicht davon aus, dass jedes Dokument zum aktuell ausgewählten Portfolio gehört.
Von der Bank bereitgestellte PDF-Dokumente stehen dem Kunden zum Download zur Verfügung. 

// User bank documents
var url = $"api/v1/user-bank-documents/user-id/{userId}/list?starting-from=20000101";
var bankDocumentsForAllPortfolios = await httpClient.GetFromJsonAsync<IList<UserBankDocumentInfoOutputModel>>(url);


								
// User bank documents
HttpRequest userDocumentsMetadataRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("user-bank-documents/user-id/" + userId + "/list?starting-from=20000101"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .build();

response = httpClient.send(userDocumentsMetadataRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
Type userBankDocumentInfoType = new TypeToken<ArrayList<UserBankDocumentInfoOutputModel>>(){}.getType();
List<UserBankDocumentInfoOutputModel> userDocumentsMetadataObjs = new Gson().fromJson(response.body(), userBankDocumentInfoType);
Wählen Sie ein Dokument aus den Metadaten und verwenden Sie seine zugehörige Portfolio-ID und Referenz. UserPortfolioId bezeichnet das Portfolio des Dokuments. Wählen Sie selectedDocumentId aus der Metadatenliste und verwenden Sie dessen Reference zum Herunterladen des PDFs. 

// selectedDocumentId identifies an item chosen from the returned metadata.
var selectedDocument = bankDocumentsForAllPortfolios.Single(x => x.Id == selectedDocumentId);
var documentPortfolioId = selectedDocument.UserPortfolioId;
var reference = selectedDocument.Reference;
var url = $"api/v1/user-bank-documents/user-id/{userId}/portfolio-id/{documentPortfolioId}/download-bank-document/reference/{Uri.EscapeDataString(reference)}";
var byteArray = await httpClient.GetByteArrayAsync(url);
// Save or display the PDF after the HTTP request succeeds.


								
// selectedDocumentId identifies an item chosen from the returned metadata.
var selectedDocument = userDocumentsMetadataObjs.stream()
    .filter(x -> x.Id == selectedDocumentId).findFirst()
    .orElseThrow(() -> new IllegalArgumentException("Select a listed document"));
var documentPortfolioId = selectedDocument.UserPortfolioId;
var reference = selectedDocument.Reference;
var encodedReference = java.net.URLEncoder.encode(reference, StandardCharsets.UTF_8).replace("+", "%20");
HttpRequest request = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("user-bank-documents/user-id/" + userId
        + "/portfolio-id/" + documentPortfolioId + "/download-bank-document/reference/" + encodedReference))
    .header("Authorization", "Bearer " + accessToken).GET().build();
var response = httpClient.send(request, BodyHandlers.ofByteArray());
Api.requireSuccess(response);
byte[] pdfBytes = response.body();
// Save or display pdfBytes as a PDF.
Beispiel eines Bankdokuments:
Beispiel eines PDF-Vertrags