Integration and API Spec

Integration and API Spec

Accounts Receivable and Chasing

Xero is polled daily by the orchestration layer to retrieve all invoices with a status of AUTHORISED or OVERDUE where the DueDate is in the past and the AmountDue is greater than zero. The same connection is used later in the flow to apply payment records when a bank feed match is confirmed.

// Poll output (per invoice)
InvoiceID        : string (UUID)
InvoiceNumber    : string
Contact.Name     : string
Contact.EmailAddress : string
Contact.ContactID : string (UUID)
AmountDue        : decimal
DueDate          : ISO8601 date string
Status           : string (AUTHORISED | OVERDUE)
// Payment write input
InvoiceID        : string (UUID)
Amount           : decimal
Date             : ISO8601 date string
Account.Code     : string (bank account code from Xero chart of accounts)

Gmail sends all outbound reminder emails from the designated finance inbox. Emails are composed by the orchestration layer using pre-approved tiered templates, with invoice-specific values injected at send time. The from address must match the authorised send-as address in Google Workspace.

// Input per send action
to              : string (client email address from Xero contact)
from            : string (authorised send-as address, from credential store)
subject         : string (rendered from template)
body_html       : string (rendered HTML template with injected values)
body_text       : string (plain-text fallback)
// Output (Gmail API response)
message_id      : string (Gmail message ID, stored to Google Sheets log)
thread_id       : string
labelIds        : array

Google Sheets serves as the central chase log. Before each reminder send, the orchestration layer reads the sheet to determine how many reminders have already been sent for a given invoice and when the last one was dispatched. After each action, a new row is appended recording the outcome.

// Read input (reminder history lookup)
spreadsheet_id  : string (from credential store)
range           : string  e.g. 'chase_log!A:K'
filter_field    : invoice_id
// Read output
reminder_count  : integer
last_reminder_date : string (ISO8601)
// Write input (append row after action)
invoice_id      : string
invoice_number  : string
client_name     : string
client_email    : string
amount_due      : decimal
due_date        : string (ISO8601)
days_overdue    : integer
reminder_count  : integer (incremented)
last_reminder_date : string (ISO8601, today)
last_reminder_subject : string
gmail_message_id : string

Slack receives a formatted escalation alert when an invoice meets the escalation threshold: 60 or more days overdue, or three or more reminders sent without payment. Alerts are posted to the designated finance channel using a Slack bot token.

// Input
channel         : string (channel ID from credential store)
text            : string (fallback plain text)
blocks          : array (Slack Block Kit JSON with invoice details)
  > client_name     : string
  > invoice_number  : string
  > amount_due      : decimal
  > days_overdue    : integer
  > reminder_count  : integer
  > xero_invoice_url : string
// Output
ok              : boolean
ts              : string (message timestamp, store for audit)

HubSpot receives a note on the client's contact record after each reminder send and after each payment reconciliation. The note records the current reminder stage or confirms payment received. The contact is matched by email address from the Xero invoice contact.

// Contact search input
filterGroups[0].filters[0].propertyName : 'email'
filterGroups[0].filters[0].operator     : 'EQ'
filterGroups[0].filters[0].value        : string (client email from Xero)
// Contact search output
results[0].id   : string (HubSpot contact ID)
// Note create input (POST /crm/v3/objects/notes)
properties.hs_note_body  : string (rendered template)
properties.hs_timestamp  : string (ISO8601 UTC)
associations[0].to.id    : string (contact ID)
associations[0].types[0].associationCategory : 'HUBSPOT_DEFINED'
associations[0].types[0].associationTypeId   : 202
// Note create output
id              : string (HubSpot note ID, store to Google Sheets log)

// Credential store contents (all values stored as secrets, referenced by key name)

// Xero
XERO_CLIENT_ID            : string   // OAuth app client ID
XERO_CLIENT_SECRET        : string   // OAuth app client secret
XERO_TENANT_ID            : string   // Xero organisation tenant ID
XERO_ACCESS_TOKEN         : string   // Auto-rotated by platform
XERO_REFRESH_TOKEN        : string   // Auto-rotated by platform, 60-day expiry
XERO_BANK_ACCOUNT_CODE    : string   // Chart of accounts code for payment matching

// Gmail / Google Workspace
GOOGLE_CLIENT_ID          : string   // Shared Google Cloud project OAuth client ID
GOOGLE_CLIENT_SECRET      : string   // Shared Google Cloud project OAuth client secret
GOOGLE_ACCESS_TOKEN       : string   // Auto-rotated by platform
GOOGLE_REFRESH_TOKEN      : string   // Auto-rotated by platform
GMAIL_SEND_AS_ADDRESS     : string   // Authorised send-as email address

// Google Sheets
SHEETS_SPREADSHEET_ID     : string   // AR Chase Log spreadsheet ID
SHEETS_LOG_TAB            : string   // Value: chase_log
SHEETS_EXCEPTIONS_TAB     : string   // Value: exceptions_list

// Slack
SLACK_BOT_TOKEN           : string   // xoxb-... bot token
SLACK_FINANCE_CHANNEL_ID  : string   // Target channel ID (not channel name)

// HubSpot
HUBSPOT_ACCESS_TOKEN      : string   // Private app token, rotate every 90 days
HUBSPOT_PORTAL_ID         : string   // HubSpot portal ID
HUBSPOT_NOTE_ASSOC_TYPE   : integer  // Value: 202 (confirm against target portal)

// Orchestration
ENV                       : string   // sandbox | production
BUSINESS_TIMEZONE         : string   // e.g. Australia/Sydney
REMINDER_MIN_INTERVAL_DAYS: integer  // Minimum days between reminders, e.g. 7
ESCALATION_DAYS_THRESHOLD : integer  // Days overdue before escalation, e.g. 60
ESCALATION_REMINDER_COUNT : integer  // Reminder count before escalation, e.g. 3