125 lines
4.1 KiB
Markdown
125 lines
4.1 KiB
Markdown
# jtlsrv
|
|
|
|
Built on **libuv** (event loop), **OpenSSL** (TLS), **llhttp** (HTTP parsing), **unixODBC** + [**ODBC Driver 18 for SQL Server**](https://learn.microsoft.com/en-us/sql/connect/odbc/microsoft-odbc-driver-for-sql-server) (database), and **libvips** (image thumbnails). Blocking work (ODBC queries, image processing) runs on libuv worker threads.
|
|
|
|
## Requirements
|
|
|
|
| Dependency | Purpose |
|
|
|---|---|
|
|
| C++17 compiler | gcc or clang |
|
|
| GNU Make | Build |
|
|
| pkg-config | Dependency flags |
|
|
| libuv | Async I/O and thread pool |
|
|
| OpenSSL | TLS |
|
|
| libvips | Product/category image resizing |
|
|
| unixODBC + dev headers | ODBC runtime |
|
|
| [ODBC Driver 18 for SQL Server](https://learn.microsoft.com/en-us/sql/connect/odbc/microsoft-odbc-driver-for-sql-server) | Connect to JTL-Wawi (MSSQL) |
|
|
|
|
Vendored in `vendor/`: **llhttp**, **nlohmann/json** (no install needed).
|
|
|
|
### Install on Ubuntu / Debian
|
|
|
|
```bash
|
|
sudo apt install \
|
|
build-essential make pkg-config \
|
|
libuv1-dev libssl-dev libvips-dev unixodbc-dev
|
|
```
|
|
|
|
Install [Microsoft's ODBC driver](https://learn.microsoft.com/en-us/sql/connect/odbc/microsoft-odbc-driver-for-sql-server) (required for MSSQL):
|
|
|
|
```bash
|
|
curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | \
|
|
sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
|
|
|
|
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/microsoft-prod.gpg] \
|
|
https://packages.microsoft.com/ubuntu/$(lsb_release -rs)/prod $(lsb_release -cs) main" | \
|
|
sudo tee /etc/apt/sources.list.d/mssql-release.list
|
|
|
|
sudo apt update
|
|
sudo ACCEPT_EULA=Y apt install msodbcsql18
|
|
```
|
|
|
|
## Build
|
|
|
|
```bash
|
|
make
|
|
```
|
|
|
|
The binary is written to `./jtlsrv`. After code changes always run `make` before starting the server.
|
|
|
|
Debug build:
|
|
|
|
```bash
|
|
make debug
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Copy the example env file from the repo root and edit as needed:
|
|
|
|
```bash
|
|
cp ../.env.example .env
|
|
```
|
|
|
|
Key settings:
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `PORT` | `4443` | HTTPS listen port |
|
|
| `PAIRING_CODE` | `307018` | Code shown to the POS during pairing |
|
|
| `AUTH_TOKEN` | (built-in default) | Device auth token after pairing |
|
|
| `MSSQL_*` | — | JTL-Wawi database connection |
|
|
| `MANDANT_*` | — | Mandant metadata returned to the client |
|
|
| `ROOT_CATEGORY_ID` | `1` | Root category for sync |
|
|
| `TAX_ZONE_NAME` | `Zone-EU` | Tax zone for product prices |
|
|
| `LOG_FILE` | `logs/requests.log` | Request log path |
|
|
| `ORDER_LOG_FILE` | `logs/orders.log` | Order log path |
|
|
|
|
The server starts without MSSQL if `MSSQL_USER` is unset or the connection fails — pairing and handshake still work, but catalog sync from the database is unavailable.
|
|
|
|
## TLS certificates
|
|
|
|
Place a certificate and key at `certs/cert.pem` and `certs/key.pem` (relative to the working directory when you run the binary).
|
|
|
|
```bash
|
|
mkdir -p certs
|
|
openssl req -x509 -newkey rsa:2048 -nodes \
|
|
-keyout certs/key.pem -out certs/cert.pem -days 3650 \
|
|
-subj '/CN=localhost/O=JTL POS Sync/C=DE' \
|
|
-addext 'subjectAltName=DNS:localhost,IP:127.0.0.1,IP:0.0.0.0'
|
|
```
|
|
|
|
On startup the server prints the pairing code and whether MSSQL connected.
|
|
|
|
## API endpoints
|
|
|
|
| Method | Path | Description |
|
|
|---|---|---|
|
|
| GET | `/v1/client` | Client discovery / pairing |
|
|
| GET | `/v1/init` | Init handshake |
|
|
| GET | `/v1/category` | Category sync |
|
|
| GET | `/v1/product` | Product sync |
|
|
| GET | `/v1/productcomposite` | Composite product sync |
|
|
| GET | `/v1/deletedentity` | Deleted entity sync |
|
|
| GET | `/v1/customergroup` | Customer group sync |
|
|
| POST | `/v1/order` | Submit orders |
|
|
| GET | `/v1/pimage` | Product image (resized) |
|
|
| GET | `/v1/cimage` | Category image (resized) |
|
|
|
|
## Project layout
|
|
|
|
```
|
|
Makefile
|
|
src/
|
|
main.cpp Entry point, route registration, startup
|
|
config.hpp .env loader
|
|
tls_server.{hpp,cpp} HTTPS over libuv + OpenSSL
|
|
http.{hpp,cpp} llhttp request/response handling
|
|
router.{hpp,cpp} Route dispatch
|
|
pairing.{hpp,cpp} In-memory pairing store
|
|
endpoints/ HTTP handlers
|
|
queries/ SQL query builders (header-only)
|
|
db/pool.{hpp,cpp} ODBC connection pool
|
|
vendor/ llhttp, nlohmann/json
|
|
```
|