Integration and API Spec

Integration and API Spec

Purchase Order Management

Acts as the single intake trigger for the automation. A new form response fires a push notification or is detected via polling depending on the orchestration platform's Google Forms connector capability. The form schema must enforce required fields so the validation agent receives a consistent payload.

// Trigger payload (Google Forms response object)
response.responseId          -> internal run_id
response.answers[requester_name].textAnswers.answers[0].value
response.answers[requester_email].textAnswers.answers[0].value
response.answers[department_code].textAnswers.answers[0].value
response.answers[supplier_name].textAnswers.answers[0].value
response.answers[supplier_email].textAnswers.answers[0].value
response.answers[item_description].textAnswers.answers[0].value
response.answers[quantity].textAnswers.answers[0].value
response.answers[unit_cost].textAnswers.answers[0].value
response.answers[total_cost].textAnswers.answers[0].value
response.answers[budget_code].textAnswers.answers[0].value
response.lastSubmittedTime   -> submission_timestamp

Used by all three agents: Agent 1 sends missing-field prompts to the requester, Agent 2 sends the structured approval request with interactive buttons to the approver and a 24-hour reminder, and Agent 3 sends the final PO confirmation to the requester. Requires a custom Slack app installed in the workspace with interactive component support.

// Outbound: missing-field prompt (Agent 1)
POST https://slack.com/api/chat.postMessage
{
  channel: <requester_slack_user_id>,
  text: 'Your purchase request is missing required fields.',
  blocks: [ Section(missing_fields_list) ]
}

// Outbound: approval request (Agent 2)
POST https://slack.com/api/chat.postMessage
{
  channel: <approver_slack_user_id>,
  blocks: [ Header, Section(spend_summary), Actions(approve_btn, reject_btn) ]
}

// Inbound: interactive callback payload
payload.actions[0].action_id  -> 'approve' | 'reject'
payload.user.id               -> approver_slack_user_id
payload.message.ts            -> original_message_timestamp
payload.view.state            -> optional rejection reason

// Outbound: requester notification (Agent 3)
POST https://slack.com/api/chat.postMessage
{
  channel: <requester_slack_user_id>,
  text: 'Your PO {po_number} has been raised and sent to {supplier_name}.',
  blocks: [ Section(po_number, supplier, expected_delivery) ]
}

Used exclusively by Agent 3 to create a draft purchase order on approval. Requires a Xero connected app with OAuth 2.0. The PO is created with line items derived from the validated form data and linked to the correct account code using the budget_code field. Xero plan must support API access; confirm this before build start.

// POST https://api.xero.com/api.xro/2.0/PurchaseOrders
{
  'PurchaseOrders': [{
    'Contact': { 'Name': supplier_name },
    'Date': submission_date (ISO 8601),
    'DeliveryDate': null,
    'LineItems': [{
      'Description': item_description,
      'Quantity': quantity,
      'UnitAmount': unit_cost,
      'AccountCode': XERO_ACCOUNT_CODE_MAP[budget_code]
    }],
    'Status': 'DRAFT',
    'Reference': run_id
  }]
}

// Response: extract
PurchaseOrders[0].PurchaseOrderID  -> xero_po_id
PurchaseOrders[0].PurchaseOrderNumber -> po_number

Used by Agent 3 to send the purchase order PDF to the supplier and to monitor for a supplier confirmation reply. If no reply arrives within 48 hours, a follow-up email is sent automatically. Gmail is accessed via the same Google OAuth client as Forms and Sheets.

// Outbound: supplier PO email
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
{
  raw: base64url(
    To: supplier_email,
    From: GMAIL_SENDER_ADDRESS,
    Subject: GMAIL_PO_TEMPLATE_SUBJECT (populated),
    Body: GMAIL_PO_TEMPLATE_BODY (populated),
    Attachment: po_pdf (base64 encoded)
  )
}
// Store returned message.id as gmail_sent_message_id

// Inbound: reply detection
GET /gmail/v1/users/me/threads/{threadId}
messages[-1].payload.headers['From'] -> supplier_reply_from
messages[-1].internalDate            -> supplier_reply_timestamp
// If reply detected: cancel 48-hour follow-up, log confirmed_at to Sheets

Used by Agent 3 as the procurement register and audit log. Each approved PO appends a new row with all key fields. Finance and ops teams read this sheet directly; the automation only writes to it and never deletes rows.

// POST https://sheets.googleapis.com/v4/spreadsheets/{SHEETS_SPREADSHEET_ID}/values/{SHEETS_REGISTER_SHEET_NAME}!A:V:append
valueInputOption: 'USER_ENTERED'
insertDataOption: 'INSERT_ROWS'
values: [[
  run_id, submission_timestamp, requester_name, requester_email,
  department_code, supplier_name, supplier_email, item_description,
  quantity, unit_cost, total_cost, budget_code,
  approver_name, approver_slack_id, approved_at,
  po_number, xero_po_id, gmail_sent_message_id,
  supplier_confirmed (FALSE), confirmed_at (''),
  follow_up_sent (FALSE), notes ('')
]]

// Update on supplier confirmation:
PATCH /values/{SHEETS_REGISTER_SHEET_NAME}!S{row}:U{row}
values: [[ TRUE, confirmed_at_timestamp, FALSE ]]

# Google (shared OAuth client for Forms, Gmail, Sheets)
GOOGLE_OAUTH_CLIENT_ID          = '<from Google Cloud Console>'
GOOGLE_OAUTH_CLIENT_SECRET      = '<from Google Cloud Console>'
GOOGLE_OAUTH_REFRESH_TOKEN      = '<generated during OAuth flow>'
GMAIL_SENDER_ADDRESS            = 'ops@[YourCompany.com]'
FORM_ID                         = '<Google Forms form ID string>'
SHEETS_SPREADSHEET_ID           = '<Google Sheets spreadsheet ID string>'
SHEETS_REGISTER_SHEET_NAME      = 'Procurement Register'

# Slack
SLACK_BOT_TOKEN                 = 'xoxb-<workspace-token>'
SLACK_SIGNING_SECRET            = '<from Slack app credentials page>'

# Xero
XERO_CLIENT_ID                  = '<from Xero developer portal>'
XERO_CLIENT_SECRET              = '<from Xero developer portal>'
XERO_TENANT_ID                  = '<Xero organisation tenant ID>'
XERO_REFRESH_TOKEN              = '<stored and updated on each token refresh>'

# Configuration variables (not secrets but must not be hardcoded in nodes)
APPROVAL_THRESHOLDS_JSON        = '{
  "default": { "under_500": "<approver_email_A>", "500_to_2000": "<approver_email_B>", "over_2000": "<approver_email_C>" },
  "department_overrides": { "IT": { "under_500": "<approver_email_D>" } }
}'
XERO_ACCOUNT_CODE_MAP           = '{
  "OPS": "400", "IT": "420", "MKTG": "430", "HR": "450", "FINANCE": "460"
}'
GMAIL_PO_TEMPLATE_SUBJECT       = 'Purchase Order {{po_number}} from [YourCompany.com]'
GMAIL_PO_TEMPLATE_BODY          = '<path to template file or inline template string>'

# Webhook endpoints (stored for reference; not secrets)
AGENT1_INBOUND_WEBHOOK_URL      = 'https://<platform-host>/webhook/<agent1-id>'
AGENT2_SLACK_CALLBACK_URL       = 'https://<platform-host>/webhook/<agent2-id>'

# Gmail watch (refresh daily)
GMAIL_PUBSUB_TOPIC              = 'projects/<project-id>/topics/gmail-po-replies'