|
1 | | -[](https://mvnrepository.com/artifact/software.xdev/template-placeholder) |
2 | | -[](https://github.com/xdev-software/template-placeholder/actions/workflows/check-build.yml?query=branch%3Adevelop) |
3 | | -[](https://sonarcloud.io/dashboard?id=xdev-software_template-placeholder) |
| 1 | +[](https://mvnrepository.com/artifact/software.xdev/bzst-dip-java-client) |
| 2 | +[](https://github.com/xdev-software/bzst-dip-java-client/actions/workflows/check-build.yml?query=branch%3Adevelop) |
| 3 | +[](https://sonarcloud.io/dashboard?id=xdev-software_bzst-dip-java-client) |
4 | 4 |
|
5 | | -# template-placeholder |
| 5 | +<div align="center"> |
| 6 | + <img src="assets/Logo.svg" height="200" alt="XDEV BZST-DIP-Java-Client Logo"> |
| 7 | +</div> |
6 | 8 |
|
| 9 | +# bzst-dip-java-client |
| 10 | + |
| 11 | +Client for using the [Mass data transmission DIP (mass data interface)](https://www.bzst.de/EN/Businesses/CESOP/electronic_data_transmission/electronic_data_transmission_node.html#js-toc-entry1). |
| 12 | + |
| 13 | +The BZSt (Bundeszentralamt für Steuern / Federal Central Tax Office) provides the Digital Inbox (DIP) as a service for payment service providers to transmit financial data. |
| 14 | + |
| 15 | +Clients need to register / login at [BZSt online.portal](https://www.bzst.de/DE/Service/Portalinformation/Massendaten/DIP/dip.html?nn=68828) through [Elster](https://www.elster.de/elsterweb/start), [BundID](https://id.bund.de/de) or [BZSt Online-Portal (BOP)](https://www.elster.de/bportal/start). |
| 16 | + |
| 17 | +See the [BZSt Information](https://www.bzst.de/EN/Service/Portalinformation/Login/login_node.html) for more information. |
| 18 | + |
| 19 | +> [!NOTE] |
| 20 | +> **BZSt Online-Portal** (deprecated) is different from **BZSt online.portal**. |
| 21 | +
|
| 22 | +## Rationale |
| 23 | + |
| 24 | +We created this client to make it as easy as possible for the developer to use the BZSt DIP. |
| 25 | +Through usage of the builder pattern (see [Configuration](#configuration) below), DTOs and a typesafe data model we ensure high usability and readability. |
| 26 | + |
| 27 | +The BZSt provides [XSD](https://www.bzst.de/SharedDocs/Downloads/DE/Digitale_Plattformbetreiber/amtlicher_datensatz_entwurf) that define the expected XML structure and make it possible to generate java classes ([BZSt Docs](https://www.bzst.de/DE/Unternehmen/Intern_Informationsaustausch/DAC7/Handbuecher/handbuecher.html?nn=127558#js-toc-entry2)).<br/> |
| 28 | +Our library validates each request through these XSD find errors before they are sent to the DIP. |
7 | 29 |
|
8 | 30 | ## Installation |
9 | | -[Installation guide for the latest release](https://github.com/xdev-software/template-placeholder/releases/latest#Installation) |
| 31 | +[Installation guide for the latest release](https://github.com/xdev-software/bzst-dip-java-client/releases/latest#Installation) |
| 32 | + |
| 33 | +## Usage |
| 34 | + |
| 35 | +See the [examples in the demo package](./bzst-dip-java-client-demo/src/main/java/software/xdev/). |
| 36 | + |
| 37 | +### Create keystore file |
| 38 | + |
| 39 | +For authentification at the BZST you have to create a public- and private-key. |
| 40 | + |
| 41 | +First you have to create a **PEM** file as described on the [BZST Website](https://www.bzst.de/DE/Service/Portalinformation/Massendaten/DIP/dip_node.html) (see 1.7). |
| 42 | + |
| 43 | +OpenSSL can be downloaded from their [website](https://www.openssl.org/). |
| 44 | + |
| 45 | +``` |
| 46 | +openssl req -newkey rsa-pss -new -nodes -x509 -days 3650 -pkeyopt rsa_keygen_bits:4096 -sigopt rsa_pss_saltlen:32 -keyout key.pem -out cert.pem |
| 47 | +``` |
| 48 | + |
| 49 | +Next you have to convert that file to a **PKCS12** file. |
| 50 | + |
| 51 | +``` |
| 52 | +openssl pkcs12 -export -in cert.pem -inkey key.pem -out certificate.p12 -name "certificate" |
| 53 | +``` |
| 54 | + |
| 55 | +The [keytool](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html) is contained in your JDK installation. |
| 56 | + |
| 57 | +``` |
| 58 | +keytool -importkeystore -srckeystore certificate.p12 -srcstoretype pkcs12 -destkeystore cert.jks |
| 59 | +``` |
| 60 | + |
| 61 | +The password you insert here, along with the file itself must be set in the client configuration. See example at [app.properties](./bzst-dip-java-client-demo/src/main/resources/app.properties): |
| 62 | + |
| 63 | +``` |
| 64 | +certificate.keystore.password=SECRET_PASSWORD |
| 65 | +certificate.keystore.file=cert.jks |
| 66 | +``` |
| 67 | + |
| 68 | +You also have to set the public key in the [BZST online.portal](https://online.portal.bzst.de/). |
| 69 | +Exporting the public key with OpenSSL is easy: |
| 70 | + |
| 71 | +``` |
| 72 | +openssl rsa -in key.pem -pubout > publicKey.pub |
| 73 | +``` |
| 74 | + |
| 75 | +### Client ID |
| 76 | + |
| 77 | +It's also important to use the client id provided by [BZST online.portal](https://online.portal.bzst.de/) |
| 78 | +in the client configuration. See example |
| 79 | +at [app.properties](./bzst-dip-java-client-demo/src/main/resources/app.properties): |
| 80 | + |
| 81 | +``` |
| 82 | +client.id=abcd1234-ab12-ab12-ab12-abcdef123456 |
| 83 | +``` |
| 84 | + |
| 85 | +### Configuration |
| 86 | + |
| 87 | +The client can be configured through a properties file (see [app.properties](./bzst-dip-java-client-demo/src/main/resources/app.properties) and [ApplicationWithConfigurationFromProperties.java](./bzst-dip-java-client-demo/src/main/java/software/xdev/ApplicationWithConfigurationFromProperties.java)) or by creating a configuration object (see [Application.java](./bzst-dip-java-client-demo/src/main/java/software/xdev/Application.java)). |
| 88 | + |
| 89 | +```java |
| 90 | +public static BzstDipConfiguration createConfiguration() |
| 91 | +{ |
| 92 | + return new BzstDipConfigurationBuilder() |
| 93 | + .setClientId("abcd1234-ab12-ab12-ab12-abcdef123456") |
| 94 | + .setTaxID("86095742719") |
| 95 | + .setTaxNumber("123") |
| 96 | + .setCertificateKeystoreInputStream(() -> ClassLoader.getSystemClassLoader() |
| 97 | + .getResourceAsStream("DemoKeystore.jks")) |
| 98 | + .setCertificateKeystorePassword("test123") |
| 99 | + .setRealmEnvironmentBaseUrl(BzstDipConfiguration.ENDPOINT_URL_TEST) |
| 100 | + .setMessageTypeIndic(BzstDipDpiMessageType.DPI_401) |
| 101 | + .setReportingPeriod(LocalDate.now()) |
| 102 | + .setDocTypeIndic(BzstDipOecdDocType.OECD_1) |
| 103 | + .setPlatformOperatorOrganizationName("TestOrg") |
| 104 | + .setPlatformOperatorPlatformName("TestApp") |
| 105 | + .setPlatformOperatorAddress(new BzstDipAddressFix("TestCity")) |
| 106 | + .buildAndValidate(); |
| 107 | +} |
| 108 | +``` |
10 | 109 |
|
11 | 110 | ## Support |
12 | | -If you need support as soon as possible and you can't wait for any pull request, feel free to use [our support](https://xdev.software/en/services/support). |
| 111 | + |
| 112 | +If you need support as soon as possible, and you can't wait for any pull request, feel free to use [our support](https://xdev.software/en/services/support). |
13 | 113 |
|
14 | 114 | ## Contributing |
15 | 115 | See the [contributing guide](./CONTRIBUTING.md) for detailed instructions on how to get started with our project. |
16 | 116 |
|
17 | 117 | ## Dependencies and Licenses |
18 | | -View the [license of the current project](LICENSE) or the [summary including all dependencies](https://xdev-software.github.io/template-placeholder/dependencies) |
| 118 | +View the [license of the current project](LICENSE) or the [summary including all dependencies](https://xdev-software.github.io/bzst-dip-java-client/dependencies) |
0 commit comments