# Invora REST API, Webhooks & MCP (3.3)

Invora ships a JSON REST API, signed webhooks and — new in 3.0 — an MCP endpoint, so your
invoicing plugs into Power Automate, Zapier, n8n, AI agents, or your own code — including
Microsoft Business Central integrations built against it.

## Authentication

Create a key in **Settings → API & Webhooks** (admin). A key belongs to a user and can do
exactly what that user can do in the app — clerks create documents, record payments and manage
clients; admins additionally run the install. Send it on every call:

    Authorization: Bearer apk_...

The key is shown once at creation and stored hashed. Revoke any time.

## Endpoints

| Method & path | What it does |
|---|---|
| `GET  /api/ping` | Verify a key |
| `GET  /api/invoices` · `GET /api/estimates` | Newest 50; `?status=` filters (`draft`, `sent`, `partial`, `paid`, `overdue`, `accepted`, `declined`) |
| `POST /api/invoices` · `POST /api/estimates` | Create (client_id + lines[{description, qty, unit, tax_rate}]; optional status/discount/dates) |
| `GET  /api/documents/{id}` | One document with lines, payments, totals, public link; `fees_cents` and `late_fees` list any late fee applied under the owner's rule (new in 3.3) |
| `POST /api/documents/{id}/payments` | Record a payment (invoices only): {"amount": "125.00", "paid_on"?, "method"?} |
| `POST /api/documents/{id}/status` | Set workflow status (draft/sent; estimates also accepted/declined) |
| `GET/POST /api/clients` | List / create clients; each listed client carries `portal_url`, its portal link, or `null` while none is switched on (new in 3.3) |
| `GET  /api/items` · `GET /api/taxes` | Catalog reference data |
| `GET  /api/reminders` | The automatic payment-reminder schedule, read-only (new in 3.2; see below) |
| `GET  /api/openapi.json` | OpenAPI 3 spec (no auth) |

### Create an invoice

    curl -X POST https://your-install/api/invoices \
      -H "Authorization: Bearer apk_..." -H "Content-Type: application/json" \
      -d '{"client_id": 1, "status": "sent",
           "lines": [{"description": "Consulting", "qty": "3", "unit": "150.00", "tax_rate": "20"}]}'

Money is decimal-in, integer-cents-out. The exact same validation and totals math as the UI applies.

## Webhooks

Add receiver URLs in **Settings → API & Webhooks**. Events:

- `invoice.created` / `estimate.created` — a document is created: in the browser, by converting
  an estimate, through the API, by an AI tool or by a recurring schedule
- `payment.recorded` — any payment lands
- `invoice.paid` — the balance reaches zero
- `estimate.accepted` — marked accepted, converted to an invoice, or accepted by the client on
  their estimate link (3.3)
- `estimate.declined` — declined by the client on their estimate link (new in 3.3)

Each delivery is an HTTP POST with a JSON body (`{"event", "at", "document": {...}}`) and:

    X-Invora-Event: invoice.created
    X-Invora-Signature: sha256=<hex HMAC-SHA256 of the raw body, keyed with the endpoint's secret>

Verify the signature before trusting a payload. Delivery is one attempt with a 5-second
timeout — deliberately simple; the **Recent deliveries** log on the settings page shows
every attempt and response code. Design receivers to be idempotent.

## Power Automate (and Logic Apps)

Two ways, no Microsoft partnership required:

1. **Instant trigger via webhook:** in Power Automate, create a flow with the
   **"When an HTTP request is received"** trigger, copy its URL into Invora's webhooks,
   and branch on `body('...')?['event']`. That's your invoices driving Teams messages,
   Business Central jobs, or anything else in your tenant.
2. **Custom connector:** Power Automate → Data → Custom connectors → **Import an OpenAPI
   file** → point it at `/api/openapi.json` from your install (or download the file).
   Set security to API Key / Bearer. Every endpoint above becomes a native action.

## Limits, honestly

- The API acts at user level; there is no separate scope system beyond the app's roles.
- One delivery attempt per webhook event (log + idempotent receivers, not a retry queue).
- List endpoints cap at 50–100 rows; this is an SMB invoicing tool, not a data warehouse.

# MCP — the agent door (new in 3.0)

Invora speaks the **Model Context Protocol** at `POST /mcp`, so Claude, ChatGPT agents, n8n's
AI nodes or your own code can *use* Invora instead of merely reading it. It is the same product
underneath: the same bearer key, the same roles, and the same money math. An agent cannot do
anything its key's user could not do in the browser — and it cannot compute a total, ever;
Invora's integer-cent engine does.

Transport is **streamable HTTP, stateless**: one JSON-RPC 2.0 request in, one JSON response out.

```bash
curl -s -X POST https://invora.example.com/mcp \
  -H "Authorization: Bearer apk_xxxx" -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1"}}}'
```

Then `tools/list` to discover, `tools/call` to act:

```bash
curl -s -X POST https://invora.example.com/mcp \
  -H "Authorization: Bearer apk_xxxx" -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"overdue_report","arguments":{}}}'
```

## Connect it to an assistant

Mint the key in the app first: **Settings → API keys**. Choose **Read only** when the assistant should
answer questions but never change anything — the endpoint then lists only the read tools and refuses the
rest by name, so a careless prompt cannot write. Full access behaves as before.

Every client needs the same three facts, and nothing in the handshake is vendor-specific:

| | |
|---|---|
| **The address** | `https://invora.example.com/mcp` |
| **The key** | header `Authorization: Bearer apk_xxxx` |
| **The transport** | MCP over streamable HTTP, stateless |

**Claude** — one command, or the same URL and header as a custom connector in the desktop and web apps:

```sh
claude mcp add --transport http invora https://invora.example.com/mcp \
  --header "Authorization: Bearer apk_xxxx"
```

**ChatGPT and the OpenAI API** — one entry in the Responses API's `tools` array (in ChatGPT itself, the
same URL and key go in as a connector):

```json
{
  "type": "mcp",
  "server_label": "invora",
  "server_url": "https://invora.example.com/mcp",
  "authorization": "apk_xxxx",
  "require_approval": "never"
}
```

**Every other client spells the same three facts differently — copy the shape from its own
documentation, not from here.** VS Code is the clearest example of why: its
[configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
(read 6 September 2026) puts servers in `.vscode/mcp.json` under a **`"servers"` object** — *"an
object that maps server names to their configurations"*. Pasted as-is,
a block written for another client will not load there. The id, the URL and the token are what travel; the JSON around
them belongs to whichever client you are configuring.

**A local model, n8n, or your own code** — n8n's **MCP Client** node takes the URL and the same
`Authorization: Bearer` header; a model running on your own machine reaches it through any MCP client, so
nothing leaves your network at all. Writing it yourself is one POST of JSON-RPC 2.0:

```sh
curl -X POST https://invora.example.com/mcp \
  -H "Authorization: Bearer apk_xxxx" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

Any client that speaks MCP's streamable-HTTP transport works, including ones that do not exist yet:
Invora implements the protocol, not an integration with a particular vendor.

## Tools

| Tool | Writes? | What it does |
|---|---|---|
| `list_invoices` | no | Invoices newest first (max 50); optional effective-status filter |
| `list_estimates` | no | Estimates newest first (max 50); optional status filter |
| `get_document` | no | One document with lines, payments and totals |
| `create_invoice` | **yes** | Creates an invoice from client_id + lines; totals computed by Invora |
| `create_estimate` | **yes** | Creates an estimate, same shape |
| `record_payment` | **yes** | Records a payment; a fully-paid invoice fires the paid webhook |
| `set_status` | **yes** | draft/sent (estimates also accepted/declined) — paid/partial/overdue are computed, never set |
| `overdue_report` | no | Counts by effective status + the overdue invoices with balances |
| `list_clients` | no | Clients on file |
| `reminder_schedule` | no | The automatic payment-reminder schedule: steps, and per open invoice the last step sent, today, and the next one (new in 3.2) |

There is deliberately **no send-to-client tool and no delete tool**. A customer is emailed only
by a person in the app or by the reminder schedule the owner switched on in Settings, and
records are destroyed only by a person. An agent can draft your recurring work, tell you what is
overdue and read the reminder schedule; it cannot write to your customers, trigger or pause a
reminder, or erase your books.

## Money discipline

Send decimals as strings (`"unit": "150.00"`, `"amount": "459.99"`). Invora parses them with
the same `to_cents`/`to_milli` guards the form uses and computes every total itself. A nested
value where a scalar belongs, an unknown argument, or an unknown client are each refused by
name with `isError: true` — the same sentences a person sees.

# Operational endpoints (new in 3.0)

| Endpoint | Guard | What it does |
|---|---|---|
| `GET /backup/scheduled?t=<token>` | ops token (Security page) | Writes a redacted JSON backup into `data/backups/`, keeps the newest 14 |
| `GET /cron/recurring?t=<token>` | same ops token | Drafts every recurring invoice that is due (never sends) |
| `GET /cron/reminders?t=<token>` | same ops token | Applies the late fees due today under the owner's rule (3.3), then sends the automatic payment reminders due today, up to the daily cap; each does nothing while it is switched off (new in 3.2). The JSON adds `late_fees_applied` |
| `POST /pay/stripe` | Stripe's signature (`Stripe-Signature`) | The owner's own Stripe webhook (new in 3.3; see below). 404 while switched off |
| `GET /c/{token}` · `GET /c/{token}/statement.pdf` | the client's portal token | A client's own page and statement PDF (new in 3.3). Read-only |
| `GET /calendar.ics?t=<token>` | its own feed token | Read-only iCal feed of open invoices' due dates |
| `GET /clients/{id}/gdpr.json` | admin session | Subject-access export for one client |

# Automatic payment reminders (new in 3.2): see, never send

Reminders are **off by default**. The owner switches them on in **Settings → Automatic payment
reminders**, approving the steps (days from the due date, `-3,0,7,14` by default), a daily cap
and one message per step. They then go out on normal page loads, or from `/cron/reminders` for an
install nobody visits, through the owner's own SMTP server. Every attempt is recorded in the
invoice's send log with its step.

The API and the MCP door can **read** the schedule and nothing more. `GET /api/reminders` and the
MCP tool `reminder_schedule` return the same JSON:

```json
{
  "enabled": true, "armed": true, "not_armed_because": [], "today": "2026-09-24",
  "steps": [{"days": -3, "label": "3 days before the due date"}, {"days": 0, "label": "on the due date"},
            {"days": 7, "label": "7 days after the due date"}, {"days": 14, "label": "14 days after the due date"}],
  "daily_cap": 20, "attempts_today": 2,
  "invoices": [
    {"id": 12, "number": "INV-0012", "client_id": 3, "client": "Aria Okafor", "status": "overdue",
     "due_date": "2026-09-17", "balance_cents": 47740,
     "last_step": {"days": 0, "label": "on the due date", "on": "2026-09-17", "status": "sent"},
     "today": {"state": "send", "step": 7, "reason": ""},
     "next": {"days": 7, "label": "7 days after the due date", "on": "2026-09-24"}}
  ],
  "note": "Read-only. Reminders go only on the schedule the owner switched on in Settings; nothing here can send one."
}
```

`today.state` is one of `send` (goes today), `would_send` (would go today, but the schedule is not
armed: see `not_armed_because`), `held` (due today but held: paused, no address, the day's cap,
a refused send, or a quiet day after another mail; `reason` says which), `done` (today's step
already went), `waiting` (no step has come yet) or `finished`. The response carries no email
addresses and no message text. There is no route or tool that sends, pauses or edits a reminder.

# Stripe payments, late fees and the client portal (new in 3.3)

**Stripe payments mark the invoice paid.** Off until the owner switches it on in **Settings →
Stripe payments mark the invoice paid** and pastes the endpoint's signing secret (`whsec_…`).
Point a Stripe webhook endpoint at `POST /pay/stripe` with the events `checkout.session.completed`
and `checkout.session.async_payment_succeeded`. Invora:

- verifies every delivery before reading it: HMAC-SHA256 of `"<t>.<raw body>"` with the signing
  secret, any `v1` signature in the `Stripe-Signature` header, and a timestamp within five minutes
  (400 otherwise, nothing written);
- records each Stripe event id once (a retry answers `duplicate`), and each checkout session once;
- finds the invoice from `client_reference_id` (`invora-<id>`, which Invora adds to every
  `buy.stripe.com` link it shows or mails) or from a metadata field `invoice` holding the invoice
  number; the currency has to match the invoice's;
- records the amount Stripe reports as paid through the same path as any payment, so
  `payment.recorded`, `invoice.paid`, the audit trail and the paid notice all follow. A paid
  invoice gets no further reminder.

Outcomes, shown under **Latest notices from Stripe**: `recorded`, `duplicate`, `pending` (a bank
debit Stripe has not confirmed yet), `unmatched`, `currency_mismatch`, `ignored`. Other payment
services can record payments through `POST /api/documents/{id}/payments`.

**Late fees** are a rule the owner writes in **Settings → Late fees**, off by default: a flat
amount or a percentage of what is unpaid on the invoice (never of earlier fees), a number of days
after the due date, once or again every 30 days up to a limit. It applies only to invoices falling
due on or after the day it was switched on. A fee is its own row, added after the discount and the
tax: `total_cents` includes it, `fees_cents` is its sum, and `late_fees` lists each one
(`seq`, `label`, `amount_cents`, `applied_on`). A waived fee leaves both. No API route or MCP tool
adds or waives a fee.

**The client portal** is one link per client (`/c/{token}`, 40 hex characters), made, replaced or
switched off on the client's page. It lists the client's own non-draft invoices and estimates and
serves a statement PDF, answers `X-Robots-Tag: noindex` and `Referrer-Policy: no-referrer`, and
reads only. Estimates are answered on their own link (`POST /p/{token}/decide`) when the owner
switched online answers on; an accepted estimate becomes a draft invoice.


## Connect it to Zapier, Make or n8n

Invora talks to other tools without a plugin: it sends a webhook (an HTTPS message) the moment something happens, and it accepts calls to the API above. Zapier, Make and n8n can use both.

### Before you start

- In Invora, open **Settings → API & Webhooks**. Mint an API key (choose **Read only** if the other tool only reads), and add a webhook when you have its URL (below).
- Use your install's full address, for example `https://invora.yourcompany.com`.

### When something happens in Invora: send it to another tool

1. In the other tool, create the trigger that gives you a URL to receive webhooks:
   - **Zapier:** the "Webhooks by Zapier" app, trigger **Catch Hook** (Webhooks by Zapier needs a paid Zapier plan).
   - **Make:** module **Webhooks → Custom webhook**.
   - **n8n:** the **Webhook** node.
2. Copy that URL into Invora under **Settings → API & Webhooks**, and choose the event or events below.
3. Make the event happen once in Invora, so the other tool receives a sample and you can map its fields.

| Event | Fires when |
|---|---|
| `invoice.created` | A document is created: in the browser, by converting an estimate, through the API, by an AI tool or by a recurring schedule |
| `estimate.created` | A document is created: in the browser, by converting an estimate, through the API, by an AI tool or by a recurring schedule |
| `payment.recorded` | Any payment lands |
| `invoice.paid` | The balance reaches zero |
| `estimate.accepted` | Marked accepted, converted to an invoice, or accepted by the client on their estimate link (3.3) |
| `estimate.declined` | Declined by the client on their estimate link (new in 3.3) |

Every delivery carries `X-Invora-Signature`, an HMAC-SHA256 signature over the raw body. Zapier and Make accept the delivery without checking it, so keep the webhook URL private. In n8n you can check it in a Code node before using the data.

### When something happens elsewhere: act in Invora

- **Zapier:** "Webhooks by Zapier", action **POST** (or **Custom Request**).
- **Make:** module **HTTP → Make a request**.
- **n8n:** the **HTTP Request** node.

Send the request to your install's address plus the path from the Endpoints table above, with the header `Authorization: Bearer <your API key>` and a JSON body. A read-only key cannot write.

The endpoints that change something:

- `POST /api/invoices`: Create (client_id + lines[{description, qty, unit, tax_rate}]; optional status/discount/dates)
- `POST /api/estimates`: Create (client_id + lines[{description, qty, unit, tax_rate}]; optional status/discount/dates)
- `POST /api/documents/{id}/payments`: Record a payment (invoices only): {"amount": "125.00", "paid_on"?, "method"?}
- `POST /api/documents/{id}/status`: Set workflow status (draft/sent; estimates also accepted/declined)
- `POST /api/clients`: List / create clients; each listed client carries `portal_url`, its portal link, or `null` while none is switched on (new in 3.3)

### Example recipes

- **invoice.created → a row in Google Sheets:** webhook trigger on `invoice.created` (A document is created: in the browser, by converting an estimate, through the API, by an AI tool or by a recurring schedule), then the Google Sheets "Create row" action with the fields you want.
- **estimate.created → a message in Slack or Teams:** webhook trigger on `estimate.created` (A document is created: in the browser, by converting an estimate, through the API, by an AI tool or by a recurring schedule), then the Slack or Microsoft Teams "Send message" action.
- **A new form entry or row elsewhere → Invora:** the other tool's trigger (for example a new Google Sheets row or a form submission), then an HTTP action calling `POST /api/invoices` (Create (client_id + lines[{description, qty, unit, tax_rate}]; optional status/discount/dates)).

These recipes use only the events and endpoints documented above. We have not run them inside Zapier, Make or n8n ourselves; Invora's own automated tests check its API.
