Method

reconcile.start

Start reconciling an account against a statement: GnuCash's defaults, the splits to tick and the balances.

Begins reconciling an account against a bank statement, as GnuCash's Reconcile dialog opens. It fills in GnuCash's defaults (the statement date, the ending balance, a postponed reconciliation if there is one), lists the account's uncleared and cleared splits with the cleared ones already ticked, and shows the balances: startingBalance, tickedBalance, reconciledBalance and the difference from the endingBalance.

It changes nothing. red-ale keeps no reconciliation window: you carry the statement and the ticked splits from call to call and hand them to reconcile.status, then to reconcile.finish or reconcile.postpone. Amounts use the account's raw sign (debits positive), whatever sign GnuCash's window would show for a credit account.

Examples

Example: with a copy of the reports/reconcile example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"reconcile.start","params":{"account":"Root:Asset:Bank","statementDate":"1970-03-01","endingBalance":"21.00"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "statementDate": "1970-03-01",
    "endingBalance": {
      "num": "2100",
      "denom": "100"
    },
    "resumedPostponed": false,
    "startingBalance": {
      "num": "-800",
      "denom": "100"
    },
    "tickedBalance": {
      "num": "2900",
      "denom": "100"
    },
    "reconciledBalance": {
      "num": "2100",
      "denom": "100"
    },
    "difference": {
      "num": "0",
      "denom": "100"
    },
    "ticked": [
      "d0000000000000000000000000000005"
    ],
    "splits": [
      {
        "split": "d0000000000000000000000000000005",
        "state": "c",
        "ticked": true,
        "…": "…"
      },
      {
        "state": "n",
        "ticked": false,
        "…": "…"
      },
      {
        "state": "n",
        "ticked": false,
        "…": "…"
      }
    ],
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash reconcile.start '{"account":"Root:Asset:Bank","statementDate":"1970-03-01","endingBalance":"21.00"}'

It prints:

{
  "statementDate": "1970-03-01",
  "endingBalance": {
    "num": "2100",
    "denom": "100"
  },
  "resumedPostponed": false,
  "startingBalance": {
    "num": "-800",
    "denom": "100"
  },
  "tickedBalance": {
    "num": "2900",
    "denom": "100"
  },
  "reconciledBalance": {
    "num": "2100",
    "denom": "100"
  },
  "difference": {
    "num": "0",
    "denom": "100"
  },
  "ticked": [
    "d0000000000000000000000000000005"
  ],
  "splits": [
    {
      "split": "d0000000000000000000000000000005",
      "state": "c",
      "ticked": true,
      "…": "…"
    },
    {
      "state": "n",
      "ticked": false,
      "…": "…"
    },
    {
      "state": "n",
      "ticked": false,
      "…": "…"
    }
  ],
  "…": "…"
}

MCP tool call

Tool call:

{"name":"reconcile.start","arguments":{"account":"Root:Asset:Bank","statementDate":"1970-03-01","endingBalance":"21.00"}}

Result:

{
  "structuredContent": {
    "statementDate": "1970-03-01",
    "endingBalance": {
      "num": "2100",
      "denom": "100"
    },
    "resumedPostponed": false,
    "startingBalance": {
      "num": "-800",
      "denom": "100"
    },
    "tickedBalance": {
      "num": "2900",
      "denom": "100"
    },
    "reconciledBalance": {
      "num": "2100",
      "denom": "100"
    },
    "difference": {
      "num": "0",
      "denom": "100"
    },
    "ticked": [
      "d0000000000000000000000000000005"
    ],
    "splits": [
      {
        "split": "d0000000000000000000000000000005",
        "state": "c",
        "ticked": true,
        "…": "…"
      },
      {
        "state": "n",
        "ticked": false,
        "…": "…"
      },
      {
        "state": "n",
        "ticked": false,
        "…": "…"
      }
    ],
    "…": "…"
  }
}

Effect: read.

Params

Params of reconcile.start. Anything absent gets GnuCash's default.

  • account (AccountRef, required): The account to reconcile.
  • statementDate (Date or null): The statement date. Defaults to the last reconcile date plus the last interval, no later than today, or the postponed statement's date.
  • endingBalance (Amount or null): The statement's ending balance, raw sign (debits positive). Defaults to the postponed balance, else the account's balance at the end of the statement date.
  • includeSubaccounts (boolean or null): Reconcile the sub-accounts too. Defaults to the account's stored choice; refused when a sub-account holds another commodity.
  • utcOffsetMinutes (integer (int32) or null): A fixed offset from UTC in minutes to use instead of the server's local time zone, for GnuCash's local-time rules (the statement date ends at 23:59:59 local time).

Result

A reconciliation in progress: the statement, the splits to tick and the window's figures. Pass the statement fields and ticked back to the next call.

  • account (Guid, required): The account reconciled.
  • statementDate (Date, required): The statement date, local to the caller's offset.
  • statementTime (Timestamp, required): The statement date as an instant: the last second of the day, as GnuCash stores it.
  • endingBalance (Amount, required): The ending balance, raw sign.
  • includeSubaccounts (boolean, required): The sub-accounts are reconciled too.
  • resumedPostponed (boolean, required): The defaults came from a postponed reconciliation.
  • lastReconcileDate (Timestamp or null): When the account was last reconciled.
  • startingBalance (Amount, required): The reconciled balance before this statement.
  • clearedBalance (Amount, required): The cleared balance (every split not n).
  • tickedBalance (Amount, required): The sum of the ticked splits.
  • reconciledBalance (Amount, required): The starting balance plus the ticked splits.
  • difference (Amount, required): The ending balance minus the reconciled balance; reconcile.finish needs it to be zero.
  • ticked (array of Guid, required): The ticked splits.
  • splits (array of CandidateWire, required): Every split that can be ticked.