495 lines
15 KiB
Markdown
495 lines
15 KiB
Markdown
# Invoice print setup
|
|
|
|
This guide creates the invoice tables and Steel calculations through the gRPC
|
|
API, installs the Typst template used by the print page, inserts example data,
|
|
and compiles the exported JSON into a PDF.
|
|
|
|
Run the commands from the repository root. The server address used by the
|
|
client is `[::1]:50051`.
|
|
|
|
## 1. Configure grpcurl
|
|
|
|
```bash
|
|
PROFILE="fakturacia_2026"
|
|
GRPC_ADDR="[::1]:50051"
|
|
```
|
|
|
|
Log in. Keep `-d` and its JSON argument on the same logical command line:
|
|
|
|
```bash
|
|
grpcurl -plaintext \
|
|
-import-path common/proto \
|
|
-proto auth.proto \
|
|
-d '{"identifier":"YOUR_USERNAME","password":"YOUR_PASSWORD"}' \
|
|
"$GRPC_ADDR" \
|
|
komp_ac.auth.AuthService/Login
|
|
```
|
|
|
|
Copy the returned `access_token`:
|
|
|
|
```bash
|
|
TOKEN="PASTE_ACCESS_TOKEN_HERE"
|
|
AUTH_HEADER="authorization: Bearer $TOKEN"
|
|
```
|
|
|
|
The account must have the administrator role for table and script creation.
|
|
|
|
Table definitions and Steel scripts require an `admin` token. Row data writes
|
|
require an `accountant` token. Keep the two tokens in separate shell variables,
|
|
for example:
|
|
|
|
```bash
|
|
ADMIN_TOKEN="PASTE_ADMIN_ACCESS_TOKEN_HERE"
|
|
ACCOUNTANT_TOKEN="PASTE_ACCOUNTANT_ACCESS_TOKEN_HERE"
|
|
ADMIN_AUTH_HEADER="authorization: Bearer $ADMIN_TOKEN"
|
|
ACCOUNTANT_AUTH_HEADER="authorization: Bearer $ACCOUNTANT_TOKEN"
|
|
```
|
|
|
|
Use `ADMIN_AUTH_HEADER` for the table-definition and table-script calls. Use
|
|
`ACCOUNTANT_AUTH_HEADER` for the `TablesData/PostTableData` calls below.
|
|
|
|
If you do not know an existing password, create a new administrator account
|
|
on a trusted local development server. The registration endpoint currently
|
|
accepts the requested role, so do not expose this unauthenticated endpoint to
|
|
an untrusted network.
|
|
|
|
```bash
|
|
grpcurl -plaintext \
|
|
-import-path common/proto \
|
|
-proto auth.proto \
|
|
-d '{
|
|
"username":"invoice_admin",
|
|
"email":"invoice_admin@example.test",
|
|
"password":"CHANGE_THIS_PASSWORD",
|
|
"password_confirmation":"CHANGE_THIS_PASSWORD",
|
|
"role":"admin",
|
|
"timezone":"Europe/Bratislava",
|
|
"phone_country":"SK"
|
|
}' \
|
|
"$GRPC_ADDR" \
|
|
komp_ac.auth.AuthService/Register
|
|
```
|
|
|
|
Then log in with the same credentials and copy the returned token:
|
|
|
|
```bash
|
|
grpcurl -plaintext \
|
|
-import-path common/proto \
|
|
-proto auth.proto \
|
|
-d '{"identifier":"invoice_admin","password":"CHANGE_THIS_PASSWORD"}' \
|
|
"$GRPC_ADDR" \
|
|
komp_ac.auth.AuthService/Login
|
|
```
|
|
|
|
The `Invalid credentials` response means the username/email or password is
|
|
wrong. Sending only `{"identifier":"admin"}` cannot work because the login
|
|
request still requires a valid password. A temporary `connection refused`
|
|
means the server was not listening at that moment; retry after starting the
|
|
server.
|
|
|
|
## 2. Create the tables
|
|
|
|
Create referenced tables first.
|
|
|
|
### Supplier
|
|
|
|
```bash
|
|
grpcurl -plaintext -H "$AUTH_HEADER" \
|
|
-import-path common/proto -proto table_definition.proto \
|
|
-d '{
|
|
"profile_name":"fakturacia_2026",
|
|
"table_name":"dodavatel",
|
|
"row_display_column":"nazov",
|
|
"columns":[
|
|
{"name":"nazov","field_type":"TEXT"},
|
|
{"name":"ulica","field_type":"TEXT"},
|
|
{"name":"mesto","field_type":"TEXT"},
|
|
{"name":"ico","field_type":"TEXT"},
|
|
{"name":"dic","field_type":"TEXT"},
|
|
{"name":"icdph","field_type":"TEXT"},
|
|
{"name":"iban","field_type":"TEXT"},
|
|
{"name":"banka","field_type":"TEXT"},
|
|
{"name":"telefon","field_type":"TEXT"},
|
|
{"name":"email","field_type":"TEXT"}
|
|
]
|
|
}' \
|
|
"$GRPC_ADDR" komp_ac.table_definition.TableDefinition/PostTableDefinition
|
|
```
|
|
|
|
### Customer
|
|
|
|
```bash
|
|
grpcurl -plaintext -H "$AUTH_HEADER" \
|
|
-import-path common/proto -proto table_definition.proto \
|
|
-d '{
|
|
"profile_name":"fakturacia_2026",
|
|
"table_name":"odberatel",
|
|
"row_display_column":"nazov",
|
|
"columns":[
|
|
{"name":"nazov","field_type":"TEXT"},
|
|
{"name":"ulica","field_type":"TEXT"},
|
|
{"name":"mesto","field_type":"TEXT"},
|
|
{"name":"ico","field_type":"TEXT"},
|
|
{"name":"dic","field_type":"TEXT"},
|
|
{"name":"icdph","field_type":"TEXT"}
|
|
]
|
|
}' \
|
|
"$GRPC_ADDR" komp_ac.table_definition.TableDefinition/PostTableDefinition
|
|
```
|
|
|
|
### Invoice
|
|
|
|
```bash
|
|
grpcurl -plaintext -H "$AUTH_HEADER" \
|
|
-import-path common/proto -proto table_definition.proto \
|
|
-d '{
|
|
"profile_name":"fakturacia_2026",
|
|
"table_name":"faktura",
|
|
"row_display_column":"cislo",
|
|
"base_currency":"EUR",
|
|
"links":[
|
|
{"linked_table_name":"dodavatel","required":true},
|
|
{"linked_table_name":"odberatel","required":true}
|
|
],
|
|
"columns":[
|
|
{"name":"cislo","field_type":"TEXT"},
|
|
{"name":"datum_vystavenia","field_type":"DATE"},
|
|
{"name":"datum_dodania","field_type":"DATE"},
|
|
{"name":"datum_splatnosti","field_type":"DATE"},
|
|
{"name":"variabilny_symbol","field_type":"TEXT"},
|
|
{"name":"sposob_uhrady","field_type":"TEXT"},
|
|
{"name":"zaklad_dane","field_type":"MONEY","rounding":"MONEY_ROUNDING_HALF_UP","recompute_on_dependency_change":true},
|
|
{"name":"dph_celkom","field_type":"MONEY","rounding":"MONEY_ROUNDING_HALF_UP","recompute_on_dependency_change":true},
|
|
{"name":"celkom_spolu","field_type":"MONEY","rounding":"MONEY_ROUNDING_HALF_UP","recompute_on_dependency_change":true},
|
|
{"name":"poznamka","field_type":"TEXT"}
|
|
]
|
|
}' \
|
|
"$GRPC_ADDR" komp_ac.table_definition.TableDefinition/PostTableDefinition
|
|
```
|
|
|
|
### Invoice item
|
|
|
|
```bash
|
|
grpcurl -plaintext -H "$AUTH_HEADER" \
|
|
-import-path common/proto -proto table_definition.proto \
|
|
-d '{
|
|
"profile_name":"fakturacia_2026",
|
|
"table_name":"polozka",
|
|
"row_display_column":"nazov",
|
|
"base_currency":"EUR",
|
|
"links":[{"linked_table_name":"faktura","required":true}],
|
|
"columns":[
|
|
{"name":"nazov","field_type":"TEXT"},
|
|
{"name":"mnozstvo","field_type":"DECIMAL(12,3)"},
|
|
{"name":"mj","field_type":"TEXT"},
|
|
{"name":"cena","field_type":"MONEY","rounding":"MONEY_ROUNDING_HALF_UP"},
|
|
{"name":"dph","field_type":"DECIMAL(5,2)"},
|
|
{"name":"bez","field_type":"MONEY","rounding":"MONEY_ROUNDING_HALF_UP","recompute_on_dependency_change":true},
|
|
{"name":"dph_suma","field_type":"MONEY","rounding":"MONEY_ROUNDING_HALF_UP","recompute_on_dependency_change":true},
|
|
{"name":"spolu","field_type":"MONEY","rounding":"MONEY_ROUNDING_HALF_UP","recompute_on_dependency_change":true}
|
|
]
|
|
}' \
|
|
"$GRPC_ADDR" komp_ac.table_definition.TableDefinition/PostTableDefinition
|
|
```
|
|
|
|
## 3. Get table IDs
|
|
|
|
Use `table_definition.proto`, not `common.proto`, for this service call:
|
|
|
|
```bash
|
|
TREE=$(grpcurl -plaintext -H "$AUTH_HEADER" \
|
|
-import-path common/proto -proto table_definition.proto \
|
|
-d '{}' "$GRPC_ADDR" \
|
|
komp_ac.table_definition.TableDefinition/GetProfileTree)
|
|
|
|
echo "$TREE" | jq .
|
|
|
|
FAKTURA_ID=$(echo "$TREE" | jq -r \
|
|
'.profiles[] | select(.name=="fakturacia_2026") | .tables[] | select(.name=="faktura") | .id')
|
|
|
|
POLOZKA_ID=$(echo "$TREE" | jq -r \
|
|
'.profiles[] | select(.name=="fakturacia_2026") | .tables[] | select(.name=="polozka") | .id')
|
|
```
|
|
|
|
## 4. Add Steel calculations
|
|
|
|
The script API requires expressions beginning with `(`. Money values must be
|
|
combined using the money functions; do not use ordinary decimal `+` on MONEY.
|
|
|
|
```bash
|
|
grpcurl -plaintext -H "$AUTH_HEADER" \
|
|
-import-path common/proto -proto table_script.proto \
|
|
-d "{
|
|
\"table_definition_id\":$POLOZKA_ID,
|
|
\"target_column\":\"bez\",
|
|
\"script\":\"(money-mul (steel_get_column \\\"polozka\\\" \\\"cena\\\") (steel_get_column \\\"polozka\\\" \\\"mnozstvo\\\"))\",
|
|
\"description\":\"Quantity multiplied by unit price\"
|
|
}" \
|
|
"$GRPC_ADDR" komp_ac.table_script.TableScript/PostTableScript
|
|
```
|
|
|
|
```bash
|
|
grpcurl -plaintext -H "$AUTH_HEADER" \
|
|
-import-path common/proto -proto table_script.proto \
|
|
-d "{
|
|
\"table_definition_id\":$POLOZKA_ID,
|
|
\"target_column\":\"dph_suma\",
|
|
\"script\":\"(money-div (money-mul (steel_get_column \\\"polozka\\\" \\\"bez\\\") (steel_get_column \\\"polozka\\\" \\\"dph\\\")) \\\"100\\\")\",
|
|
\"description\":\"VAT amount\"
|
|
}" \
|
|
"$GRPC_ADDR" komp_ac.table_script.TableScript/PostTableScript
|
|
```
|
|
|
|
```bash
|
|
grpcurl -plaintext -H "$AUTH_HEADER" \
|
|
-import-path common/proto -proto table_script.proto \
|
|
-d "{
|
|
\"table_definition_id\":$POLOZKA_ID,
|
|
\"target_column\":\"spolu\",
|
|
\"script\":\"(money-add (steel_get_column \\\"polozka\\\" \\\"bez\\\") (steel_get_column \\\"polozka\\\" \\\"dph_suma\\\"))\",
|
|
\"description\":\"Total including VAT\"
|
|
}" \
|
|
"$GRPC_ADDR" komp_ac.table_script.TableScript/PostTableScript
|
|
```
|
|
|
|
Invoice aggregate scripts:
|
|
|
|
```bash
|
|
grpcurl -plaintext -H "$AUTH_HEADER" \
|
|
-import-path common/proto -proto table_script.proto \
|
|
-d "{
|
|
\"table_definition_id\":$FAKTURA_ID,
|
|
\"target_column\":\"zaklad_dane\",
|
|
\"script\":\"(money-add (steel_related_aggregate \\\"sum\\\" \\\"polozka\\\" \\\"bez\\\" \\\"faktura\\\") (money-new \\\"EUR\\\" \\\"0\\\"))\"
|
|
}" \
|
|
"$GRPC_ADDR" komp_ac.table_script.TableScript/PostTableScript
|
|
```
|
|
|
|
```bash
|
|
grpcurl -plaintext -H "$AUTH_HEADER" \
|
|
-import-path common/proto -proto table_script.proto \
|
|
-d "{
|
|
\"table_definition_id\":$FAKTURA_ID,
|
|
\"target_column\":\"dph_celkom\",
|
|
\"script\":\"(money-add (steel_related_aggregate \\\"sum\\\" \\\"polozka\\\" \\\"dph_suma\\\" \\\"faktura\\\") (money-new \\\"EUR\\\" \\\"0\\\"))\"
|
|
}" \
|
|
"$GRPC_ADDR" komp_ac.table_script.TableScript/PostTableScript
|
|
```
|
|
|
|
```bash
|
|
grpcurl -plaintext -H "$AUTH_HEADER" \
|
|
-import-path common/proto -proto table_script.proto \
|
|
-d "{
|
|
\"table_definition_id\":$FAKTURA_ID,
|
|
\"target_column\":\"celkom_spolu\",
|
|
\"script\":\"(money-add (steel_related_aggregate \\\"sum\\\" \\\"polozka\\\" \\\"spolu\\\" \\\"faktura\\\") (money-new \\\"EUR\\\" \\\"0\\\"))\"
|
|
}" \
|
|
"$GRPC_ADDR" komp_ac.table_script.TableScript/PostTableScript
|
|
```
|
|
|
|
## 5. Insert data
|
|
|
|
Insert supplier and customer rows first. The API returns their IDs.
|
|
|
|
```bash
|
|
grpcurl -plaintext -H "$AUTH_HEADER" \
|
|
-import-path common/proto -proto tables_data.proto \
|
|
-d '{
|
|
"profile_name":"fakturacia_2026",
|
|
"table_name":"dodavatel",
|
|
"data":{
|
|
"nazov":"Kreatív Studio s.r.o.",
|
|
"ulica":"Štúrova 8",
|
|
"mesto":"040 01 Košice",
|
|
"ico":"45612378",
|
|
"dic":"2022998877",
|
|
"icdph":"SK2022998877",
|
|
"iban":"SK89 1100 0000 0026 1234 5678",
|
|
"banka":"Tatra banka, a.s.",
|
|
"telefon":"+421 911 222 333",
|
|
"email":"fakturacia@kreativstudio.sk"
|
|
}
|
|
}' \
|
|
"$GRPC_ADDR" komp_ac.tables_data.TablesData/PostTableData
|
|
```
|
|
|
|
```bash
|
|
grpcurl -plaintext -H "$AUTH_HEADER" \
|
|
-import-path common/proto -proto tables_data.proto \
|
|
-d '{
|
|
"profile_name":"fakturacia_2026",
|
|
"table_name":"odberatel",
|
|
"data":{
|
|
"nazov":"Nová Kaviareň s.r.o.",
|
|
"ulica":"Námestie SNP 12",
|
|
"mesto":"974 01 Banská Bystrica",
|
|
"ico":"51239876",
|
|
"dic":"2120654321",
|
|
"icdph":"SK2120654321"
|
|
}
|
|
}' \
|
|
"$GRPC_ADDR" komp_ac.tables_data.TablesData/PostTableData
|
|
```
|
|
|
|
Set the returned IDs:
|
|
|
|
```bash
|
|
DODAVATEL_ID="1"
|
|
ODBERATEL_ID="1"
|
|
```
|
|
|
|
Insert the invoice. Scripted totals are initially zero because it has no
|
|
items yet.
|
|
|
|
```bash
|
|
grpcurl -plaintext -H "$AUTH_HEADER" \
|
|
-import-path common/proto -proto tables_data.proto \
|
|
-d "{
|
|
\"profile_name\":\"fakturacia_2026\",
|
|
\"table_name\":\"faktura\",
|
|
\"data\":{
|
|
\"dodavatel_id\":$DODAVATEL_ID,
|
|
\"odberatel_id\":$ODBERATEL_ID,
|
|
\"cislo\":\"2026042\",
|
|
\"datum_vystavenia\":\"2026-06-15\",
|
|
\"datum_dodania\":\"2026-06-12\",
|
|
\"datum_splatnosti\":\"2026-06-29\",
|
|
\"variabilny_symbol\":\"2026042\",
|
|
\"sposob_uhrady\":\"Prevodný príkaz\",
|
|
\"zaklad_dane\":\"0\",
|
|
\"dph_celkom\":\"0\",
|
|
\"celkom_spolu\":\"0\",
|
|
\"poznamka\":\"Ďakujeme za Vašu dôveru.\"
|
|
}
|
|
}" \
|
|
"$GRPC_ADDR" komp_ac.tables_data.TablesData/PostTableData
|
|
```
|
|
|
|
Set the returned invoice ID:
|
|
|
|
```bash
|
|
FAKTURA_ROW_ID="PASTE_INVOICE_ID"
|
|
```
|
|
|
|
Insert invoice items. Because the item columns are scripted, include their
|
|
calculated values in each request.
|
|
|
|
```bash
|
|
grpcurl -plaintext -H "$AUTH_HEADER" \
|
|
-import-path common/proto -proto tables_data.proto \
|
|
-d "{
|
|
\"profile_name\":\"fakturacia_2026\",
|
|
\"table_name\":\"polozka\",
|
|
\"data\":{
|
|
\"faktura_id\":$FAKTURA_ROW_ID,
|
|
\"nazov\":\"Návrh loga a vizuálnej identity\",
|
|
\"mnozstvo\":\"1\",
|
|
\"mj\":\"ks\",
|
|
\"cena\":\"850.00\",
|
|
\"dph\":\"20\",
|
|
\"bez\":\"850.00\",
|
|
\"dph_suma\":\"170.00\",
|
|
\"spolu\":\"1020.00\"
|
|
}
|
|
}" \
|
|
"$GRPC_ADDR" komp_ac.tables_data.TablesData/PostTableData
|
|
```
|
|
|
|
Repeat the same request for additional items, changing the values. For the
|
|
sample invoice, the calculated values are:
|
|
|
|
| Item | `bez` | `dph_suma` | `spolu` |
|
|
|---|---:|---:|---:|
|
|
| Logo | 850.00 | 170.00 | 1020.00 |
|
|
| Menu, quantity 2 | 240.00 | 48.00 | 288.00 |
|
|
| Printed menus | 255.00 | 25.50 | 280.50 |
|
|
| Interior photography | 260.00 | 52.00 | 312.00 |
|
|
|
|
The resulting invoice totals are `zaklad_dane = 1605.00`,
|
|
`dph_celkom = 295.50`, and `celkom_spolu = 1900.50`.
|
|
|
|
## 6. Install the Typst template
|
|
|
|
The Linux client discovers templates in:
|
|
|
|
```text
|
|
~/.config/komp-ac/komp_ac_client/print_templates/
|
|
```
|
|
|
|
Place the supplied files there with matching stems:
|
|
|
|
```bash
|
|
mkdir -p ~/.config/komp-ac/komp_ac_client/print_templates
|
|
cp inv2_generic.typ ~/.config/komp-ac/komp_ac_client/print_templates/faktura.typ
|
|
cp inv2_generic.json ~/.config/komp-ac/komp_ac_client/print_templates/faktura.json
|
|
```
|
|
|
|
The JSON must contain the target paths used by the print mapper:
|
|
|
|
```text
|
|
faktura.*
|
|
dodavatel.*
|
|
odberatel.*
|
|
polozky[].*
|
|
```
|
|
|
|
Open the invoice row in the client, open the Print page, select `faktura.typ`,
|
|
select the related `polozka` rows, and export. The client writes the generated
|
|
JSON as `faktura.export.json` beside the template.
|
|
|
|
## 7. Compile the PDF
|
|
|
|
```bash
|
|
typst compile \
|
|
--input data="$HOME/.config/komp-ac/komp_ac_client/print_templates/faktura.export.json" \
|
|
"$HOME/.config/komp-ac/komp_ac_client/print_templates/faktura.typ" \
|
|
faktura.pdf
|
|
```
|
|
|
|
The client currently exports the API-backed JSON and saves the document
|
|
snapshot, but it does not invoke the Typst compiler itself.
|
|
|
|
## Deterministic five-person company simulation
|
|
|
|
The repository also contains a standalone bootstrap that creates a separate
|
|
`small_company_2026` profile, installs its Steel calculations, and pushes all
|
|
fixture rows through the same gRPC APIs used by the client:
|
|
|
|
```text
|
|
server/scripts/bootstrap_small_company.py
|
|
```
|
|
|
|
It expects the existing passwordless users `admin` and `filipko`. The admin
|
|
token is used only for table definitions and scripts. The accountant token is
|
|
used for every business-row insert.
|
|
|
|
Preview the scope without contacting the server:
|
|
|
|
```bash
|
|
python3 server/scripts/bootstrap_small_company.py --dry-run
|
|
```
|
|
|
|
Create and populate the profile:
|
|
|
|
```bash
|
|
python3 server/scripts/bootstrap_small_company.py
|
|
```
|
|
|
|
If a run stops after creating some objects, resume from its checkpoint:
|
|
|
|
```bash
|
|
python3 server/scripts/bootstrap_small_company.py --resume
|
|
```
|
|
|
|
The checkpoint defaults to `small_company_2026.bootstrap-state.json`. It
|
|
contains table IDs, script IDs, and inserted row IDs, but no access tokens or
|
|
passwords. The bootstrap does not delete an existing profile. If the profile
|
|
already exists without its matching checkpoint, it stops instead of modifying
|
|
unknown data.
|
|
|
|
The fixed scenario includes five employees, customers, suppliers, products,
|
|
CRM leads, sales orders, invoices and partial payments, purchase orders,
|
|
supplier invoices, stock movements and positions, expenses, and service time
|
|
entries. It verifies parent totals, outstanding balances, and stock values by
|
|
reading the rows back after insertion.
|