Budget Calendar API integration (MiShell · OpenFinance)

Deliverables checklist

• OpenAPI 3.1 spec for the statement, recurring, and stats endpoints
• Protocol report: file-format layout, encoding, version notes, recurrence schema
• Runnable Python and Node.js source for the Drive watcher + parser
• Webhook emitter so your stack is notified on each new sync
• Reconciliation script for desktop/mobile divergence (last-write-wins + conflict log)
• PIPEDA / GDPR consent template and data-retention defaults
• Automated tests covering 50+ recorded sample budget files

Engagement models

• Source code delivery from $300 — runnable code and docs handed over; pay after delivery upon satisfaction.
• Pay-per-call hosted API — point your client at our endpoint and pay per request; no upfront fee, ideal for finance coaches running a small client roster.
• Bespoke retainer — when the integration must follow MiShell desktop releases or add new categorization logic over time.

1. Coaching dashboard for financial planners

A Canadian financial-coaching service onboards each client by asking them to share a folder in Google Drive containing their Budget Calendar backup. Our watcher ingests every new save and pushes normalized transactions into the coach's dashboard. Business context: coaches review weekly cash-flow. Data: Transaction + Recurring payment + Monthly statistic. OpenFinance mapping: AISP-style read-only consent on a user-owned data store rather than a bank.

2. Bookkeeping bridge to QuickBooks / Xero

Self-employed users who keep personal and small-business spend in Budget Calendar can sync only the business-tagged transactions to accounting software. Context: avoid double-entry. Data: Transaction (filtered by category icon) + Excel export fallback. Mapping: JSON statement endpoint feeds the accounting platform's bank-feed importer.

3. Desktop ↔ mobile reconciliation

Users on the MiShell desktop trial plus the Android app frequently get drift between machines. Our reconciliation service reads both file formats, applies last-write-wins per record id, and emits a conflict log. Context: multi-device household budgets. Data: Sync metadata + Transaction history. Mapping: follows ISO/IEC 27001 audit-trail guidance for change tracking.

4. Cash-flow forecast webhook

A neobank partner wants to send a nudge when a customer's projected balance, based on Budget Calendar recurring entries, dips below a threshold. Context: proactive overdraft prevention. Data: Recurring payment projections + Balance adjustment. Mapping: matches the AISP "forward-looking statement" pattern that Plaid's Open Banking documentation describes for European personal-finance use cases.

5. Tax-season packaging

Once a year, accountants ask their clients for a full transaction log. Our Excel-aware parser collects the user's most recent export, normalizes columns to a CRA/IRS-friendly layout, signs the file, and returns a download link. Context: annual reporting. Data: Excel export + Category & icon. Mapping: short-lived consent token, single-purpose access.

Statement query API

POST /api/v1/budget-calendar/statement
Content-Type: application/json
Authorization: Bearer <ACCESS_TOKEN>

{
  "user_id": "u_9f3a1c",
  "from_date": "2026-04-01",
  "to_date":   "2026-04-30",
  "include": ["transactions", "recurring", "balance_adjust"],
  "currency": "CAD"
}

200 OK
{
  "user_id": "u_9f3a1c",
  "range": {"from":"2026-04-01","to":"2026-04-30"},
  "transactions": [
    {
      "id": "tx_4012",
      "date": "2026-04-08",
      "amount": -42.55,
      "currency": "CAD",
      "category": "groceries",
      "icon": "cart",
      "note": "Loblaws",
      "is_recurring": false
    }
  ],
  "stats": {"income": 3200.00, "spend": 2118.40, "net": 1081.60}
}

Drive backup webhook (server → client)

POST https://your-app.example.com/hooks/budget-calendar
X-OFL-Signature: t=1715472000,v1=8e2a...
Content-Type: application/json

{
  "event": "budget_file.synced",
  "user_id": "u_9f3a1c",
  "file": {
    "drive_id": "1aBcD...",
    "name": "budget_2026.mbc",
    "modified_at": "2026-05-11T08:14:22Z",
    "device": "android-pixel7"
  },
  "diff": {
    "added": 3, "updated": 1, "removed": 0,
    "new_tx_ids": ["tx_4013","tx_4014","tx_4015"]
  }
}

Verify with HMAC-SHA256 over the raw body using your shared signing key.

Auth: per-user Drive consent (Node.js)

// Exchange Google OAuth code for a folder-scoped refresh token
const url = "https://oauth2.googleapis.com/token";
const body = new URLSearchParams({
  code,
  client_id: process.env.G_CLIENT_ID,
  client_secret: process.env.G_CLIENT_SECRET,
  redirect_uri: process.env.G_REDIRECT,
  grant_type: "authorization_code"
});
const res = await fetch(url, { method: "POST", body });
if (!res.ok) throw new Error("oauth_exchange_failed: " + res.status);
const { refresh_token, access_token } = await res.json();

// Store refresh_token encrypted; access_token is short-lived.
// Scope used: https://www.googleapis.com/auth/drive.file
// → only files the user explicitly opens with our app are visible.

Error envelope

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": "sync_conflict",
  "message": "Two device saves within 30s; last-write-wins applied.",
  "winner_device": "android-pixel7",
  "loser_device":  "windows-desktop",
  "trace_id": "01HXY...EE"
}

Common errors:
  401 invalid_token        – refresh the OAuth grant
  403 drive_scope_denied   – user revoked folder access
  410 file_format_unknown  – MiShell desktop bumped its version
  429 rate_limited         – back off per Retry-After header

Regulatory baseline

Budget Calendar is published by a Canadian developer and used worldwide, so our integrations follow Canada's PIPEDA for personal-data handling, the EU GDPR data-minimization principle for European users, and the spirit of PSD2 consent and revocation for any flow that resembles an Account Information Service. Where the user explicitly opts in, we also produce CCPA-style data-export and delete-on-request endpoints.

Operational safeguards

• Drive scope is drive.file — never drive — so unrelated files stay invisible.
• All refresh tokens encrypted at rest with envelope keys (AWS KMS or GCP KMS).
• Audit log per request: user id, scope, endpoint, sha256 of payload, retention 90 days.
• Right-to-erasure endpoint wipes parsed cache, token, and logs within 30 days.
• Optional on-prem deployment for coaching firms that must keep data in Canada.

About us

OpenFinance Lab is an independent studio that builds compliant integrations for mobile and desktop finance apps. Our engineers come from neobanking, payment-aggregator, and ERP backgrounds, and we have shipped OpenFinance-style adapters for calendar-budget tools, e-wallets, bank apps, and accounting suites used across Canada, the United States, and the European Union.

• Protocol analysis: file formats, OAuth handshakes, sync trees, recurrence rules.
• API engineering: REST and webhook layers, OpenAPI specs, SDKs in Python, Node.js, Go.
• Privacy & compliance reviews aligned with PIPEDA, GDPR, and PSD2 expectations.
• Pricing: source-code delivery from $300, or pay-per-call on our hosted endpoints.
• Delivery cadence: most first drops ship within two business weeks.

Contact

Send us the target app and your integration scope. We respond within one business day with a written estimate, deliverables list, and a sample data shape.

Open the contact page

Engagement workflow

1. Scope confirmation: list of endpoints, target user count, regions, retention rules.
2. Protocol analysis on a sample Budget Calendar file the customer provides (2–4 business days).
3. Implementation of the parser, Drive watcher, and JSON endpoints (3–7 business days).
4. Compliance pass: PIPEDA / GDPR review, signed audit log spec, revoke endpoint.
5. Hand-off: source code, OpenAPI spec, automated tests, deployment notes.

FAQ

Does Budget Calendar by MiShell expose an official public API?

What data can be extracted for OpenFinance use cases?

How is user consent and privacy handled?

How long does a typical Budget Calendar integration take?