Guide

Print an invoice

Put your company's details in the book, run the Printable Invoice report for a document, and export it as a single HTML page to print or send.

red-ale has no print dialog. A document is printed by running the Printable Invoice report on it, which gives its figures exactly, and exporting that as one HTML page. Open the page in a browser to print it, or turn it into a PDF. The same report prints invoices, bills, credit notes and expense vouchers.

Steps

  1. Set your company's details once with book.setOptions: companyName, companyAddress, companyContactPerson, phone, fax, email, website, companyId and taxNumber. They fill the header of the printout.
  2. Find the document's GUID with invoice.list. The report is told which document to print by its GUID, not its number.
  3. Run the report with report.run, report Printable Invoice, and the option {"General": {"Invoice Number": "<guid>"}}. You get the report result: the entries, net price, tax, total, payments and amount due, as exact figures with their display forms. A document may be posted or not.
  4. Adjust the layout if you like. report.options lists the options: which entry columns show (Display Columns), whether the due date, billing terms and payments print, a custom title, extra notes at the foot, and the CSS.
  5. Export it with report.export, with the same options. The result's html is a complete, self-contained page. From the command line, red-ale exec --output invoice.html --book book.gnucash report.export '{...}' writes it to a file instead of printing it.
  6. To print as GnuCash does, read defaultInvoiceReport with book.options. If the book names an invoice report that red-ale has, run that one; otherwise use the Printable Invoice, which is what GnuCash falls back to. The Printable Invoice page has the details.

Example

Example: with a copy of the synthetic/business-editable example book open as book.gnucash, at 2024-03-25T12:00:00Z.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"book.setOptions","params":{"companyName":"Acme Ltd","companyAddress":"1 Main St\nSpringfield","companyEmailAddress":"billing@acme.example"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "companyName": "Acme Ltd",
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"report.run","params":{"report":"Printable Invoice","options":{"General":{"Invoice Number":"aa210b7131de44c48b8513cd27c00e95"}}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "report": {
      "name": "Printable Invoice",
      "…": "…"
    },
    "sections": "…",
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":3,"method":"report.export","params":{"report":"Printable Invoice","options":{"General":{"Invoice Number":"aa210b7131de44c48b8513cd27c00e95"}}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "title": "…",
    "html": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
book.setOptions {"companyName":"Acme Ltd","companyAddress":"1 Main St\nSpringfield","companyEmailAddress":"billing@acme.example"}
report.run {"report":"Printable Invoice","options":{"General":{"Invoice Number":"aa210b7131de44c48b8513cd27c00e95"}}}
report.export {"report":"Printable Invoice","options":{"General":{"Invoice Number":"aa210b7131de44c48b8513cd27c00e95"}}}
EOF

It prints:

[
  {
    "companyName": "Acme Ltd",
    "…": "…"
  },
  {
    "report": {
      "name": "Printable Invoice",
      "…": "…"
    },
    "sections": "…",
    "…": "…"
  },
  {
    "title": "…",
    "html": "…"
  }
]

MCP tool call

Tool call:

{"name":"book.setOptions","arguments":{"companyName":"Acme Ltd","companyAddress":"1 Main St\nSpringfield","companyEmailAddress":"billing@acme.example"}}

Result:

{
  "structuredContent": {
    "companyName": "Acme Ltd",
    "…": "…"
  }
}

Tool call:

{"name":"report.run","arguments":{"report":"Printable Invoice","options":{"General":{"Invoice Number":"aa210b7131de44c48b8513cd27c00e95"}}}}

Result:

{
  "structuredContent": {
    "report": {
      "name": "Printable Invoice",
      "…": "…"
    },
    "sections": "…",
    "…": "…"
  }
}

Tool call:

{"name":"report.export","arguments":{"report":"Printable Invoice","options":{"General":{"Invoice Number":"aa210b7131de44c48b8513cd27c00e95"}}}}

Result:

{
  "structuredContent": {
    "title": "…",
    "html": "…"
  }
}