|
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://editor.swagger.io/?url=https://raw.githubusercontent.com/xdev-software/template-placeholder/develop/openapi/openapi.yml) |
| 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://editor.swagger.io/?url=https://raw.githubusercontent.com/xdev-software/bzst-dip-java-client/develop/openapi/openapi.yml) |
4 | 4 |
|
5 | | -# template-placeholder |
| 5 | +# <img src="assets/logo-v2.svg" height="24" alt="XDEV BZST-DIP-Java-Client Logo"> bzst-dip-java-client |
6 | 6 |
|
7 | | -This client [is generated](./template-placeholder/pom.xml) from an [``openapi.yml``](./openapi/openapi.yml) using [OpenAPI Generator](https://openapi-generator.tech/). |
| 7 | +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). |
| 8 | + |
| 9 | +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. |
| 10 | + |
| 11 | +This library uses a [generated](./bzst-dip-java-client/pom.xml) client from an [``openapi.yml``](./openapi/openapi.yml) |
| 12 | +using [OpenAPI Generator](https://openapi-generator.tech/). |
| 13 | + |
| 14 | +Clients need to register / login |
| 15 | +at [BZSt online.portal](https://www.bzst.de/DE/Service/Portalinformation/Massendaten/DIP/dip.html?nn=68828) |
| 16 | +through [Elster](https://www.elster.de/elsterweb/start), [BundID](https://id.bund.de/de) |
| 17 | +or [BZSt Online-Portal (BOP)](https://www.elster.de/bportal/start). |
| 18 | + |
| 19 | +See the [BZSt Information](https://www.bzst.de/EN/Service/Portalinformation/Login/login_node.html) for more information. |
| 20 | + |
| 21 | +> [!NOTE] |
| 22 | +> **BZSt Online-Portal** (deprecated) is different from **BZSt online.portal**. |
| 23 | +
|
| 24 | +> [!IMPORTANT] |
| 25 | +> We are currently on version 2.0.0. Since testing with the BZSt is quite difficult, |
| 26 | +> **we could not test this version fully**. |
| 27 | +> |
| 28 | +> If you don't want to take any risk using our client, you can still use the **stable and |
| 29 | +tested [version 1.0.3 of this library](https://github.com/xdev-software/bzst-dip-java-client/releases/tag/v1.0.3)**. |
| 30 | +> |
| 31 | +> If you are **willing to test v2.0.0**, we would very much appreciate your feedback! |
| 32 | +
|
| 33 | +## Rationale |
| 34 | + |
| 35 | +We created this client to make it as easy as possible for the developer to use the BZSt DIP. |
| 36 | +Through usage of the builder pattern (see [Configuration](#configuration) below), DTOs and a typesafe data model we ensure high usability and readability. |
| 37 | + |
| 38 | +The BZSt provides [XSD](https://www.bzst.de/DE/Unternehmen/Umsatzsteuer/CESOP/Benutzerhandbuch/cesop-benutzerhandbuch.html) 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/> |
| 39 | +Our library validates each request through these XSD find errors before they are sent to the DIP. |
8 | 40 |
|
9 | 41 | ## Installation |
10 | | -[Installation guide for the latest release](https://github.com/xdev-software/template-placeholder/releases/latest#Installation) |
| 42 | +[Installation guide for the latest release](https://github.com/xdev-software/bzst-dip-java-client/releases/latest#Installation) |
| 43 | + |
| 44 | +## Usage |
| 45 | + |
| 46 | +See the [examples in the demo package](./bzst-dip-java-client-demo/src/main/java/software/xdev/). |
| 47 | + |
| 48 | +### Create certificate |
| 49 | + |
| 50 | +For authentification at the BZST you have to create a public- and private-key. |
| 51 | + |
| 52 | +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). |
| 53 | + |
| 54 | +OpenSSL can be downloaded from the [website](https://www.openssl.org/). |
| 55 | + |
| 56 | +``` |
| 57 | +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 |
| 58 | +``` |
| 59 | + |
| 60 | +You also have to set the public key in the [BZST online.portal](https://online.portal.bzst.de/). |
| 61 | +Exporting the public key with OpenSSL is easy: |
11 | 62 |
|
12 | | -## Demo |
13 | | -A minimal demo is also available [here](./template-placeholder-demo/src/main/java/software/xdev/Application.java). |
| 63 | +``` |
| 64 | +openssl rsa -in key.pem -pubout > publicKey.pub |
| 65 | +``` |
| 66 | + |
| 67 | +Now you can already use these two files to sign your requests. See |
| 68 | +the [example with PEM signing](./bzst-dip-java-client-demo/src/main/java/software/xdev/ApplicationWithPem.java). |
| 69 | + |
| 70 | +### Create Java KeyStore (JKS) |
| 71 | + |
| 72 | +If you want to go one step further you can use the Java KeyStore. Then you have to convert the `cert.pem` file to a * |
| 73 | +*PKCS12** file. |
| 74 | + |
| 75 | +``` |
| 76 | +openssl pkcs12 -export -in cert.pem -inkey key.pem -out certificate.p12 -name "certificate" |
| 77 | +``` |
| 78 | + |
| 79 | +The [keytool](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html) is contained in your JDK installation. |
| 80 | + |
| 81 | +``` |
| 82 | +keytool -importkeystore -srckeystore certificate.p12 -srcstoretype pkcs12 -destkeystore cert.jks |
| 83 | +``` |
| 84 | + |
| 85 | +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): |
| 86 | + |
| 87 | +``` |
| 88 | +certificate.keystore.password=SECRET_PASSWORD |
| 89 | +certificate.keystore.file=cert.jks |
| 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 [ApplicationWithDac7.java](./bzst-dip-java-client-demo/src/main/java/software/xdev/ApplicationWithDac7.java)). |
| 109 | + |
| 110 | +```java |
| 111 | +public static BzstDipConfiguration createConfiguration() |
| 112 | +{ |
| 113 | + return new BzstDipConfigurationBuilder() |
| 114 | + .setApplicationCode(BzstDipConfiguration.SupportedApplicationCode.DAC7) |
| 115 | + .setClientId("abcd1234-ab12-ab12-ab12-abcdef123456") |
| 116 | + .setTaxID("86095742719") |
| 117 | + .setTaxNumber("123") |
| 118 | + .setSigningProvider(new SigningProviderByJks("DemoKeystore.jks", "test123")) |
| 119 | + .setRealmEnvironmentBaseUrl(BzstDipConfiguration.ENDPOINT_URL_TEST) |
| 120 | + .setMessageTypeIndic(BzstDipDpiMessageType.DPI_401) |
| 121 | + .setReportingPeriod(LocalDate.now()) |
| 122 | + .setDocTypeIndic(BzstDipOecdDocType.OECD_1) |
| 123 | + .setPlatformOperatorOrganizationName("TestOrg") |
| 124 | + .setPlatformOperatorPlatformName("TestApp") |
| 125 | + .setPlatformOperatorAddress(new BzstDipAddressFix("TestCity")) |
| 126 | + .buildAndValidate(); |
| 127 | +} |
| 128 | +``` |
| 129 | + |
| 130 | +Messages are sent with |
| 131 | +DAC7 ([ApplicationWithDac7.java](./bzst-dip-java-client-demo/src/main/java/software/xdev/ApplicationWithDac7.java)) or |
| 132 | +the |
| 133 | +CESOP ([ApplicationWithCesop.java](./bzst-dip-java-client-demo/src/main/java/software/xdev/ApplicationWithCesop.java)) |
| 134 | +Format. |
14 | 135 |
|
15 | 136 | ## Support |
16 | | -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). |
| 137 | + |
| 138 | +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). |
17 | 139 |
|
18 | 140 | ## Contributing |
19 | 141 | See the [contributing guide](./CONTRIBUTING.md) for detailed instructions on how to get started with our project. |
20 | 142 |
|
21 | 143 | ## Dependencies and Licenses |
22 | | -View the [license of the current project](LICENSE) or the [summary including all dependencies](https://xdev-software.github.io/template-placeholder/dependencies) |
| 144 | +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