Integration and API Spec

Integration and API Spec

Invoice Generation and Delivery

HubSpot is the trigger source for Agent 1 (Invoice Builder Agent) and the CRM write target for Agent 2 (Delivery and CRM Sync Agent). It provides deal properties, company contact data, and receives the invoice reference and updated deal stage on completion.

// Trigger payload (inbound webhook or poll result)
deal.id             -> string  (HubSpot deal object ID)
deal.dealname       -> string  (invoice description fallback)
deal.amount         -> number  (total deal value)
deal.dealstage      -> string  (must match HUBSPOT_STAGE_CLOSED_WON or HUBSPOT_STAGE_COMPLETE)
deal.closedate      -> ISO8601 date
// Fetched separately
deal.line_items[]   -> array   (name, quantity, unit_price, hs_sku)
company.name        -> string
company.billing_email -> string
company.payment_terms -> string  (custom property: 'payment_terms_tier')
company.tax_classification -> string  (custom property: 'tax_classification')
// Written back by Agent 2
deal.dealstage      <- HUBSPOT_STAGE_INVOICED
deal.xero_invoice_reference <- string  (Xero InvoiceNumber)

Xero is the invoice creation target for Agent 1 and the approval event source for Agent 2. Agent 1 creates a draft invoice via the Xero Invoices API. Agent 2 listens for the invoice status to change from DRAFT to AUTHORISED (approved) before triggering downstream delivery steps.

// Agent 1 writes (POST /invoices)
Type                 = 'ACCREC'
Contact.ContactID    -> looked up by billing email
LineItems[].Description  -> deal line item name
LineItems[].Quantity     -> deal line item quantity
LineItems[].UnitAmount   -> deal line item unit_price
LineItems[].AccountCode  -> XERO_DEFAULT_ACCOUNT_CODE
LineItems[].TaxType      -> resolved from payment_terms mapping table
CurrencyCode         -> deal currency (default: 'USD')
DueDateString        -> calculated from closedate + payment_terms days
Status               = 'DRAFT'
BrandingThemeID      -> XERO_BRANDING_THEME_ID
// Agent 2 reads (webhook event)
InvoiceID            -> string  (used to fetch PDF and retrieve InvoiceNumber)
InvoiceNumber        -> string  (written back to HubSpot)
Contact.EmailAddress -> string  (confirmed billing address for Gmail send)

Gmail is used by Agent 2 to send the approved invoice to the client billing contact. The email uses a branded HTML template with the invoice PDF attached. The send is triggered only after Xero webhook confirmation of AUTHORISED status.

// Input to Gmail send step
to                   -> Contact.EmailAddress (from Xero webhook event)
cc                   -> (empty unless deal property 'cc_contact_email' is populated)
bcc                  -> GMAIL_BCC_FINANCE
reply_to             -> GMAIL_REPLY_TO
subject              -> 'Invoice {{invoice_number}} from [YourCompany.com]'
body_html            -> GMAIL_INVOICE_TEMPLATE_HTML (rendered with deal values)
attachment.filename  -> 'Invoice_{{invoice_number}}.pdf'
attachment.mimeType  -> 'application/pdf'
attachment.data      -> base64(Xero PDF bytes)
// Output
messageId            -> string  (logged to Google Sheets row for audit trail)

Google Sheets serves two roles: it hosts the payment terms and tax code mapping table read by Agent 1 at runtime, and it receives an appended tracking row from Agent 2 after each invoice is sent. Both operations target the same Google Sheets file but different named sheets (tabs).

// Agent 1 reads (PaymentTermsMapping tab)
client_type          -> matched against company.tax_classification from HubSpot
payment_terms_days   -> integer (used to calculate Xero DueDateString)
xero_tax_type        -> string (e.g. 'TAX001') passed to Xero LineItems[].TaxType
// Agent 2 appends (InvoiceLog tab)
invoice_number       <- Xero InvoiceNumber
client_name          <- Xero Contact.Name
client_email         <- Xero Contact.EmailAddress
amount               <- Xero Total
currency             <- Xero CurrencyCode
send_date            <- ISO8601 timestamp of Gmail send
due_date             <- Xero DueDateString
deal_id              <- HubSpot deal.id
xero_invoice_id      <- Xero InvoiceID
gmail_message_id     <- Gmail messageId

Slack receives two types of notification from Agent 2: a draft-ready alert sent to the finance lead when Agent 1 creates the Xero draft, and a send-confirmation alert posted to the finance channel after Gmail delivery completes.

// Draft-ready DM to finance lead (sent by Agent 1 after Xero draft created)
channel              -> SLACK_FINANCE_LEAD_USER_ID
text                 -> 'Draft invoice {{invoice_number}} for {{client_name}} ({{amount}} {{currency}}) is ready for review.'
blocks[].accessory  -> Button: 'Review in Xero' -> xero_deep_link
// Send-confirmation channel message (sent by Agent 2 after Gmail send)
channel              -> SLACK_FINANCE_CHANNEL_ID
text                 -> 'Invoice {{invoice_number}} sent to {{client_email}} for {{amount}} {{currency}}. Due: {{due_date}}.'
blocks[].accessory  -> Button: 'View in Xero' -> xero_deep_link

# HubSpot
HUBSPOT_PRIVATE_APP_TOKEN      # Private app bearer token
HUBSPOT_CLIENT_SECRET          # Used for webhook signature validation
HUBSPOT_STAGE_CLOSED_WON       # Deal stage ID for Closed-Won
HUBSPOT_STAGE_COMPLETE         # Deal stage ID for Complete
HUBSPOT_STAGE_INVOICED         # Deal stage ID written back after send
HUBSPOT_INVOICE_REF_FIELD      # Internal name of invoice reference custom property

# Xero
XERO_ACCESS_TOKEN              # OAuth 2.0 access token (short-lived, auto-refreshed)
XERO_REFRESH_TOKEN             # OAuth 2.0 refresh token (60-day expiry)
XERO_TENANT_ID                 # Xero organisation (tenant) ID
XERO_BRANDING_THEME_ID         # Invoice template/branding theme ID
XERO_DEFAULT_ACCOUNT_CODE      # Default sales account code (e.g. '200')
XERO_WEBHOOK_KEY               # Webhook signing key for payload validation

# Gmail
GMAIL_REFRESH_TOKEN            # OAuth 2.0 refresh token for sending account
GMAIL_SEND_FROM                # Sending address (e.g. finance-automation@yourdomain.com)
GMAIL_REPLY_TO                 # Reply-to address for client responses
GMAIL_BCC_FINANCE              # BCC address for finance team archive
GMAIL_INVOICE_TEMPLATE_HTML    # Path or content of HTML email template

# Google Sheets
GSHEETS_REFRESH_TOKEN          # OAuth 2.0 refresh token (may share Gmail grant)
GSHEETS_SPREADSHEET_ID         # Spreadsheet ID for mapping table and invoice log

# Slack
SLACK_BOT_TOKEN                # Bot OAuth token (xoxb-...)
SLACK_FINANCE_CHANNEL_ID       # Channel ID for send-confirmation messages
SLACK_FINANCE_LEAD_USER_ID     # Slack user ID for draft-ready DMs