Integration and API Spec

Integration and API Spec

Asset and Equipment Tracking

Airtable is the single source of truth for every asset record. The orchestration layer polls the base for new or updated records on a short interval and also receives webhook events when a record is created or a status field changes. All three agents read from and write back to this base.

// Trigger payload (webhook)
{ "baseId": "appXXXXXXXXXXXXXX", "tableId": "tblXXXXXXXXXXXXXX",
  "changedFieldIds": ["fldAssetStatus", "fldDisposalFlag"],
  "createdTime": "2024-05-01T09:14:00.000Z",
  "recordId": "recXXXXXXXXXXXXXX" }
// Write-back (QR URL patch)
PATCH /v0/{baseId}/{tableId}/{recordId}
{ "fields": { "fldQRCodeURL": [{ "url": "https://qr.example.com/asset-001.png" }] } }

Called by Agent 1 (Asset Intake Agent) to generate a unique, scannable QR code for every confirmed asset record. The returned image URL is written back to the Airtable record and is also included in the Slack assignment message.

// Outbound request
POST {QR_API_BASE_URL}/generate
Headers: { "X-API-Key": "{QR_API_KEY}" }
Body: { "data": "https://[YourCompany.com]/assets/AST-00042",
        "format": "PNG", "size": 400, "errorCorrection": "M" }
// Response
{ "success": true, "url": "https://qr.example.com/AST-00042.png",
  "expiresAt": null }

Used by Agent 1 for assignment notifications and by Agent 2 for maintenance reminders, overdue loan alerts, and the monthly audit summary post. All messages are sent via a dedicated bot installed in the [YourCompany.com] workspace.

// Assignment notification
POST https://slack.com/api/chat.postMessage
{ "channel": "{assignee_slack_id}",
  "text": "Asset AST-00042 (MacBook Pro 14\" M3) has been assigned to you.",
  "blocks": [ { "type": "section", "text": { "type": "mrkdwn",
    "text": "*Asset assigned:* AST-00042\n*Label URL:* <{qr_url}|Scan or print>" } } ] }
// Overdue alert (ops manager copy)
{ "channel": "{SLACK_OPS_CHANNEL_ID}",
  "text": ":warning: Asset AST-00031 is overdue for return. Borrower: @priya.nair. Due: 2024-04-28." }

Used exclusively by Agent 2 (Maintenance Scheduler Agent) to create recurring Google Calendar events for maintenance intervals and to send email reminders where Slack delivery cannot be confirmed. Authentication uses a service account with domain-wide delegation so the agent can create events on behalf of the operations coordinator without requiring interactive login.

// Calendar event creation
POST https://www.googleapis.com/calendar/v3/calendars/{GOOGLE_CALENDAR_ID}/events
{ "summary": "Maintenance Due: AST-00042 MacBook Pro 14\" M3",
  "start": { "date": "2024-08-01" },
  "end": { "date": "2024-08-01" },
  "recurrence": ["RRULE:FREQ=MONTHLY;INTERVAL=6"],
  "reminders": { "useDefault": false,
    "overrides": [ {"method": "email", "minutes": 10080},
                    {"method": "popup", "minutes": 1440} ] } }

Used exclusively by Agent 3 (Finance Sync Agent) to create fixed-asset records when a new asset is confirmed in Airtable, and to post write-off entries when a disposal flag is set. Xero's fixed-asset API requires the asset to be linked to the correct account code and depreciation method, both of which must be confirmed with the finance team before the agent is activated.

// Create fixed-asset record
POST https://api.xero.com/assets.xro/1.0/Assets
Headers: { "Authorization": "Bearer {access_token}",
           "Xero-tenant-id": "{XERO_TENANT_ID}" }
{ "assetName": "MacBook Pro 14in M3 AST-00042",
  "assetNumber": "AST-00042",
  "purchaseDate": "2024-05-01",
  "purchasePrice": 2499.00,
  "assetStatus": "Draft",
  "bookDepreciationSetting": {
    "depreciationMethod": "StraightLine",
    "averagingMethod": "FullMonth",
    "depreciationRate": 0.25,
    "bookEffectiveDateOfChangeId": "01" } }

# Airtable
AIRTABLE_PAT=pat_xxxxxxxxxxxxxxxxxxxx
AIRTABLE_BASE_ID=appXXXXXXXXXXXXXX
AIRTABLE_ASSETS_TABLE_ID=tblXXXXXXXXXXXXXX
AIRTABLE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxx

# QR Code Generator
QR_API_KEY=qr_live_xxxxxxxxxxxxxxxxxxxx
QR_API_BASE_URL=https://api.qrcodegenerator.example.com/v2
QR_ASSET_URL_TEMPLATE=https://[YourCompany.com]/assets/

# Slack
SLACK_BOT_TOKEN=xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx
SLACK_OPS_CHANNEL_ID=C0XXXXXXXXX
SLACK_AUDIT_CHANNEL_ID=C0XXXXXXXXY

# Google Workspace
GOOGLE_SERVICE_ACCOUNT_JSON={...full service account key JSON...}
GOOGLE_DELEGATE_EMAIL=ops.coordinator@[YourCompany.com]
GOOGLE_CALENDAR_ID=xxxxxxxxxxxxxxxxxxxxxxxxxx@group.calendar.google.com

# Xero
XERO_CLIENT_ID=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XERO_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
XERO_REFRESH_TOKEN=<stored and auto-rotated on each token exchange>
XERO_TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
XERO_ASSET_ACCOUNT_CODE=1100
XERO_DEPRECIATION_METHOD=StraightLine
XERO_DEPRECIATION_RATE=0.25
XERO_CATEGORY_DEPRECIATION_MAP={"IT Hardware":0.25,"Furniture":0.10,"Vehicles":0.20}

# Orchestration platform
PLATFORM_WEBHOOK_SIGNING_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ENV=production