Skip to content
This repository was archived by the owner on Sep 2, 2021. It is now read-only.

Commit 372c022

Browse files
carlosthe19916carlosthe19916
committed
add docs
1 parent 8d1e95c commit 372c022

File tree

6 files changed

+341
-1
lines changed

6 files changed

+341
-1
lines changed

‎docusaurus/docs/configuration.md

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
id: configuration
3+
title: Configuration
4+
---
5+
6+
_XBuilder Server_ allows you to change the default configuration of the server. For configuring the server, _XBuilder Server_ uses variables.
7+
8+
## Variables
9+
10+
| variable | default value | description |
11+
| ----------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------ |
12+
| openubl.igv | 0.18 | Value of the IGV tax |
13+
| openubl.ivap | 0.04 | Value of the IVAP tax |
14+
| openubl.icb | 0.20 | Value of the ICB tax |
15+
| openubl.timezone | America/Lima | Time zone in which automatic dates will be generated |
16+
| openubl.server.keystore.location | _null_ | (Optional) The location of the certificate you want to use if you'd like to sign all your certificates |
17+
| openubl.server.keystore.password | _null_ | (Optional) The password of the certificate you want to use if you'd like to sign all your certificates |
18+
| openubl.defaults.moneda | PEN | Default currency you want to use |
19+
| openubl.defaults.unidad-medida | NIU | Default Unit of Measure |
20+
| openubl.defaults.tipo-igv | GRAVADO_OPERACION_ONEROSA | Default type of _IGV_ taxes you want to apply |
21+
| openubl.defaults.tipo-nota-credito | ANULACION_DE_LA_OPERACION | Default type of _CreditNote_ |
22+
| openubl.defaults.tipo-nota-debito | AUMENTO_EN_EL_VALOR | Default type of _DebitNote_ |
23+
| openubl.defaults.regimen-percepcion | VENTA_INTERNA | Default type of _Perception_ |
24+
| openubl.defaults.regimen-retencion | TASA_TRES | Default type of _Retention_ |
25+
26+
## Override variables
27+
28+
_XBuilder Server_ is based on Quarkus and you can take advantage of their system to override variables. For more information about how to override properties read [Quarkus Config](https://quarkus.io/guides/config#overriding-properties-at-runtime)
29+
30+
> You can override these runtime properties with the following mechanisms (in decreasing priority):
31+
>
32+
> 1. using system properties:
33+
>
34+
> - for a runner jar: java -Dquarkus.datasource.password=youshallnotpass -jar target/myapp-runner.jar
35+
> - for a native executable: ./target/myapp-runner -Dquarkus.datasource.password=youshallnotpass
36+
>
37+
> 1. using environment variables:
38+
>
39+
> - for a runner jar: export QUARKUS_DATASOURCE_PASSWORD=youshallnotpass ; java -jar target/myapp-runner.jar
40+
>
41+
> - for a native executable: export QUARKUS_DATASOURCE_PASSWORD=youshallnotpass ; ./target/myapp-runner
42+
>
43+
> 1. using an environment file named .env placed in the current working directory containing the line QUARKUS_DATASOURCE_PASSWORD=youshallnotpass (for dev mode, this file can be placed in the root of the project, but it is advised to not check it in to version control)
44+
>
45+
> 1. using a configuration file placed in \$PWD/config/application.properties
46+
>
47+
> - By placing an application.properties file inside a directory named config which resides in the directory where the application runs, any runtime properties defined in that file will override the default configuration. Furthermore any runtime properties added to this file that were not part of the original application.properties file will also be taken into account.
48+
>
49+
> - This works in the same way for runner jar and the native executable
50+
>
51+
> **https://quarkus.io/guides/config#overriding-properties-at-runtime**
52+
53+
### Docker example
54+
55+
```shell script
56+
docker run \
57+
-e OPENUBL_ICB=0.9 \
58+
projectopenubl/xbuilder-server
59+
```
60+
61+
### JVM example
62+
63+
```shell script
64+
java -Dopenubl.icb=0.9 -jar xbuilder-*-runner.jar
65+
```
66+
67+
### Linux example
68+
69+
Using system properties:
70+
71+
```shell script
72+
./xbuilder-server-* -Dopenubl.icb=0.9
73+
```
74+
75+
Using environment variables:
76+
77+
```shell script
78+
export OPENUBL_ICB=0.9 ; ./xbuilder-server-*
79+
```

‎docusaurus/docs/create_xmls.md

+185
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
---
2+
id: create_xmls
3+
title: Create XMLs
4+
---
5+
6+
For creating XML files you need to interact with the set of REST endpoints _XBuilder Server_ exposes to you. For more information about the REST API documentation visit [OpenAPI](./openapi)
7+
8+
For executing the next set of examples you need to have _XBuilder Server_ running.
9+
10+
## Invoice
11+
12+
```shell script
13+
curl -X POST \
14+
-H "Content-Type: application/json" \
15+
-d '{
16+
"serie": "F001",
17+
"numero": 1,
18+
"proveedor": {
19+
"ruc": "12345678912",
20+
"razonSocial": "Project OpenUBL"
21+
},
22+
"cliente": {
23+
"tipoDocumentoIdentidad": "RUC",
24+
"numeroDocumentoIdentidad": "12312312312",
25+
"nombre": "Nombre de mi cliente"
26+
},
27+
"detalle": [
28+
{
29+
"descripcion": "Nombre de producto o servicio",
30+
"precioUnitario": 1,
31+
"cantidad": 1,
32+
"tipoIgv": "GRAVADO_OPERACION_ONEROSA"
33+
}
34+
]
35+
}' \
36+
http://localhost:8080/api/documents/invoice/create
37+
```
38+
39+
## CreditNote
40+
41+
```shell script
42+
curl -X POST \
43+
-H "Content-Type: application/json" \
44+
-d '{
45+
"serie": "F001",
46+
"numero": 1,
47+
"descripcionSustentoDeNota": "mi motivo",
48+
"serieNumeroComprobanteAfectado": "F001-1",
49+
"proveedor": {
50+
"ruc": "12345678912",
51+
"razonSocial": "Project OpenUBL"
52+
},
53+
"cliente": {
54+
"tipoDocumentoIdentidad": "RUC",
55+
"numeroDocumentoIdentidad": "12312312312",
56+
"nombre": "Nombre de mi cliente"
57+
},
58+
"detalle": [
59+
{
60+
"descripcion": "Nombre de producto o servicio",
61+
"precioUnitario": 1,
62+
"cantidad": 1
63+
}
64+
]
65+
}' \
66+
http://localhost:8080/api/documents/credit-note/create
67+
```
68+
69+
## DebitNote
70+
71+
```shell script
72+
curl -X POST \
73+
-H "Content-Type: application/json" \
74+
-d '{
75+
"serie": "F001",
76+
"numero": 1,
77+
"descripcionSustentoDeNota": "mi motivo",
78+
"serieNumeroComprobanteAfectado": "F001-1",
79+
"proveedor": {
80+
"ruc": "12345678912",
81+
"razonSocial": "Project OpenUBL"
82+
},
83+
"cliente": {
84+
"tipoDocumentoIdentidad": "RUC",
85+
"numeroDocumentoIdentidad": "12312312312",
86+
"nombre": "Nombre de mi cliente"
87+
},
88+
"detalle": [
89+
{
90+
"descripcion": "Nombre de producto o servicio",
91+
"precioUnitario": 1,
92+
"cantidad": 1
93+
}
94+
]
95+
}' \
96+
http://localhost:8080/api/documents/debit-note/create
97+
```
98+
99+
## VoidedDocument
100+
101+
```shell script
102+
curl -X POST \
103+
-H "Content-Type: application/json" \
104+
-d '{
105+
"numero": 1,
106+
"descripcionSustento": "mi motivo de baja",
107+
"proveedor": {
108+
"ruc": "12345678912",
109+
"razonSocial": "Project OpenUBL"
110+
},
111+
"comprobante": {
112+
"serieNumero": "F001-1",
113+
"tipoComprobante": "FACTURA",
114+
"fechaEmision": 1585398109198
115+
}
116+
}' \
117+
http://localhost:8080/api/documents/voided-document/create
118+
```
119+
120+
## SummaryDocument
121+
122+
```shell script
123+
curl -X POST \
124+
-H "Content-Type: application/json" \
125+
-d '{
126+
"numero": 1,
127+
"fechaEmisionDeComprobantesAsociados": 1585398109198,
128+
"proveedor": {
129+
"ruc": "12345678912",
130+
"razonSocial": "Project OpenUBL"
131+
},
132+
"detalle": [{
133+
"tipoOperacion": "ADICIONAR",
134+
"comprobante": {
135+
"tipo": "FACTURA",
136+
"serieNumero": "F001-1",
137+
"cliente": {
138+
"tipoDocumentoIdentidad": "RUC",
139+
"numeroDocumentoIdentidad": "12121212121",
140+
"nombre": "nombre de mi cliente"
141+
},
142+
"valorVenta": {
143+
"importeTotal": 100,
144+
"gravado": 100,
145+
"exonerado": 0,
146+
"inafecto": "0",
147+
"gratuito": "0"
148+
},
149+
150+
"impuestos": {
151+
"igv": 22,
152+
"icb": 0
153+
}
154+
}
155+
}, {
156+
"tipoOperacion": "ADICIONAR",
157+
"comprobante": {
158+
"tipo": "NOTA_CREDITO",
159+
"serieNumero": "BC01-1",
160+
"cliente": {
161+
"tipoDocumentoIdentidad": "DNI",
162+
"numeroDocumentoIdentidad": "12121212",
163+
"nombre": "nombre de mi cliente"
164+
},
165+
"valorVenta": {
166+
"importeTotal": 100,
167+
"gravado": 100,
168+
"exonerado": 0,
169+
"inafecto": "0",
170+
"gratuito": "0"
171+
},
172+
173+
"impuestos": {
174+
"igv": 22,
175+
"icb": 0
176+
}
177+
},
178+
"comprobanteAfectado": {
179+
"tipo": "BOLETA",
180+
"serieNumero": "B001-1"
181+
}
182+
}]
183+
}' \
184+
http://localhost:8080/api/documents/summary-document/create
185+
```

‎docusaurus/docs/example.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -74,4 +74,4 @@ curl -X POST \
7474
]
7575
}' \
7676
http://localhost:8080/api/documents/invoice/create
77-
```
77+
```

‎docusaurus/docs/openapi.md

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
id: openapi
3+
title: OpenAPI
4+
---
5+
6+
For interacting with _XBuilder Server_ you need to use the set of REST endpoints _XBuilder Server_ exposes to you.
7+
8+
## Openapi.json
9+
10+
For having access to our REST API documentation you need to have _XBuilder Server_ running and then download our `openapi.json` file through:
11+
12+
- [http://localhost:8080/openapi](http://localhost:8080/openapi)
13+
14+
> You need to change `http://localhost:8080` depending on where you started the server
15+
16+
Once you have the `openapi.json` you can view it through the tool of your preference; we can recommend [Apicur](https://www.apicur.io/) or [Swagger](https://swagger.io/) but it is up to you.

‎docusaurus/docs/sign_xmls.md

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
id: sign_xmls
3+
title: Sign XMLs
4+
---
5+
6+
There are 2 ways of signing your XMLs:
7+
8+
- Create your XML files using `X-OPENBUL-PRIVATEKEY` and `X-OPENUBL-CERTIFICATEKEY` headers.
9+
- Configure the server and use a single certificate to sign all XMLs,
10+
11+
## Method 1: Sign using Headers
12+
13+
You need to provide 3 things:
14+
15+
- **Body** - The body of the request which contains info about the document you are about to create.
16+
- **X-OPENBUL-PRIVATEKEY** - The header which contains the PEM encoded version of your private key.
17+
- **X-OPENUBL-CERTIFICATEKEY** - The header which contains the PEM encoded version of your certificate.
18+
19+
```shell script
20+
curl -X POST \
21+
-H "Content-Type: application/json" \
22+
-H "X-OPENBUL-PRIVATEKEY: MIIEowIBAAKCAQEArhO3H48lGkRNcPNhA6uTd804NnMxBkXKKTgR8DldX8vTmrf0JqNGMLxUlqSG1KlRelHQXvIz7GWO0NgE0DZ9eMEULS7S8YMuj6RZFCudDb/aasxHyCvjVfdKJUF4BIPPKN2dvjFBAQz4fI/3/PceptIqzwzl+8SryXEbJgAUmjaS2POE65RePRIINOV1Vi7lwvLzH0Zl1sr+oytOnXAI1YRlKZhgcS5v5XeX/qfRpbIQdqxcloVAQX/voN8QsLT6chZr/gEZbUnDs2HD286/Xzg27Rw8Bwy7HIbhhKYPK2TsFanpMhsTVtC3gxp6umLb3Fuala7RBC76nDZC9A+95QIDAQABAoIBABhHrbIcMCuivT504+I0K0R5fk6x8HOUhmcLaA0eozR6ZJBe+hHtkhu4GQBOAHRnDXNHOA4WMEHXxHzCtKEqCIQwQhUvQ8Ll7jegz7/teWFykg91YMm9vV6/ODtMD2Zp0Bo+FwNxMUTpPzt4hTlmaoMQK2JnxShBvUhCm2vIdRcxLHV63HjRWqHu98vKYxQ5ByQX3nVBP757zRI2rhC5g0yzQucGj2GMeD3t8W/NozNaUx9qXq2YaqhIYfhbzKZH41ZeIpE0Au7aNS4WBTpWkO1patCpSZHhTV9RIbBCG7al0ukLs3FfbWoHCAJAHUyuEvG4htSb0WqudlJn/rPNdP0CgYEA4SK8NgON4wvdi42dr43NdcOVbWes4HM4M8f1pi7W9RSracuAXj7oeyirKPnUMJchRNOlF/aTghbgtbgAYBFxYYfFbc12BURiAgo6firu6ILD7696V/uxiQPSg/chVrBkN1rYYf1sTgcJB9N7uuiBQZAh8NJWJNvviPVxNfFhoO8CgYEAxfEMCnEBiiOiKi72eclGGAAQr/JAdoaCXZPi1lmbAkWULtyqoo3MzyuyJ3GDwb1j8e2JqPEvqAW8w993Z5vqk/N9MA7rlSE6UPxTHs8ZKNWcdci0rReurG+evrGRRJmKuvqK0/7Nqr/f039VuRqvgtWxJeFoBNZVpwGG/LeCJmsCgYAVcjyhnJcQkNnK6HOj/Isc88OxR1YFj5REAoFZEk8xy4VEr7kLwUxeJxKe9aWL92mY59xrOvb0Rn+jb+LBRAgb9VYOTqs2dzwq25SU3jwh9Ar8MyghZ32TAsU0Av+vBWCWkVXZh82gZTUsBK5dsLZXa4aALVk9a6IW1uKw88yMCwKBgFk3e2jdZIdB5l7DCh78ZFZ++QaE1x9VIz9QX8ajXqWYfODeXx6jcTPTixoSJQPW/ExX91spUoSWCW3ztBsEAKgs8DkQEIkIEAPepwxU5g8ssLe5/g2ihf181f03hbV4yznZoWdKCqMyloz6cMXczEzZSl47iancfYCnxJL1l3j/AoGBAIQDUua/Ia2LLJE24kamiLmdtECHsXg/Wrp++YaGc2btHblAN5TNQfy3S4yvQIOzaVp7AQMXq/AUdua1YcLS1Op/CsocgVMzpckZ7FVS8BFuQnQx8ltnAcqbnCo6UzUdOPKNRw2EDyk9yK83wEtvkvlHOVdRsOlYN5ZSrkq1X92A" \
23+
-H "X-OPENUBL-CERTIFICATEKEY: MIIE+DCCA+CgAwIBAgIJALURz7AYmJ5+MA0GCSqGSIb3DQEBBQUAMIIBDTEbMBkGCgmSJomT8ixkARkWC0xMQU1BLlBFIFNBMQswCQYDVQQGEwJQRTENMAsGA1UECAwETElNQTENMAsGA1UEBwwETElNQTEYMBYGA1UECgwPVFUgRU1QUkVTQSBTLkEuMUUwQwYDVQQLDDxETkkgOTk5OTk5OSBSVUMgMTA0Njc3OTM1NDkgLSBDRVJUSUZJQ0FETyBQQVJBIERFTU9TVFJBQ0nDk04xRDBCBgNVBAMMO05PTUJSRSBSRVBSRVNFTlRBTlRFIExFR0FMIC0gQ0VSVElGSUNBRE8gUEFSQSBERU1PU1RSQUNJw5NOMRwwGgYJKoZIhvcNAQkBFg1kZW1vQGxsYW1hLnBlMB4XDTE5MTEwODEyNTY1MFoXDTIxMTEwNzEyNTY1MFowggENMRswGQYKCZImiZPyLGQBGRYLTExBTUEuUEUgU0ExCzAJBgNVBAYTAlBFMQ0wCwYDVQQIDARMSU1BMQ0wCwYDVQQHDARMSU1BMRgwFgYDVQQKDA9UVSBFTVBSRVNBIFMuQS4xRTBDBgNVBAsMPEROSSA5OTk5OTk5IFJVQyAxMDQ2Nzc5MzU0OSAtIENFUlRJRklDQURPIFBBUkEgREVNT1NUUkFDScOTTjFEMEIGA1UEAww7Tk9NQlJFIFJFUFJFU0VOVEFOVEUgTEVHQUwgLSBDRVJUSUZJQ0FETyBQQVJBIERFTU9TVFJBQ0nDk04xHDAaBgkqhkiG9w0BCQEWDWRlbW9AbGxhbWEucGUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCuE7cfjyUaRE1w82EDq5N3zTg2czEGRcopOBHwOV1fy9Oat/Qmo0YwvFSWpIbUqVF6UdBe8jPsZY7Q2ATQNn14wRQtLtLxgy6PpFkUK50Nv9pqzEfIK+NV90olQXgEg88o3Z2+MUEBDPh8j/f89x6m0irPDOX7xKvJcRsmABSaNpLY84TrlF49Egg05XVWLuXC8vMfRmXWyv6jK06dcAjVhGUpmGBxLm/ld5f+p9GlshB2rFyWhUBBf++g3xCwtPpyFmv+ARltScOzYcPbzr9fODbtHDwHDLschuGEpg8rZOwVqekyGxNW0LeDGnq6YtvcW5qVrtEELvqcNkL0D73lAgMBAAGjVzBVMB0GA1UdDgQWBBTe18LHVKkeRrWs3Bxp1ikK50l96jAfBgNVHSMEGDAWgBTe18LHVKkeRrWs3Bxp1ikK50l96jATBgNVHSUEDDAKBggrBgEFBQcDATANBgkqhkiG9w0BAQUFAAOCAQEASBWcP4AiqUUZSG2/Z3RU3BgvOVV3if8xYAaZT99n5PsvyBiZ3Gh6VpAW9ezoe25ZNSqGMmGfq+R4mEuiqK4h6jDJp0fN47IwRhWjttB9dwpxIDEkWW7zPdueGx+BY8EuyfNDWR/C7GPfu6azSHiapzeKC57AAZ8xo8kDdhXxDy8hTqNGolkqnc6QutW8cYPeonqyhi2THN163lZ3Cx5OV8vGFQ3ou2msF0klY9qXopI9i8wQjEeOG6bCvVxdID9ZjTbuGbO9pAN9hH7hZ41XEG/CspSWbFf1/Wbnlfusne9v9NgRj0MM+LAHM7AO5/7j1XwRq4x+U9TSVPgpoU9l5Q==" \
24+
-d '{
25+
"serie": "F001",
26+
"numero": 1,
27+
"proveedor": {
28+
"ruc": "12345678912",
29+
"razonSocial": "Project OpenUBL"
30+
},
31+
"cliente": {
32+
"tipoDocumentoIdentidad": "RUC",
33+
"numeroDocumentoIdentidad": "12312312312",
34+
"nombre": "Nombre de mi cliente"
35+
},
36+
"detalle": [
37+
{
38+
"descripcion": "Nombre de producto o servicio",
39+
"precioUnitario": 1,
40+
"cantidad": 1,
41+
"tipoIgv": "GRAVADO_OPERACION_ONEROSA"
42+
}
43+
]
44+
}' \
45+
http://localhost:8080/api/documents/invoice/create
46+
```
47+
48+
## Method 2: Sign configuring the server
49+
50+
You need to configure the properties `openubl.server.keystore.location` and `openubl.server.keystore.password` so every single XML is signed.
51+
52+
> Even after using this method you are always able to override the certificate to sign an XML using the previous method.
53+
54+
| variable | default value | description |
55+
| -------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------ |
56+
| openubl.server.keystore.location | _null_ | (Optional) The location of the certificate you want to use if you'd like to sign all your certificates |
57+
| openubl.server.keystore.password | _null_ | (Optional) The password of the certificate you want to use if you'd like to sign all your certificates |
58+
59+
To know more about how to override properties in the server read [Configuration](./configuration)

‎docusaurus/sidebars.js

+1
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,6 @@ module.exports = {
22
someSidebar: {
33
"XBuilder Server": ["introduction", "design_principles", "contributing"],
44
"Getting started": ["installation", "example"],
5+
Guides: ["openapi", "create_xmls", "sign_xmls", "configuration"],
56
},
67
};

0 commit comments

Comments
 (0)