Integration and API Spec

Integration and API Spec

Compliance & Certification Tracking

Acts as the master compliance register. Agent 1 reads rows to classify expiring items. Agent 2 reads status fields to detect unacknowledged items. Agent 3 writes updated expiry dates, certificate references, status flags, and Notion document links back to the register. All read and write operations target a single named spreadsheet identified by its Spreadsheet ID stored in the credential store.

// Read (Agents 1 and 2)
GET /v4/spreadsheets/{SHEETS_REGISTER_ID}/values/{SHEETS_TAB_NAME}!A2:I
// Returns: array of row arrays, positional columns A-I as above

// Write (Agent 3)
PUT /v4/spreadsheets/{SHEETS_REGISTER_ID}/values/{SHEETS_TAB_NAME}!C{row}:I{row}
Body: { range, majorDimension: 'ROWS', values: [[expiry_date, renewal_status, urgency_tier, doc_link, last_reminder_sent, escalated_flag, certificate_ref]] }

Used by Agent 1 to send tiered reminder emails and by Agent 2 to send escalation emails to owners and their managers. A weekly compliance report is also distributed via Gmail on a scheduled basis. All outbound emails use pre-approved templates stored in the credential store by template ID; no email body is assembled from free text at runtime.

// Send reminder or escalation email
POST /gmail/v1/users/{GMAIL_SENDER_ADDRESS}/messages/send
Body: { raw: base64url_encoded_MIME_message }
// MIME headers required: From, To, Subject, Content-Type: text/html; charset=utf-8

// Template placeholder substitution (performed by orchestration layer before API call)
template_body.replace('{{item_name}}', row.item_name)
template_body.replace('{{owner_name}}', row.owner_name)
template_body.replace('{{expiry_date}}', row.expiry_date)

Used by Agent 1 to post structured expiry alerts to the designated compliance channel and by Agent 2 to send direct messages to the item owner and their manager when escalation is triggered. The Slack app is installed once at the workspace level; the bot token and channel IDs are stored in the credential store.

// Post channel alert
POST https://slack.com/api/chat.postMessage
Headers: Authorization: Bearer {SLACK_BOT_TOKEN}, Content-Type: application/json
Body: { channel: SLACK_COMPLIANCE_CHANNEL_ID, blocks: SLACK_BLOCK_REMINDER, text: fallback_text }

// Send direct escalation message
POST https://slack.com/api/chat.postMessage
Body: { channel: {resolved_slack_user_id}, blocks: SLACK_BLOCK_ESCALATION, text: fallback_text }

// Resolve owner Slack user ID from email
GET https://slack.com/api/users.lookupByEmail?email={owner_email}
Returns: { user: { id: 'U0XXXXXXX' } }

Used by Agent 3 to file renewed certification documents in the organisation's certification library database. Each filed document creates or updates a Notion page within the designated database, using a standardised naming convention and linking the page URL back to the Google Sheets register. The Notion integration must have access to the specific database; access is not granted workspace-wide by default.

// Create new certification page in database
POST https://api.notion.com/v1/pages
Headers: Authorization: Bearer {NOTION_INTEGRATION_TOKEN}, Notion-Version: 2022-06-28
Body: { parent: { database_id: NOTION_DATABASE_ID }, properties: { Name: {title: [{text: {content: page_name}}]}, Expiry_Date: {date: {start: expiry_date}}, Owner_Email: {email: owner_email}, Certificate_Ref: {rich_text: [{text: {content: cert_ref}}]}, Status: {select: {name: 'Active'}} } }

// Update existing page
PATCH https://api.notion.com/v1/pages/{page_id}
Body: { properties: { Expiry_Date: {date: {start: new_expiry_date}}, Status: {select: {name: 'Active'}}, Renewal_Date: {date: {start: today}} } }

Used by Agent 3 to route renewal invoices to finance for payment processing. When a renewal event includes an invoice attachment or reference number, the automation creates a draft bill in Xero and assigns it to the appropriate contact. Finance staff review and approve bills in Xero; the automation does not approve or pay invoices automatically.

// Refresh access token
POST https://identity.xero.com/connect/token
Body: grant_type=refresh_token&refresh_token={XERO_REFRESH_TOKEN}&client_id={XERO_CLIENT_ID}&client_secret={XERO_CLIENT_SECRET}
Response: { access_token, refresh_token, expires_in }
// Store new refresh_token to credential store immediately

// Create draft bill
POST https://api.xero.com/api.xro/2.0/Invoices
Headers: Authorization: Bearer {access_token}, Xero-tenant-id: {XERO_TENANT_ID}, Content-Type: application/json
Body: { Type: 'ACCPAY', Contact: { ContactID: XERO_DEFAULT_AP_CONTACT_ID }, DueDate: invoice_due_date, LineItems: [{ Description: item_name + ' renewal', AccountCode: XERO_RENEWAL_ACCOUNT_CODE, UnitAmount: invoice_amount, Quantity: 1 }], Status: 'DRAFT', Reference: certificate_ref }

// Credential store contents (all keys required before go-live)

// Google (shared by Sheets and Gmail integrations)
GOOGLE_SERVICE_ACCOUNT_JSON      = <service account JSON key, base64-encoded>
GOOGLE_IMPERSONATION_ADDRESS     = compliance-automation@[YourCompany.com]

// Google Sheets
SHEETS_REGISTER_ID               = <32-char spreadsheet ID from URL>
SHEETS_TAB_NAME                  = ComplianceRegister

// Gmail templates (IDs reference pre-built template objects in the orchestration layer)
GMAIL_SENDER_ADDRESS             = compliance-automation@[YourCompany.com]
GMAIL_TEMPLATE_REMINDER_90       = tmpl_reminder_90d
GMAIL_TEMPLATE_REMINDER_60       = tmpl_reminder_60d
GMAIL_TEMPLATE_REMINDER_30       = tmpl_reminder_30d
GMAIL_TEMPLATE_ESCALATION        = tmpl_escalation
GMAIL_TEMPLATE_REPORT            = tmpl_weekly_report

// Slack
SLACK_BOT_TOKEN                  = xoxb-<workspace-bot-token>
SLACK_COMPLIANCE_CHANNEL_ID      = C<11-char channel ID>
SLACK_BLOCK_REMINDER             = <JSON string of Slack Block Kit template>
SLACK_BLOCK_ESCALATION           = <JSON string of Slack Block Kit escalation template>
SLACK_MANAGER_LOOKUP             = <JSON map: { owner_email: manager_slack_user_id, ... }>

// Notion
NOTION_INTEGRATION_TOKEN         = secret_<43-char internal integration token>
NOTION_DATABASE_ID               = <32-char database ID from URL>
NOTION_NAMING_CONVENTION         = {ITEM_NAME}_{OWNER_INITIALS}_{EXPIRY_YYYY-MM-DD}

// Xero
XERO_CLIENT_ID                   = <Xero app client ID>
XERO_CLIENT_SECRET               = <Xero app client secret>
XERO_REFRESH_TOKEN               = <current refresh token; updated after each use>
XERO_TENANT_ID                   = <Xero organisation/tenant ID>
XERO_DEFAULT_AP_CONTACT_ID       = <Xero ContactID for AP approver>
XERO_RENEWAL_ACCOUNT_CODE        = 420

// Webhook security
WEBHOOK_SECRET                   = <min 32-char random string, used for HMAC-SHA256 validation>

// Reporting
REPORT_RECIPIENT_LIST            = ops-manager@[YourCompany.com], finance-lead@[YourCompany.com]