Integration and API Spec

Integration and API Spec

Bank Reconciliation Automation

Plaid is the bank feed connector for Agent 1 (Bank Feed Sync Agent). It retrieves new transactions from the connected bank account(s) using the Transactions product. The access token is generated once via the Link token flow and stored in the credential store; it is exchanged for a permanent access_token which is refreshed automatically. At approximately 400 transactions per month, Plaid API call volume is well within free-tier and Development-tier rate limits; no throttling logic is required at current volume.

// Input
GET /transactions/sync
{ access_token, cursor }

// Output
{
  added: [ { transaction_id, account_id, date, amount, name, payment_channel, pending } ],
  modified: [ ... ],
  removed: [ { transaction_id } ],
  next_cursor: string
}

Xero is used by all three agents: Agent 1 fetches unreconciled ledger transactions, Agent 2 posts confirmed matched pairs and marks them reconciled, and Agent 3 posts the final period close record. The same OAuth 2.0 connection and access token serve all three agents via the shared credential store. Xero access tokens expire after 30 minutes and use a refresh token (valid 60 days) to obtain new ones; the orchestration layer must handle token refresh transparently before each API call.

// Input: fetch unreconciled bank transactions
GET /api.xro/2.0/BankTransactions
?where=IsReconciled=false AND Status=AUTHORISED
&DateFrom={run_start_date}&DateTo={run_end_date}

// Input: post reconciled pair
POST /api.xro/2.0/BankTransactions
{
  BankTransactions: [
    { BankTransactionID: string, IsReconciled: true }
  ]
}

// Output: reconciliation confirmation
{ BankTransactions: [ { BankTransactionID, IsReconciled, UpdatedDateUTC } ] }

Google Sheets is used exclusively by Agent 2 (Matching and Exceptions Agent) to write unmatched and probable-match transactions to the exceptions tab, and to poll for bookkeeper sign-off before Agent 3 fires. The sheet must be pre-created from the FullSpec exceptions template and its Spreadsheet ID stored in the credential store. The service account is granted Editor access to the specific spreadsheet only.

// Input: write exceptions batch
POST /v4/spreadsheets/{SPREADSHEET_ID}/values/{range}:append
valueInputOption=USER_ENTERED
{
  values: [
    [ run_date, bank_ref, amount, description, suggested_category, match_type, context_notes, '' ]
  ]
}

// Input: poll sign-off column
GET /v4/spreadsheets/{SPREADSHEET_ID}/values/Exceptions_Active!H2:H

// Output
{ range, majorDimension, values: [ ['Resolved'] | ['Waived'] | [''] ] }

Slack is used by Agent 3 (Notifications and Close Agent) to post a structured reconciliation summary to the designated finance channel immediately after Agent 2 completes. The message includes the run date, total transactions processed, matched count, exception count, closing balance, and a hyperlink to the exceptions sheet. The bot token is stored in the credential store and must have the channel pre-joined.

// Input: post summary message
POST https://slack.com/api/chat.postMessage
{
  channel: SLACK_FINANCE_CHANNEL_ID,
  blocks: [
    { type: 'header', text: { type: 'plain_text', text: 'Reconciliation complete: {run_date}' } },
    { type: 'section', fields: [
        { type: 'mrkdwn', text: '*Transactions processed:* {total_count}' },
        { type: 'mrkdwn', text: '*Matched:* {matched_count}' },
        { type: 'mrkdwn', text: '*Exceptions:* {exception_count}' },
        { type: 'mrkdwn', text: '*Closing balance:* {closing_balance}' }
    ] },
    { type: 'actions', elements: [
        { type: 'button', text: { text: 'View exceptions sheet' }, url: {sheet_url} }
    ] }
  ]
}

// Output
{ ok: true, channel: string, ts: string, message: { ... } }

Gmail is used by Agent 3 to send a plain-text confirmation email to the finance lead once the Xero period close record has been posted. The email confirms the period is closed, lists the matched transaction count and any waived exceptions, and attaches no files. The sending address is a designated service account or delegated Gmail address stored in the credential store.

// Input: send confirmation email
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
{
  raw: base64url_encode(
    'From: {GMAIL_SENDER_ADDRESS}\r\n'
    + 'To: {FINANCE_LEAD_EMAIL}\r\n'
    + 'Subject: Reconciliation closed: {period_label}\r\n'
    + '\r\n'
    + 'Period: {period_label}\r\n'
    + 'Matched transactions: {matched_count}\r\n'
    + 'Exceptions resolved: {resolved_count}\r\n'
    + 'Exceptions waived: {waived_count}\r\n'
    + 'Xero period close record posted: {xero_record_id}\r\n'
  )
}

// Output
{ id: string, threadId: string, labelIds: ['SENT'] }

// Credential store: Bank Reconciliation Automation
// All values are stored as encrypted named secrets.
// Never hardcode any value from this list in a workflow step.

PLAID_CLIENT_ID          = "<from Plaid Dashboard>"
PLAID_SECRET_SANDBOX     = "<from Plaid Dashboard, Sandbox>"
PLAID_SECRET_PRODUCTION  = "<from Plaid Dashboard, Production>"
PLAID_ENV                = "sandbox" // switch to "production" at go-live
PLAID_ACCESS_TOKEN_ACC1  = "<generated via Link token flow, account 1>"
PLAID_ACCESS_TOKEN_ACC2  = "<generated via Link token flow, account 2 if applicable>"
PLAID_WEBHOOK_SECRET     = "<JWT verification key from /webhook_verification_key/get>"
PLAID_SYNC_CURSOR_ACC1   = "<updated on each successful /transactions/sync call>"

XERO_CLIENT_ID           = "<from Xero Developer Portal>"
XERO_CLIENT_SECRET       = "<from Xero Developer Portal>"
XERO_TENANT_ID           = "<retrieved via GET /connections after initial auth>"
XERO_REFRESH_TOKEN       = "<rotated on each token refresh>"
XERO_BANK_ACCOUNT_ID     = "<AccountID of target bank account in Xero>"
XERO_RECON_ACCOUNT_CODE  = "<Xero account code for reconciliation, e.g. '090'>"

SHEETS_SERVICE_ACCOUNT_JSON  = "<full JSON key for Google service account>"
EXCEPTIONS_SPREADSHEET_ID    = "<Google Sheets file ID from URL>"

SLACK_BOT_TOKEN              = "xoxb-<from Slack App configuration>"
SLACK_FINANCE_CHANNEL_ID     = "<channel ID, e.g. C0123456789>"

GMAIL_CLIENT_ID              = "<from Google Cloud Console>"
GMAIL_CLIENT_SECRET          = "<from Google Cloud Console>"
GMAIL_REFRESH_TOKEN          = "<from delegated Gmail account OAuth flow>"
GMAIL_SENDER_ADDRESS         = "<sending Gmail address>"
FINANCE_LEAD_EMAIL           = "<recipient email address for period close confirmation>"