Integration and API Spec

Integration and API Spec

Cash Flow Forecasting Automation

Used by Agent 1 (Data Collection Agent) to retrieve cleared bank transactions, AR ageing buckets, and upcoming bills payable within the next 8 weeks. All calls are made server-side on a Monday schedule trigger. Pagination must be handled; Xero returns a maximum of 100 records per page for transaction endpoints.

// Input
XERO_TENANT_ID: string (UUID from credential vault)
date_from: ISO-8601 string (Monday minus 7 days)
date_to: ISO-8601 string (today, Monday 08:00 local)
// Output
xero_transactions: Transaction[]  // cleared bank transactions
xero_ar_ageing: ARBucket[]        // overdue buckets: current, 1-30, 31-60, 61-90, 90+
xero_bills_payable: Bill[]        // upcoming bills with DueDate and AmountDue

Used by Agent 1 (Data Collection Agent) to retrieve the payout schedule for the next 8 weeks. Only read access is required. The restricted API key model is preferred over a full secret key.

// Input
STRIPE_RESTRICTED_KEY: string (from credential vault)
arrival_date_lte: Unix timestamp (today + 56 days)
// Output
stripe_payouts: Payout[]  // fields: id, amount, currency, arrival_date (ISO-8601), status

Used by Agent 2 (Categorisation Agent) to write categorised transaction data into the master forecast sheet, and by Agent 3 (Distribution Agent) to poll the approval cell and trigger downstream delivery. A service account is used to avoid dependency on an individual user's credentials.

// Input (Agent 2 write)
categorised_payload: CategorisedTransaction[]
flagged_items: FlaggedTransaction[]
SHEETS_SPREADSHEET_ID: string
SHEETS_DATA_RANGE: string
// Input (Agent 3 poll)
SHEETS_APPROVAL_NAMED_RANGE: string
// Output (Agent 3 PDF export)
pdf_binary: Buffer  // exported from SHEETS_SUMMARY_TAB_NAME
pdf_filename: string  // e.g. 'CashForecast_2024-06-17.pdf'

Used by Agent 3 (Distribution Agent) to send the approved forecast PDF to the stakeholder distribution list. Sends from a designated service address using delegated OAuth credentials. No inbound email processing is required.

// Input
pdf_binary: Buffer  (from Google Sheets PDF export)
pdf_filename: string
run_date: ISO-8601 string
GMAIL_SENDER_ADDRESS: string
GMAIL_RECIPIENT_LIST: string[]
GMAIL_SUBJECT_TEMPLATE: string
// Output
gmail_message_id: string  // returned by Gmail API on success
gmail_thread_id: string

Used by Agent 3 (Distribution Agent) to post a formatted cash summary message to the finance channel immediately after the Gmail send succeeds. Uses a Slack Bot Token with a dedicated app installed in the workspace.

// Input
opening_balance: number  (currency, from categorised payload)
week4_projected_balance: number
flagged_weeks_count: integer
run_date: ISO-8601 string
approval_timestamp: ISO-8601 string
SLACK_BOT_TOKEN: string
SLACK_FINANCE_CHANNEL_ID: string
// Output
slack_ts: string   // message timestamp, used as message ID
slack_channel: string  // echoed channel ID confirming delivery

// Credential store manifest
// All entries are encrypted at rest in the platform credential vault
// Format: KEY_NAME : type : owner agent(s)

XERO_CLIENT_ID           : string  : Agent 1
XERO_CLIENT_SECRET       : string  : Agent 1
XERO_TENANT_ID           : string  : Agent 1
XERO_ACCESS_TOKEN        : string  : Agent 1  // rotated automatically on refresh
XERO_REFRESH_TOKEN       : string  : Agent 1  // rotated automatically on refresh

STRIPE_RESTRICTED_KEY    : string  : Agent 1
STRIPE_WEBHOOK_SECRET    : string  : future use only (not active in Standard build)

GOOGLE_SERVICE_ACCOUNT_JSON : json : Agent 2, Agent 3
SHEETS_SPREADSHEET_ID    : string  : Agent 2, Agent 3
SHEETS_DATA_RANGE        : string  : Agent 2  // e.g. 'ForecastData!A2:J500'
SHEETS_APPROVAL_NAMED_RANGE : string : Agent 3  // 'FORECAST_APPROVAL'
SHEETS_SUMMARY_TAB_NAME  : string  : Agent 3  // e.g. 'Summary'

GMAIL_SENDER_ADDRESS     : string  : Agent 3
GMAIL_RECIPIENT_LIST     : json    : Agent 3  // array of email strings
GMAIL_SUBJECT_TEMPLATE   : string  : Agent 3
GMAIL_BODY_TEMPLATE_ID   : string  : Agent 3

SLACK_BOT_TOKEN          : string  : Agent 3
SLACK_FINANCE_CHANNEL_ID : string  : Agent 3
SLACK_MESSAGE_TEMPLATE_ID : string : Agent 3

SCHEDULE_TIMEZONE        : string  : Agent 1  // e.g. 'America/New_York'
APPROVAL_TIMEOUT_HOURS   : integer : Agent 3  // default: 8
OWNER_ALERT_EMAIL        : string  : Agent 1, Agent 3  // fallback alert recipient
MAX_RETRY_ATTEMPTS       : integer : Agent 1  // default: 3
RETRY_BACKOFF_BASE_SECONDS : integer : Agent 1  // default: 60