Integration and API Spec

Integration and API Spec

Tax Preparation Workflow

Provides the transaction export (P&L, balance sheet, general ledger) that seeds the Document Gap Detector and is referenced by the Receipt Collection Coordinator for transaction matching. Used by Agents 1 and 2.

// API base URL
https://quickbooks.api.intuit.com/v3/company/{realmId}/

// Report endpoint example
GET /reports/ProfitAndLoss?start_date={period_start}&end_date={period_end}&accounting_method=Accrual

// Transaction query endpoint
POST /query?query=SELECT * FROM Transaction WHERE TxnDate >= '{period_start}' AND TxnDate <= '{period_end}'

// Output fields consumed downstream
transaction.Id, transaction.TxnDate, transaction.Amount, transaction.AccountRef.name,
transaction.EntityRef.name, transaction.PrivateNote, transaction.Attachments[]

Receives uploaded receipt documents, runs OCR extraction, and returns structured field data for matching against QuickBooks transactions. Used exclusively by Agent 2 (Receipt Collection Coordinator).

// Inbound: upload document
POST /documents
Content-Type: multipart/form-data
Body: { file: <binary>, filename: <string>, folder_id: <string> }

// Outbound webhook payload (document.processed)
{
  "event": "document.processed",
  "document": {
    "id": "<hubdoc_doc_id>",
    "vendor": "<extracted_vendor_name>",
    "date": "<extracted_date_YYYY-MM-DD>",
    "total": <extracted_amount_float>,
    "currency": "<ISO_4217_code>",
    "confidence": <0.0_to_1.0>,
    "folder_id": "<string>"
  }
}

Sends personalised receipt request emails to individual employees and monitors replies and attachment uploads. Used by Agent 2 (Receipt Collection Coordinator).

// Send receipt request
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
Body: { raw: <base64url_encoded_MIME_message> }

// MIME message key headers
To: {{employee_email}}
Subject: Action required: receipts needed for {{period_label}}
In-Reply-To: <not set on initial send>
X-TAX-PREP-TOKEN: {{unique_request_token}}  // for reply correlation

// List messages with label
GET /gmail/v1/users/me/messages?labelIds=TAX_PREP_REPLY&q=is:unread

// Output fields consumed downstream
message.id, message.threadId, message.payload.headers[From],
message.payload.parts[].filename, message.payload.parts[].body.attachmentId

Stores the preparation checklist (Google Sheet), incoming documents, and the final assembled tax package. Used by Agents 1 and 3.

// Read checklist sheet
GET https://sheets.googleapis.com/v4/spreadsheets/{checklist_sheet_id}/values/{sheet_tab}!A:H

// Update checklist row status
PUT /v4/spreadsheets/{checklist_sheet_id}/values/{sheet_tab}!G{row}
Body: { values: [["MATCHED"]] }

// Upload file to package folder
POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable
Body: { name: <filename>, parents: [<package_folder_id>] }

// Output: file metadata returned after upload
file.id, file.name, file.mimeType, file.webViewLink, file.createdTime

Posts exception alerts to the bookkeeper when receipts cannot be auto-matched, and sends a package-ready notification to the finance manager when Agent 3 completes assembly. Used by Agents 2 and 3.

// Post exception alert
POST https://slack.com/api/chat.postMessage
Headers: Authorization: Bearer {slack_bot_token}
Body: {
  channel: "{exception_channel_id}",
  blocks: [
    { type: "header", text: { type: "plain_text", text: "Receipt exceptions: {period_label}" } },
    { type: "section", text: { type: "mrkdwn",
        text: "*{exception_count}* items require manual review.\n<{drive_folder_link}|Open exception folder>" } }
  ],
  text: "{exception_count} receipt exceptions require manual review for {period_label}."
}

// Post package-ready notification
Body: {
  channel: "{finance_ops_channel_id}",
  text: "Tax package for {period_label} is ready for sign-off. DocuSign request sent to {approver_name}."
}

Dispatches the sign-off envelope to the business owner or director for final approval on the assembled tax package. Used by Agent 3 (Package Builder and Dispatcher).

// Obtain JWT access token
POST https://account.docusign.com/oauth/token
Body: { grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer", assertion: <signed_JWT> }

// Send envelope from template
POST https://na4.docusign.net/restapi/v2.1/accounts/{account_id}/envelopes
Body: {
  templateId: "{envelope_template_id}",
  status: "sent",
  templateRoles: [{
    roleName: "Director",
    email: "{approver_email}",
    name: "{approver_name}"
  }],
  emailSubject: "Action required: sign off on {period_label} tax package",
  emailBlurb: "The tax document package for {period_label} is ready for your review and signature."
}

// Connect webhook inbound payload (envelope-completed)
{
  "event": "envelope-completed",
  "data": {
    "envelopeId": "<guid>",
    "envelopeSummary": { "status": "completed", "completedDateTime": "<ISO8601>" }
  }
}

// ── CREDENTIAL STORE CONTENTS ──────────────────────────────────────
// One entry per line: KEY_NAME = <type> | <source>

// QuickBooks Online
QBO_CLIENT_ID              = OAuth2 client ID     | Intuit Developer Portal
QBO_CLIENT_SECRET          = OAuth2 client secret | Intuit Developer Portal
QBO_REFRESH_TOKEN          = OAuth2 refresh token | Generated at consent grant
QBO_REALM_ID               = Company ID string    | QuickBooks account settings

// Hubdoc
HUBDOC_API_KEY             = Bearer token string  | Hubdoc account settings
HUBDOC_WEBHOOK_SECRET      = HMAC-SHA256 secret   | Hubdoc webhook config panel
HUBDOC_CONFIDENCE_THRESHOLD= Config float (0.85)  | Workflow config variable

// Gmail (Google Workspace service account)
GMAIL_SA_JSON              = Service account JSON | Google Cloud Console
GMAIL_IMPERSONATE_EMAIL    = String (bookkeeper@) | Workflow config variable
GMAIL_LABEL_OUTBOUND_ID    = Gmail label ID       | Gmail API (created at setup)
GMAIL_LABEL_REPLY_ID       = Gmail label ID       | Gmail API (created at setup)
GMAIL_LABEL_PROCESSED_ID   = Gmail label ID       | Gmail API (created at setup)
GMAIL_PUBSUB_TOPIC         = Pub/Sub topic name   | Google Cloud Console

// Google Drive
GDRIVE_SA_JSON             = Service account JSON | Google Cloud Console
GDRIVE_ROOT_FOLDER_ID      = Drive folder ID      | Google Drive (shared folder)
GDRIVE_CHECKLIST_SHEET_ID  = Spreadsheet ID       | Google Sheets URL

// Slack
SLACK_BOT_TOKEN            = xoxb- token string   | Slack app credentials page
SLACK_SIGNING_SECRET       = HMAC signing secret  | Slack app credentials page
SLACK_EXCEPTION_CHANNEL_ID = Channel ID string    | Slack channel settings
SLACK_FINANCE_CHANNEL_ID   = Channel ID string    | Slack channel settings
SLACK_BOOKKEEPER_USER_ID   = Slack user ID string | Slack workspace admin
SLACK_MANUAL_TRIGGER_SECRET= Shared secret string | Generated at setup

// DocuSign
DOCUSIGN_INTEGRATION_KEY   = OAuth2 client ID     | DocuSign admin console
DOCUSIGN_RSA_PRIVATE_KEY   = RSA PEM string       | DocuSign admin console
DOCUSIGN_ACCOUNT_ID        = Account GUID         | DocuSign account settings
DOCUSIGN_TEMPLATE_ID       = Envelope template ID | DocuSign template library
DOCUSIGN_CONNECT_SECRET    = HMAC-SHA256 secret   | DocuSign Connect config
DOCUSIGN_APPROVER_EMAIL    = String (approver@)   | Workflow config variable
DOCUSIGN_APPROVER_NAME     = String               | Workflow config variable

// Shared / cross-workflow
PERIOD_RUN_STORE_TABLE     = DB table / KV prefix | Orchestration platform
CURRENT_PERIOD_LABEL       = String (e.g. Q2 2024)| Updated each cycle