smartbill-web

Files (26)

• .gitignore
• SKILL.md
• chrome-debug.sh · bin/
• install-launchd.sh · bin/
• session-lab.sh · bin/
• smartbill-mcp.sh · bin/
• edits.example.csv
• invoice.example.json
• package.json
• payment.example.json
• OPEN-FINDINGS.md · references/
• rows.example.csv
• acquisitions.ts · src/
• api.ts · src/
• btstatement.ts · src/
• cli.ts · src/
• clients.ts · src/
• glovo-pdf.ts · src/
• glovo.ts · src/
• invoices.ts · src/
• mcp.ts · src/
• pdf.ts · src/
• reconcile-html.ts · src/
• report.ts · src/
• session.ts · src/
• tsconfig.json

SKILL.md (first lines)

# SmartBill

One CLI, `npm run sb -- <cmd>`, with **two engines**. Picking the wrong one is the
main way to waste time here, so start with the table below.

```bash
cd "${CLAUDE_PLUGIN_ROOT:-$HOME/workspace/victor-skills}/skills/smartbill-web"
```

## Which engine

| Engine | How | Cost | Needs |
|---|---|---|---|
| **API** | REST on `ws.smartbill.ro` | ~200 ms/call | token in `~/.claude/smartbill.env` |
| **Browser** | Playwright on `cloud.smartbill.ro` | ~1.6 s/invoice + browser start | `sb -- login` once |

> **API issuing is OFF on this subscription since Sep 2026.** Every REST call
> answers `Nu aveti acces la API-ul SmartBill`, and `/core/integrari/` spells out
> why: *"Abonamentul tau nu include emiteri prin API"* - it is a Platinum feature.
> **This is not a stale token; regenerating it changes nothing.** Until the plan
> is upgraded everything goes through the browser: issue with `issue` + `finalize`.

**Default to the API** *(when the plan allows it)*. Fall back to the browser only
for the things the API genuinely cannot do:

| Need | Why the API can't | Use |
|---|---|---|
| **Enumerate documents** | SmartBill's public API has no listing endpoint. Only `/series`, `/tax` and `/stocks` return lists — there is no `GET /invoices`. | `sb -- list` (browser) — or `sb -- recent`, see below |
| **Edit an issued invoice** | No update endpoint exists. The API can only create, cancel, storno or delete. | `sb -- edit` (browser) |
| **Copy an existing invoice** | No "duplicate document" endpoint. `create` needs the full client + line payload spelled out. | `sb -- copy` (browser) |
| **Change the customer on an issued invoice** | No update endpoint, and the client endpoints are read-only. | `sb -- reclient` (browser) |
| **Read expenses / bank statements** | The whole *Cheltuieli* and *Tranzactii bancare* side lives only in the web app; `ws.smartbill.ro` knows nothing about it. | `sb -- expenses`, `sb -- banktx`, `sb -- reconcile` |

Everything else — reading a document, payment status, PDFs, issuing, payments,
cancel/storno/delete, emailing — goes through the API.

## Setup

**API** (once): create `~/.claude/smartbill.env`, mode 600:

```
SMARTBILL_USERNAME=you@example.com
SMARTBILL_TOKEN=<token>
SMARTBILL_VAT_CODE=RO12345678
```

The token is in SmartBill Cloud → Contul meu → Integrari → API; the circular
arrow next to it regenerates it (do that if it ever leaks — a screenshot of that
page is enough to leak it). Env vars of the same names override the file. Never
pass the token on the command line; it would land in shell history.

**Browser** (once, and again whenever the session expires):

```bash
npm install && npx playwright install chromium
npm run sb -- login          # headless, with the Keychain password; cookies saved to storageState.json
npm run sb -- login --manual # by hand, in a window
```

`login` reads the credentials from the macOS Keychain, so an agent can log back
in on its own when the session dies. Store them once, by hand (`-w` with no
value prompts for the password, so it never lands in shell history or a chat):

```bash
security add-generic-password -s cloud.smartbill.ro -a <email> -w
```

The email is read back from the Keychain item; set `SMARTBILL_ACCOUNT` only if
several are stored. If the form does not let it through (captcha, 2FA), `login`
fails with the page text and `--manual` is the way in.

`storageState.json` is gitignored.

## API commands

| Command | What it does |
|---|---|
| `sb -- series [--type factura\|proforma\|chitanta]` | series + the next number each will issue |
| `sb -- taxes` | VAT rates as name/percentage. **Read these before issuing** — names and rates differ per account and change over time |
| `sb -- stocks [--date] [--warehouse] [--product]` | stock levels as of a date |
| `sb -- read --series S --number 324 [--full]` | **reads the document**: date, due date, total, currency, counterparty, line items. `--full` dumps the raw text |
| `sb -- status --series S --number 324` | `invoiceTotalAmount` / `paidAmount` / `unpaidAmount` / `paid` |
| `sb -- get --series S --number 324 --out ./out [--name f.pdf]` | download the PDF |
| `sb -- recent [--series S] [--count 10] [--json]` | the closest thing to a listing without a browser — see below |
| `sb -- create --json invoice.json` | issue an invoice from a full payload (`invoice.example.json`) |
| `sb -- pay --series S --number 324 [--date] [--value] [--type] [--vat]` | record money received; amount, currency and client are read off the invoice |
| `sb -- pay --json payment.json` | the same, spelled out in full (`payment.example.json`) |
| `sb -- storno --series S --number 324` | reverse an invoice in full, into the same series |
| `sb -- cancel` / `restore --series S --number 324` | void / un-void; the number is kept, so the series has no gap |
| `sb -- rm --series S --number 324` | **irreversible**, and only allowed for the LAST invoice in a series |
| `sb -- email --series S --number 324 [--to] [--subject] [--body]` | SmartBill mails the document with the PDF attached |

### Recording a payment

`pay` needs no JSON file for the usual case. Given `--series` and `--number` it
reads the **amount, currency and counterparty off the invoice itself**, defaults
the value to whatever is still unpaid, and defaults the date to today:

```bash
npm run sb -- pay --series P --number 209 --date 2026-08-27 --vat NL001797931B01
```

It then **re-reads the payment status** and says `settled: true/false`, exiting
non-zero when the invoice is still open. A 200 from the POST is not evidence the
document is settled - only the status endpoint is. It also refuses to double-pay:
an invoice already marked paid comes back as `alreadyPaid` untouched.

Pick the value date from the payment advice, not from the day the email arrived -
those differ, and the advice is what the client's books show.

### Reading a document is a PDF operation

Issue date, client, line items and **currency** exist only inside the PDF — no
endpoint returns them. `status` deliberately does not say which currency its
numbers are in, so **never quote a figure from `status` alone**: reporting
"1250 RON" for a 1250 EUR invoice misstates it fivefold. Run `read` first.

`read` parses both SmartBill templates — the Romanian one for domestic clients
("Data emiterii" / "TOTAL PLATA") and the English one for foreign-currency

From victorrentea/skills, Unlicense.

More from victorrentea/skills