From 2fa61005b589944e9024c252c18c85fe6c664f1f Mon Sep 17 00:00:00 2001
From: ZProger <zproger@users.noreply.github.com>
Date: Tue, 8 Sep 2026 20:30:11 +0300
Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8?=
 =?UTF-8?q?=D1=82=D1=8C=20=D0=BF=D1=80=D0=B8=D0=BC=D0=B5=D1=80=20=D0=B2?=
 =?UTF-8?q?=D1=8B=D0=B7=D0=BE=D0=B2=D0=B0=20API=20=D0=B8=D0=B7=20=D1=87?=
 =?UTF-8?q?=D0=B0=D1=82-=D0=B1=D0=BE=D1=82=D0=B0=20(Telegram/n8n)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 DOCS.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/DOCS.md b/DOCS.md
index 6c1e3e6..e4d5fc5 100644
--- a/DOCS.md
+++ b/DOCS.md
@@ -855,6 +855,36 @@ curl -u user:pass -X POST http://localhost:3000/api/transactions/bulk \
   }'
 ```
 
+### Log expenses from a chat bot (Telegram, n8n, ...)
+
+Because it's a plain HTTP API, adding a transaction doesn't have to go through the UI — a message to a
+bot works just as well. The usual shape: a Telegram bot (or an n8n workflow triggered by Telegram)
+hands the message text to an LLM, asks it to extract a `TransactionCreate` object from it, then POSTs
+that straight to `/transactions`.
+
+For example, texting the bot "Add a $12 expense for coffee to my Cash account" or "I spent 30 EUR at a
+shop abroad, convert that to dollars and log it under Cash" — the LLM resolves account/category names
+to IDs (via `GET /accounts` / `GET /categories`), and, since Aurum itself never converts currency (see
+[Conventions](#conventions)), converts EUR → USD itself before calling the API:
+
+```bash
+curl -u user:pass -X POST http://localhost:3000/api/transactions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "account_id": 3,
+    "category_id": 4,
+    "type": "expense",
+    "amount": 32.40,
+    "description": "Shopping",
+    "date": "2026-08-30"
+  }'
+```
+
+In n8n this is typically three nodes: a Telegram Trigger, an LLM node (system prompt describes the
+`TransactionCreate` shape plus your own account/category IDs, and is told to output JSON only), and an
+HTTP Request node that POSTs that JSON to `/transactions`. No extra backend needed — the API is the only
+integration point.
+
 ---
 
 For self-hosting, environment variables, and running Aurum itself, see [README.md](README.md).