Integration and API Spec

Integration and API Spec

Accounts Payable Management

Dext is the primary invoice capture layer. It accepts documents via its mobile app, email-to-inbox forwarding, and direct upload. The automation platform consumes extracted invoice data via the Dext REST API and, where available, receives push notifications via webhook when a new document reaches a processed state.

// Webhook payload (inbound to automation platform)
{
  "event": "document.published",
  "document_id": "<string>",
  "organisation_id": "<string: DEXT_ORG_ID>",
  "published_at": "<ISO8601>"
}

// GET /documents/{document_id} response (key fields consumed downstream)
{
  "supplier": { "name": "<string>", "id": "<string>" },
  "invoice_number": "<string>",
  "date": "<YYYY-MM-DD>",
  "due_date": "<YYYY-MM-DD>",
  "total_amount": "<decimal>",
  "tax_amount": "<decimal>",
  "currency": "<ISO4217>",
  "line_items": [
    { "description": "<string>", "quantity": "<decimal>", "unit_price": "<decimal>", "total": "<decimal>" }
  ],
  "document_url": "<string: signed PDF URL, 15-min TTL>"
}

Xero is the accounting system of record. The automation reads existing bills for duplicate detection, creates new bills with coded line items, and schedules payments. Three distinct API resource groups are used: Invoices (bills), Accounts (chart of accounts), and Payments.

// GET /Invoices?where=InvoiceNumber=="{invoice_number}"&ContactID="{contact_id}" (duplicate check)
// Expected: Invoices[] length === 0 for no duplicate

// POST /Invoices (bill creation body)
{
  "Type": "ACCPAY",
  "Status": "DRAFT",
  "Contact": { "ContactID": "<string>" },
  "InvoiceNumber": "<string>",
  "Date": "<YYYY-MM-DD>",
  "DueDate": "<YYYY-MM-DD>",
  "CurrencyCode": "<ISO4217>",
  "LineItems": [
    {
      "Description": "<string>",
      "Quantity": "<decimal>",
      "UnitAmount": "<decimal>",
      "AccountCode": "<string>",
      "TaxType": "<string>"
    }
  ]
}

// POST /Payments (payment scheduling body)
{
  "Invoice": { "InvoiceID": "<string>" },
  "Account": { "AccountID": "<string: AP_PAYMENT_ACCOUNT_ID>" },
  "Date": "<YYYY-MM-DD: payment run date>",
  "Amount": "<decimal>"
}

Slack is the approval routing layer. The automation posts structured Block Kit messages to a designated approver channel or direct message thread. Approvers respond using interactive button actions. The automation listens for action payloads via a registered interactivity endpoint.

// Outbound: POST https://slack.com/api/chat.postMessage
{
  "channel": "<SLACK_AP_APPROVAL_CHANNEL_ID or user_id>",
  "text": "Invoice approval required: {supplier_name} ${total_amount}",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn", "text": "*Supplier:* {supplier_name}\n*Invoice #:* {invoice_number}\n*Amount:* ${total_amount}\n*Due:* {due_date}\n*Suggested codes:* {account_codes}" } },
    { "type": "actions", "elements": [
      { "type": "button", "text": { "type": "plain_text", "text": "Approve" }, "style": "primary", "action_id": "ap_approve", "value": "{correlation_id}:{xero_invoice_id}" },
      { "type": "button", "text": { "type": "plain_text", "text": "Query" }, "style": "danger", "action_id": "ap_query", "value": "{correlation_id}:{xero_invoice_id}" }
    ]}
  ]
}

// Inbound: Slack interactivity payload (key fields)
{
  "type": "block_actions",
  "actions": [{ "action_id": "ap_approve|ap_query", "value": "{correlation_id}:{xero_invoice_id}" }],
  "user": { "id": "<slack_user_id>", "username": "<string>" }
}

Gmail serves two roles: inbound monitoring for invoices arriving via email, and outbound sending of remittance advice emails to suppliers after payment. Both roles use the Gmail API under the same OAuth 2.0 token but different method groups.

// Inbound: Pub/Sub push notification body
{
  "message": {
    "data": "<base64-encoded: {emailAddress, historyId}>",
    "messageId": "<string>"
  },
  "subscription": "<string>"
}

// GET /gmail/v1/users/{GMAIL_AP_INBOX_USER}/messages/{id}?format=full
// Key fields extracted:
//   headers: From, Subject, Date
//   parts[].mimeType === 'application/pdf' -> attachment

// Outbound: POST /gmail/v1/users/{GMAIL_AP_INBOX_USER}/messages/send
{
  "raw": "<base64url-encoded RFC 2822 message>",
  "// message body includes:": "",
  "To": "{supplier_email}",
  "Subject": "Remittance Advice: {invoice_number} - {supplier_name}",
  "Body": "Payment of ${total_amount} for invoice {invoice_number} was processed on {payment_date}."
}

Google Drive is used on the exception path of Agent 1 when an invoice references a purchase order. The automation searches the configured PO folder for a matching PO document to surface alongside the flagged invoice in the bookkeeper's exception notification. This is a read-only integration.

// GET https://www.googleapis.com/drive/v3/files
//   ?q='<GDRIVE_PO_FOLDER_ID>' in parents and name contains '<po_number>'
//   &fields=files(id,name,webViewLink,createdTime)

// Output passed to Agent 2 exception payload:
{
  "po_match_found": true,
  "po_file_id": "<string>",
  "po_file_name": "<string>",
  "po_web_link": "<string: URL for bookkeeper review>"
}

// CREDENTIAL STORE CONTENTS
// All values injected at runtime. Never committed to version control.

// --- Dext ---
DEXT_API_KEY              = "<Dext REST API key, Practice/Accountant role>"
DEXT_ORG_ID               = "<Dext organisation ID>"
DEXT_WEBHOOK_SECRET       = "<HMAC-SHA256 signing secret from Dext webhook settings>"

// --- Xero ---
XERO_CLIENT_ID            = "<OAuth 2.0 app client ID from Xero developer portal>"
XERO_CLIENT_SECRET        = "<OAuth 2.0 app client secret>"
XERO_ACCESS_TOKEN         = "<Current access token, refreshed every 30 min>"
XERO_REFRESH_TOKEN        = "<OAuth 2.0 refresh token, rotated on use>"
XERO_TENANT_ID            = "<Xero organisation tenant ID from /connections>"
XERO_DEFAULT_ACCOUNT_CODE = "<Fallback chart-of-accounts code for uncoded lines>"
AP_PAYMENT_ACCOUNT_ID     = "<Xero bank account UUID used for payment scheduling>"
XERO_AP_CONTACT_GROUP_ID  = "<Optional: Xero contact group ID scoping supplier lookups>"

// --- Slack ---
SLACK_BOT_TOKEN               = "<xoxb-... bot token from Slack App OAuth page>"
SLACK_SIGNING_SECRET          = "<Signing secret from Slack App Basic Information>"
SLACK_AP_APPROVAL_CHANNEL_ID  = "<Slack channel ID for AP approval messages>"
SLACK_REMINDER_INTERVAL_HOURS = "24"
SLACK_MAX_REMINDERS           = "2"
SLACK_APPROVER_MAP            = "{\"200\":\"U0XXXXXXX\",\"300\":\"U0YYYYYYY\"}"
// Key: Xero cost centre / account code prefix; Value: Slack user ID

// --- Gmail ---
GMAIL_CLIENT_ID               = "<Google OAuth 2.0 client ID>"
GMAIL_CLIENT_SECRET           = "<Google OAuth 2.0 client secret>"
GMAIL_ACCESS_TOKEN            = "<Current access token>"
GMAIL_REFRESH_TOKEN           = "<Refresh token with offline_access scope>"
GMAIL_AP_INBOX_USER           = "ap@[YourCompany.com]"
GMAIL_AP_LABEL_ID             = "<Gmail label ID for AP inbox filter>"
GMAIL_PROCESSED_LABEL_ID      = "<Gmail label ID: AP/Processed>"
GMAIL_REMITTANCE_FROM         = "\"[YourCompany.com] Accounts Payable\" <ap@[YourCompany.com]>"
GMAIL_REMITTANCE_TEMPLATE_ID  = "<ID of remittance email template in document store>"

// --- Google Drive ---
GDRIVE_ACCESS_TOKEN           = "<Shared with Gmail token if scopes combined>"
GDRIVE_REFRESH_TOKEN          = "<Shared with Gmail token if scopes combined>"
GDRIVE_PO_FOLDER_ID           = "<Google Drive folder ID containing PO documents>"

// --- Orchestration layer ---
AUTOMATION_PLATFORM_WEBHOOK_BASE = "https://hooks.[automation-platform-domain]/ap-automation"
INTERNAL_QUEUE_CONNECTION_STRING = "<Platform-native queue or message bus connection>"
OCR_CONFIDENCE_THRESHOLD         = "0.85"