Skip to content

Commit d5b6f27

Browse files
dseichterdseichter
authored
Merge pull request #186 from dseichter/dseichter/issue184
#184 Implement Rest API
2 parents d639b13 + d90b4ba commit d5b6f27

14 files changed

Lines changed: 863 additions & 7 deletions

‎.github/workflows/release.yml‎

Lines changed: 110 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,41 @@ jobs:
7272
with:
7373
name: VATValidation-cli-windows-${{ github.ref_name }}.exe
7474
path: dist/VATValidation-cli-windows-${{ github.ref_name }}.exe
75+
76+
build-windows-binary-api:
77+
runs-on: windows-latest
78+
steps:
79+
80+
- name: 'Checkout'
81+
uses: actions/checkout@0c366fd6a839edf440554fa01a7085ccba70ac98 # v6
82+
83+
- name: Set up Python
84+
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
85+
with:
86+
python-version: 3.14
87+
88+
- name: Create and start virtual environment
89+
run: |
90+
python3 -m venv venv
91+
venv\Scripts\activate.bat
92+
93+
- name: Remove PySide6 dependencies from requirements
94+
run: |
95+
type src\requirements.txt | findstr /v "PySide6" >> src\requirements_new.txt
96+
del src\requirements.txt
97+
ren src\requirements_new.txt requirements.txt
98+
99+
- name: Install dependencies
100+
run: pip install -r src/requirements.txt
101+
102+
- name: Build Windows API binary
103+
run: pyinstaller --onefile src/vatvalidation_api.py -n VATValidation-api-windows-${{ github.ref_name }}.exe
104+
105+
- name: Upload artifact
106+
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
107+
with:
108+
name: VATValidation-api-windows-${{ github.ref_name }}.exe
109+
path: dist/VATValidation-api-windows-${{ github.ref_name }}.exe
75110

76111
test-cli-windows:
77112
runs-on: windows-latest
@@ -87,6 +122,20 @@ jobs:
87122
run: |
88123
VATValidation-cli-windows-${{ github.ref_name }}.exe --version
89124
125+
test-api-windows:
126+
runs-on: windows-latest
127+
needs: [build-windows-binary-api]
128+
steps:
129+
130+
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
131+
with:
132+
name: VATValidation-api-windows-${{ github.ref_name }}.exe
133+
134+
- name: Run tests
135+
shell: cmd
136+
run: |
137+
VATValidation-api-windows-${{ github.ref_name }}.exe --version
138+
90139
build-linux-binary:
91140
runs-on: ubuntu-latest
92141
steps:
@@ -154,6 +203,41 @@ jobs:
154203
name: VATValidation-cli-linux-${{ github.ref_name }}
155204
path: dist/VATValidation-cli-linux-${{ github.ref_name }}
156205

206+
build-linux-binary-api:
207+
runs-on: ubuntu-latest
208+
steps:
209+
210+
- name: 'Checkout'
211+
uses: actions/checkout@0c366fd6a839edf440554fa01a7085ccba70ac98 # v6
212+
213+
- name: Update system packages
214+
run: sudo apt-get update
215+
216+
- name: Set up Python
217+
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
218+
with:
219+
python-version: 3.14
220+
221+
- name: Create and start virtual environment
222+
run: |
223+
python3 -m venv venv
224+
source venv/bin/activate
225+
226+
- name: Remove PySide6 from requirements
227+
run: sed -i '/PySide6/d' src/requirements.txt
228+
229+
- name: Install dependencies
230+
run: pip install -r src/requirements.txt
231+
232+
- name: Build Linux API binary
233+
run: pyinstaller --onefile src/vatvalidation_api.py -n VATValidation-api-linux-${{ github.ref_name }}
234+
235+
- name: Upload artifact
236+
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
237+
with:
238+
name: VATValidation-api-linux-${{ github.ref_name }}
239+
path: dist/VATValidation-api-linux-${{ github.ref_name }}
240+
157241
test-cli-linux:
158242
runs-on: ubuntu-latest
159243
needs: [build-linux-binary-cli]
@@ -168,9 +252,23 @@ jobs:
168252
chmod +x VATValidation-cli-linux-${{ github.ref_name }}
169253
./VATValidation-cli-linux-${{ github.ref_name }} --version
170254
255+
test-api-linux:
256+
runs-on: ubuntu-latest
257+
needs: [build-linux-binary-api]
258+
steps:
259+
260+
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
261+
with:
262+
name: VATValidation-api-linux-${{ github.ref_name }}
263+
264+
- name: Run tests
265+
run: |
266+
chmod +x VATValidation-api-linux-${{ github.ref_name }}
267+
./VATValidation-api-linux-${{ github.ref_name }} --version
268+
171269
deploy:
172270
runs-on: ubuntu-latest
173-
needs: [build-windows-binary, build-linux-binary, test-cli-windows, test-cli-linux]
271+
needs: [build-windows-binary, build-linux-binary, test-cli-windows, test-cli-linux, test-api-windows, test-api-linux]
174272
steps:
175273
- name: Checkout
176274
uses: actions/checkout@0c366fd6a839edf440554fa01a7085ccba70ac98 # v6
@@ -185,6 +283,10 @@ jobs:
185283
with:
186284
name: VATValidation-cli-linux-${{ github.ref_name }}
187285

286+
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
287+
with:
288+
name: VATValidation-api-linux-${{ github.ref_name }}
289+
188290
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
189291
with:
190292
name: VATValidation-windows-${{ github.ref_name }}.exe
@@ -193,6 +295,10 @@ jobs:
193295
with:
194296
name: VATValidation-cli-windows-${{ github.ref_name }}.exe
195297

298+
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
299+
with:
300+
name: VATValidation-api-windows-${{ github.ref_name }}.exe
301+
196302
- name: Generate Release Notes
197303
id: release_notes
198304
run: |
@@ -262,4 +368,6 @@ jobs:
262368
VATValidation-linux-${{ github.ref_name }}
263369
VATValidation-windows-${{ github.ref_name }}.exe
264370
VATValidation-cli-linux-${{ github.ref_name }}
265-
VATValidation-cli-windows-${{ github.ref_name }}.exe
371+
VATValidation-cli-windows-${{ github.ref_name }}.exe
372+
VATValidation-api-linux-${{ github.ref_name }}
373+
VATValidation-api-windows-${{ github.ref_name }}.exe

‎README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,8 @@ Binaries for Windows and Linux are available in the <a href="https://github.com/
4242
- 🇪🇺 Validation using VIES (EU VAT numbers)
4343
- 🇬🇧 Validation using HMRC (check UK VAT numbers)
4444
- 🇨🇭 Validation using Swiss UID (check Swiss VAT numbers)
45-
- 🛠️ CLI batch processing (see releases)
45+
- 🛠️ CLI processing (see releases)
46+
- 🌐 FastAPI-based REST API (see documentation) (new in v2026-05-12 (not released yet))
4647
- 🔒 No manual Python dependency installation required for release binaries
4748

4849
Since 2026 the old BZSt interface has been shutdown. The new BZSt API is now supported.
@@ -60,6 +61,8 @@ If you like this software, please give it a ⭐ or send a 💰 donation in the a
6061
For full documentation, usage instructions, configuration, screenshots, and contributing guidelines,
6162
please visit the [project documentation](https://dseichter.github.io/VATValidation/).
6263

64+
Runtime settings are persisted in `src/config.json` (or the generated runtime config file), including proxy and logging values (`proxy_mode`, `proxy_url`, `proxy_username`, `proxy_password`, `logfilename`, `loglevel`).
65+
6366
---
6467

6568
## 📄 License

‎docs/docs/api.de.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# REST API
2+
3+
VATValidation bietet eine FastAPI-basierte REST-API für Einzel- und Batch-Validierung.
4+
5+
## Binärdatei
6+
7+
Die Release-Pipeline erstellt eigene API-Binaries:
8+
9+
- `VATValidation-api-windows-<version>.exe`
10+
- `VATValidation-api-linux-<version>`
11+
12+
Download über [Releases](https://github.com/dseichter/VATValidation/releases).
13+
14+
## API-Server starten
15+
16+
Windows (Standard: localhost):
17+
18+
```shell
19+
VATValidation-api-windows-v2026-05-12.exe --port 8080 --proxy-mode manual --proxy-url http://127.0.0.1:8080
20+
```
21+
22+
Linux (Standard: localhost):
23+
24+
```shell
25+
./VATValidation-api-linux-v2026-05-12 --port 8080 --proxy-mode system
26+
```
27+
28+
Standard ist `127.0.0.1` als Host und `8080` als Port.
29+
30+
Wenn die API absichtlich auf allen Interfaces erreichbar sein soll, geben Sie `--host 0.0.0.0` explizit an.
31+
32+
Proxy-Einstellungen werden einmal beim Start gesetzt und in die Konfigurationsdatei geschrieben, nicht im Request-Payload übergeben.
33+
34+
Das Logging wird ebenfalls über diese Konfigurationsdatei gesteuert. Relevante Schlüssel sind `logfilename` und `loglevel` (Standard in diesem Repository: `/tmp/vatvalidation.log` mit `ERROR`).
35+
36+
## Endpunkte
37+
38+
- `GET /health`
39+
- `POST /api/v1/validate/single`
40+
- `POST /api/v1/validate/batch`
41+
- `GET /api/v1/jobs/{job_id}`
42+
- `GET /api/v1/jobs`
43+
44+
### Request für Einzelvalidierung
45+
46+
```json
47+
{
48+
"ownvat": "DE123456789",
49+
"vat": "FR12345678901",
50+
"company": "Sample GmbH",
51+
"street": "Musterstrasse 1",
52+
"zip": "10115",
53+
"town": "Berlin",
54+
"interface": "vies",
55+
"lang": "en"
56+
}
57+
```
58+
59+
### Request für Batch-Validierung
60+
61+
```json
62+
{
63+
"input": "input.csv",
64+
"output": "output.csv",
65+
"delimiter": ";",
66+
"interface": "vies",
67+
"lang": "en",
68+
"ignore_validation_errors": false
69+
}
70+
```
71+
72+
Die Batch-Validierung läuft asynchron und liefert eine `job_id` zurück.
73+
74+
## Asynchroner Batch-Ablauf (job_id Polling)
75+
76+
1. Batch-Job starten:
77+
78+
```shell
79+
curl -X POST http://localhost:8080/api/v1/validate/batch \
80+
-H "Content-Type: application/json" \
81+
-d '{
82+
"input": "input.csv",
83+
"output": "output.csv",
84+
"delimiter": ";",
85+
"interface": "vies",
86+
"lang": "en",
87+
"ignore_validation_errors": false
88+
}'
89+
```
90+
91+
Beispielantwort:
92+
93+
```json
94+
{
95+
"job_id": "d5242f38-6e3a-4f75-9d0e-3d8cc9f4e5a8",
96+
"status": "queued",
97+
"status_url": "/api/v1/jobs/d5242f38-6e3a-4f75-9d0e-3d8cc9f4e5a8"
98+
}
99+
```
100+
101+
2. Aktuellen Status über `job_id` abfragen:
102+
103+
```shell
104+
curl http://localhost:8080/api/v1/jobs/d5242f38-6e3a-4f75-9d0e-3d8cc9f4e5a8
105+
```
106+
107+
Beispielantwort während der Verarbeitung:
108+
109+
```json
110+
{
111+
"job_id": "d5242f38-6e3a-4f75-9d0e-3d8cc9f4e5a8",
112+
"status": "running",
113+
"created_at": "2026-05-11T10:00:00+00:00",
114+
"started_at": "2026-05-11T10:00:01+00:00",
115+
"input": "input.csv",
116+
"output": "output.csv",
117+
"result_code": null,
118+
"ok": null,
119+
"error": null
120+
}
121+
```
122+
123+
Beispielantwort nach Abschluss:
124+
125+
```json
126+
{
127+
"job_id": "d5242f38-6e3a-4f75-9d0e-3d8cc9f4e5a8",
128+
"status": "finished",
129+
"created_at": "2026-05-11T10:00:00+00:00",
130+
"started_at": "2026-05-11T10:00:01+00:00",
131+
"finished_at": "2026-05-11T10:00:08+00:00",
132+
"input": "input.csv",
133+
"output": "output.csv",
134+
"result_code": 0,
135+
"ok": true,
136+
"error": null
137+
}
138+
```
139+
140+
3. Optional: alle aktuell im Speicher gehaltenen Jobs auflisten:
141+
142+
```shell
143+
curl http://localhost:8080/api/v1/jobs
144+
```
145+
146+
## OpenAPI-Spezifikation
147+
148+
FastAPI stellt automatisch bereit:
149+
150+
- OpenAPI JSON: `GET /openapi.json`
151+
- Swagger UI: `GET /docs`
152+
- ReDoc: `GET /redoc`
153+
154+
Zusätzlich gibt es eine statische Referenz-Spezifikation in diesem Repository unter `docs/docs/openapi.yaml`.
155+
156+
Sie können die OpenAPI-Spezifikation auch aus der Binärdatei exportieren:
157+
158+
Windows:
159+
160+
```shell
161+
VATValidation-api-windows-v2026-05-12.exe --export-openapi openapi.json
162+
```
163+
164+
Linux:
165+
166+
```shell
167+
./VATValidation-api-linux-v2026-05-12 --export-openapi openapi.json
168+
```

0 commit comments

Comments
 (0)