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