Integration and API Spec

Integration and API Spec

Time Tracking and Billable Hours

Primary source of job records, work items, and time entries. The Time Capture Agent reads open time entries and work items; the Reconciliation Agent writes reconciled hours back and marks work items as ready to bill.

// Input (Time Capture Agent)
GET /timesheets?period=current&status=draft
GET /work?assignee={user_id}&status=open
// Output (Reconciliation Agent)
PATCH /time_entries/{id} { "status": "approved", "billable": true }
PATCH /work/{id} { "billing_status": "ready_to_bill" }

Billing export destination. The Reconciliation Agent pushes approved time entries as invoice line items against the matched Xero contact and tracking category.

// Input (Reconciliation Agent)
POST /Invoices
{
  "Type": "ACCREC",
  "Contact": { "ContactID": "{xero_contact_id}" },
  "Status": "DRAFT",
  "LineItems": [
    {
      "Description": "{job_name} - {period}",
      "Quantity": {total_hours},
      "UnitAmount": {rate},
      "TrackingCategories": [{ "TrackingCategoryID": "{category_id}" }]
    }
  ]
}
// Output
InvoiceID, InvoiceNumber, Status: DRAFT

Delivers targeted gap nudges to individual team members. The Gap Chaser Agent sends a direct message only to users whose timesheets have missing or thin entries, citing the specific gaps.

// Input (Gap Chaser Agent)
POST /chat.postMessage
{
  "channel": "{user_slack_id}",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn",
      "text": "*Timesheet gaps detected for {period}*\nMissing: {gap_dates}" } },
    { "type": "context", "elements": [
      { "type": "mrkdwn", "text": "Please update by {deadline}" }
    ]}
  ]
}
// Output
ts (message timestamp), channel, ok: true

Email fallback channel for gap nudges when a team member cannot be reached via Slack or when the firm prefers email as the primary nudge channel.

// Input (Gap Chaser Agent - email fallback)
POST /users/me/messages/send
{
  "raw": "<base64url encoded RFC2822 message>"
}
// Decoded message headers
To: {recipient_email}
Subject: Timesheet gaps for {period} - action needed
Content-Type: text/plain
Body: Missing entries on {gap_dates}. Please update by {deadline}.
// Output
id (Gmail message ID), threadId, labelIds: [SENT]

Orchestration and monitoring layer. Manages workflow execution, schedules periodic triggers, logs run state, and exposes a webhook for inbound events. All agents execute within this runtime.

// Scheduled trigger (period close)
POST /workflows/time-capture-agent/trigger
{ "payload": { "period": "2024-W08", "close_date": "2024-02-23" } }
// Run status check
GET /runs/{run_id}
// Response
{ "run_id": "run_abc123", "status": "completed", "steps_completed": 7,
  "errors": [], "duration_ms": 4210 }

// n8n Credential Store - required entries

// 1. Karbon API Key
Credential name : karbon_api_key
Type            : Header Auth
Header name     : Authorization
Header value    : Bearer <KARBON_API_KEY>

// 2. Xero OAuth 2.0
Credential name : xero_oauth2
Type            : OAuth2 (PKCE)
Client ID       : <XERO_CLIENT_ID>
Client Secret   : <XERO_CLIENT_SECRET>
Auth URL        : https://login.xero.com/identity/connect/authorize
Token URL       : https://identity.xero.com/connect/token
Scopes          : accounting.transactions accounting.contacts.read accounting.settings.read
Tenant ID       : <XERO_TENANT_ID>  // retrieved post-auth from /connections

// 3. Slack Bot Token
Credential name : slack_bot_token
Type            : Header Auth
Header name     : Authorization
Header value    : Bearer <SLACK_BOT_TOKEN>  // xoxb- prefix

// 4. Gmail OAuth 2.0
Credential name : gmail_oauth2
Type            : OAuth2
Client ID       : <GOOGLE_CLIENT_ID>
Client Secret   : <GOOGLE_CLIENT_SECRET>
Auth URL        : https://accounts.google.com/o/oauth2/auth
Token URL       : https://oauth2.googleapis.com/token
Scopes          : https://www.googleapis.com/auth/gmail.send

// 5. FullSpec Automation API Key
Credential name : fullspec_api_key
Type            : Header Auth
Header name     : X-FullSpec-Key
Header value    : <FULLSPEC_API_KEY>