Integration and API Spec

Integration and API Spec

End of Month Close Automation

Used by Agent 2 (Reconciliation) and Agent 3 (Accruals and Reporting). Reads transactions, bank statements, and coded rules; writes journal entries; reads aged reports and final period figures for the management pack.

// Reads (Agent 2)
GET /api.xro/2.0/BankTransactions?where=Status=="AUTHORISED"&fromDate={period_start}&toDate={period_end}
GET /api.xro/2.0/BankStatements/{bankAccountID}
GET /api.xro/2.0/Items  // coding rules reference
// Writes (Agent 3)
POST /api.xro/2.0/ManualJournals  // accruals and prepayments
// Reads (Agent 3)
GET /api.xro/2.0/Reports/TrialBalance?date={period_end}
GET /api.xro/2.0/Reports/ProfitAndLoss?fromDate={period_start}&toDate={period_end}
GET /api.xro/2.0/Reports/BalanceSheet?date={period_end}
GET /api.xro/2.0/Reports/AgedPayablesByContact

Used by Agent 2 (writes exceptions list) and Agent 3 (reads accruals schedule, writes management accounts pack). The automation platform authenticates via a dedicated service account with domain delegation so no user OAuth consent is required at runtime.

// Agent 2 writes
POST /v4/spreadsheets/{SHEETS_EXCEPTIONS_ID}/values/{range}:append
// body: { values: [[transaction_id, date, amount, description, status, note]] }
// Agent 3 polls
GET /v4/spreadsheets/{SHEETS_EXCEPTIONS_ID}/values/Exceptions!B1
// Agent 3 reads accruals
GET /v4/spreadsheets/{SHEETS_ACCRUALS_ID}/values/Accruals_Schedule!A:G
// Agent 3 writes pack
PUT /v4/spreadsheets/{SHEETS_MGMT_PACK_ID}/values/{range}:update

Used by Agent 1 (chase emails and 24-hour reminders) and Agent 3 (final report distribution). Sends via the Gmail API using a service account with domain-wide delegation so mail is sent as the bookkeeper or controller address rather than a generic service address.

// Agent 1: send chase
POST /gmail/v1/users/me/messages/send
// body: RFC 2822 MIME message, base64url-encoded
// Agent 1: monitor replies
GET /gmail/v1/users/me/history?startHistoryId={historyId}&historyTypes=messageAdded
// Agent 3: send distribution
POST /gmail/v1/users/me/messages/send  // with PDF attachment, base64url-encoded

Used by Agent 1 for internal close-status notifications and parallel alerts to the chase emails. A dedicated Slack App is created for the automation with a Bot Token scoped to the minimum required permissions.

// Agent 1: post notification
POST https://slack.com/api/chat.postMessage
// body: { channel: SLACK_CHANNEL_FINANCE, text: '...', blocks: [...] }
// Authorization: Bearer {SLACK_BOT_TOKEN}

Used by Agent 2 (Reconciliation). Fetches published supplier documents (invoices and receipts) that have been pushed from Hubdoc to Xero. The integration reads document metadata to enrich the reconciliation matching logic.

// Agent 2: fetch published documents
GET https://api.hubdoc.com/v1/documents?status=published&created_after={period_start}&created_before={period_end}&limit=100&page={n}
// Authorization: Bearer {HUBDOC_API_KEY}
// Response fields used: id, supplier_name, total_amount, currency, date, xero_transaction_id

Used by Agent 2 (Reconciliation) as a secondary document source. Dext (formerly Receipt Bank) provides expense receipts and supplier bills submitted by staff. The integration reads extracted document data to supplement Hubdoc coverage.

// Agent 2: fetch published items (polling fallback)
GET https://api.dext.com/v1/items?status=published&date_from={period_start}&date_to={period_end}
// Authorization: Bearer {DEXT_API_KEY}
// Webhook: inbound event
POST {DEXT_WEBHOOK_ENDPOINT}
// Header: X-Dext-Signature-256: sha256=<hmac>
// Body fields used: item_id, supplier_name, total, currency, date, category, xero_bill_id

// Credential store contents (key names only - values stored encrypted)

// Xero
XERO_CLIENT_ID
XERO_CLIENT_SECRET
XERO_TENANT_ID
XERO_BANK_ACCOUNT_IDS          // JSON array of account GUIDs
XERO_ACCOUNT_MAP               // JSON object: { "account_code": "category_label" }

// Google (Sheets + Gmail shared service account)
GOOGLE_SERVICE_ACCOUNT_JSON    // Full JSON key file contents
GMAIL_SENDER_ADDRESS           // e.g. bookkeeper@[YourCompany.com]
GMAIL_CHASE_TEMPLATE_ID        // Template string or Sheets reference
GMAIL_REMINDER_TEMPLATE_ID
GMAIL_REPORT_TEMPLATE_ID
GMAIL_DISTRIBUTION_LIST        // JSON array: [{ name, email }, ...]
GMAIL_PUBSUB_TOPIC             // projects/{project}/topics/{topic}

// Google Sheets
SHEETS_EXCEPTIONS_ID           // Spreadsheet ID
SHEETS_ACCRUALS_ID             // Spreadsheet ID
SHEETS_MGMT_PACK_ID            // Spreadsheet ID

// Slack
SLACK_BOT_TOKEN                // xoxb-...
SLACK_CHANNEL_FINANCE          // Channel ID e.g. C04XXFINANCE
SLACK_CHANNEL_ALERTS           // Channel ID
SLACK_USER_MAP                 // JSON object: { "Full Name": "UXXXXXXXX" }

// Hubdoc
HUBDOC_API_KEY
HUBDOC_ORG_ID

// Dext
DEXT_API_KEY
DEXT_WORKSPACE_ID
DEXT_WEBHOOK_SECRET
DEXT_WEBHOOK_ENDPOINT          // Public URL of platform webhook receiver

// Platform
BUSINESS_CALENDAR_REGION       // e.g. US, GB, AU - for last-business-day calc
MATCH_CONFIDENCE_THRESHOLD     // Default: 0.80