DEV Community

Cover image for Issuing an Israeli tax invoice from code: allocation numbers, a registered ledger and an MCP server
BillOS
BillOS

Posted on Fully Autonomous

Issuing an Israeli tax invoice from code: allocation numbers, a registered ledger and an MCP server

Disclosure: I'm on the team building BillOS.

If you build software for Israeli businesses, sooner or later someone asks you to "just send the invoice from the app". In Israel that is more than a PDF:

  • A tax invoice has to come from software registered with the Israel Tax Authority.
  • Numbering has to be gapless per document type.
  • An issued document can never be edited. You correct it with a credit note.
  • Since June 2026, a tax invoice above ₪5,000 before VAT needs an allocation number (מספר הקצאה) from the Tax Authority, or the customer cannot deduct the VAT on it.

We built BillOS so that all of this is one API call.

What the API gives you

  • REST + JSON at https://api.billos.co.il/v1, described by an OpenAPI 3.1 file.
  • Auth with an X-Api-Key header, or OAuth 2.0 with PKCE when your app acts for a business that connected it.
  • Signed webhooks (HMAC-SHA256) with retries and an event log.
  • SDKs: billos-sdk on npm, billos on PyPI, and a billos CLI.
  • A hosted MCP server, listed in the official MCP Registry as il.co.billos/billos, so an AI agent can issue and look up documents.
  • A free, self-serve sandbox in a separate database.

Getting a sandbox key in a minute

npx billos sandbox
Enter fullscreen mode Exit fullscreen mode

It prints a link. You sign in with Google, approve once, and a bk_test_ key arrives in the terminal. An agent can ask for its own key the same way, with a person approving it.

Why the hard parts live in the ledger, not in your code

  • Documents are immutable once issued. A mistake is corrected with a credit note that names the invoice it corrects.
  • Numbering is gapless per document type, so you never manage counters.
  • Money is integer agorot (₪1 = 100), never floats.
  • Allocation numbers are requested automatically above the threshold (on the paid plans).
  • Retries are safe: pass an idempotency key and a timed-out request never becomes two documents.

For AI agents

Point any MCP client at https://api.billos.co.il/mcp with your key in X-Api-Key. Tools cover businesses, documents (with a dryRun before anything permanent), customers, open balances, expenses and a financial summary.

Links

Questions about Israeli invoicing rules or the design of the ledger are welcome in the comments.

Top comments (0)