Integration and API Spec

Integration and API Spec

Budget Planning and Approval

Receives standardised budget submissions from department heads. The form is pre-populated with department name and prior period actuals pulled from the master Google Sheet. Responses feed directly into the linked response Sheet tab consumed by Agent 2.

// Output (to Google Sheets response tab)
response.timestamp       -> Column A: Timestamp
response.department_name -> Column B: Department
response.cost_category   -> Column C: Category
response.line_description-> Column D: Description
response.amount_requested-> Column E: Amount
response.notes           -> Column F: Notes

Central data store for the entire workflow. Three key tabs are used: (1) SubmissionTracker, (2) FormResponses (linked from Google Forms), and (3) MasterBudget. The orchestration layer reads and writes to all three tabs across all three agents.

// Read (Agent 1): SubmissionTracker tab
SubmissionTracker!A:F -> department list, status, reminder flags
CONFIG!B2            -> deadline_timestamp
// Write (Agent 1): SubmissionTracker tab
SubmissionTracker!B{row} -> 'Late' if deadline passed
SubmissionTracker!E{row} -> TRUE after 48h reminder sent
SubmissionTracker!F{row} -> TRUE after 24h reminder sent
// Read (Agent 2): FormResponses tab
FormResponses!A:F    -> all validated submission rows
// Write (Agent 2): MasterBudget tab
MasterBudget!A:I     -> consolidated rows with variance flags
// Write (Agent 3): MasterBudget!I{row}
MasterBudget!I{row}  -> TRUE after finance marks cleared
MasterBudget + Drive URL -> appended to archive log row

Source of prior period actuals used to populate variance columns in the MasterBudget tab. The integration reads account transaction data scoped to the relevant tracking categories and reporting period. No write operations are performed against Xero.

// API call (Agent 2)
GET /api.xro/2.0/Reports/ProfitAndLoss
  ?fromDate={period_start}
  ?toDate={period_end}
  ?trackingCategoryID={XERO_TRACKING_ID}
// Mapped output -> MasterBudget tab
Report.Rows[].Cells[].Value -> MasterBudget!E (Prior Actuals per cost centre)

Used by Agent 1 to send targeted submission deadline reminders to individual department heads, and by Agent 3 to post a completion notification to the finance channel once the signed document is archived.

// Agent 1: deadline reminder DM
POST /api/slack/chat.postMessage
  channel: {dept_head_user_id}
  text:    'Reminder: {department_name} budget submission due {deadline_datetime}'
// Agent 3: completion notification
POST /api/slack/chat.postMessage
  channel: {finance_channel_id}
  text:    'Budget approval complete. Signed document archived: {drive_url}'

Used by Agent 3 to generate a signing envelope from the consolidated budget summary document, dispatch it to signatories in the configured order, and receive a completion webhook event when all signatures are captured.

// Agent 3: create envelope
POST /v2.1/accounts/{DOCUSIGN_ACCOUNT_ID}/envelopes
  body.documents[0].documentBase64 -> base64 PDF of MasterBudget summary
  body.recipients.signers           -> DOCUSIGN_SIGNERS array
  body.envelopeDefinition.status    -> 'sent'
// Inbound webhook (Connect event)
POST {orchestration_webhook_endpoint}
  event.envelopeId     -> matched to active cycle
  event.status         -> 'completed' | 'declined' | 'voided'
  event.completedDateTime -> written to MasterBudget archive log

Used by Agent 3 to upload the signed budget document (downloaded from DocuSign after envelope completion) to the correct period-specific folder and to return the shareable file URL for the Slack completion notification.

// Agent 3: check or create sub-folder
GET /drive/v3/files?q='GDRIVE_ARCHIVE_FOLDER_ID' in parents and name='{cycle_name} Signed Budget'
POST /drive/v3/files  (if folder not found)
  body.name     -> '{cycle_name} Signed Budget'
  body.mimeType -> 'application/vnd.google-apps.folder'
  body.parents  -> [GDRIVE_ARCHIVE_FOLDER_ID]
// Agent 3: upload signed PDF
POST /upload/drive/v3/files?uploadType=multipart
  metadata.name    -> 'BudgetApproval_{cycle_name}_{ISO_date}.pdf'
  metadata.parents -> [sub_folder_id]
  media body       -> signed PDF binary from DocuSign
// Output
file.webViewLink -> SLACK completion message + MasterBudget archive log

// Credential store contents (all keys stored as encrypted secrets)

// Google Workspace (service account)
GOOGLE_SA_KEY                  = {service account JSON key, full content}
GSHEETS_MASTER_ID              = {Google Sheets workbook ID string}
GDRIVE_ARCHIVE_FOLDER_ID       = {Google Drive parent folder ID string}
GFORMS_BUDGET_FORM_ID          = {Google Forms form ID string}
GFORMS_ENTRY_DEPT              = {pre-fill entry ID for Department Name field}
GFORMS_ENTRY_ACTUALS           = {pre-fill entry ID for Prior Actuals field}

// Xero
XERO_CLIENT_ID                 = {OAuth app client ID}
XERO_CLIENT_SECRET             = {OAuth app client secret}
XERO_ACCESS_TOKEN              = {current access token, refreshed by workflow}
XERO_REFRESH_TOKEN             = {current refresh token, updated on each refresh}
XERO_TENANT_ID                 = {connected Xero organisation tenant ID}
XERO_TRACKING_ID               = {tracking category ID for cost centre mapping}

// Slack
SLACK_BOT_TOKEN                = xoxb-{workspace bot token}

// DocuSign
DOCUSIGN_INTEGRATION_KEY       = {DocuSign app integration key (client ID)}
DOCUSIGN_RSA_PRIVATE_KEY       = {RSA private key PEM for JWT grant flow}
DOCUSIGN_ACCOUNT_ID            = {DocuSign account GUID}
DOCUSIGN_BASE_URI              = https://{subdomain}.docusign.net
DOCUSIGN_TEMPLATE_ID           = {envelope template ID, if using pre-built template}
DOCUSIGN_SIGNERS               = [{name, email, routingOrder} JSON array]
DOCUSIGN_CONNECT_HMAC_SECRET   = {Connect webhook HMAC shared secret}

// Orchestration layer webhook secrets
AGENT2_WEBHOOK_SECRET          = {shared secret for Agent 2 inbound webhook}
AGENT3_WEBHOOK_SECRET          = {shared secret for Agent 3 inbound webhook}