Integration and API Spec

Integration and API Spec

Affiliate Programme Management

Provides conversion events and affiliate profile data to Agent 1. The connection is the entry point for the entire automation. Webhook delivery is preferred; polling is the fallback for plans that do not expose webhook endpoints reliably.

// Inbound webhook payload (trimmed)
{
  "event": "conversion_approved",
  "conversion": {
    "id": "conv_abc123",
    "affiliate": { "id": "aff_001", "email": "partner@example.com" },
    "amount": 250.00,
    "currency": "USD",
    "commission": 25.00,
    "created_at": "2024-05-01T09:14:22Z",
    "status": "approved"
  }
}

Serves as the commission log and audit trail (written by Agent 1) and as the weekly data source for the performance digest (read by Agent 3). A single spreadsheet with two named tabs is required.

// Row written to CommissionLog tab by Agent 1
[
  "conv_abc123",       // A: conversion_id
  "aff_001",           // B: affiliate_id
  "partner@example.com", // C: affiliate_email
  250.00,              // D: sale_amount_usd
  10,                  // E: commission_rate_pct
  25.00,               // F: commission_amount_usd
  "pending_payout",   // G: status
  "",                 // H: hubspot_deal_id (populated by Agent 2)
  "",                 // I: xero_bill_id (populated by Agent 2)
  "2024-05-01T09:15:00Z" // J: logged_at
]

Receives deal creation and update requests from Agent 2 to record affiliate attribution against each validated conversion. Uses the private app token auth model introduced in HubSpot's v3 API.

// POST /crm/v3/objects/deals  (create deal)
{
  "properties": {
    "dealname": "Affiliate Commission: aff_001 - conv_abc123",
    "pipeline": "{HUBSPOT_PIPELINE_ID}",
    "dealstage": "{HUBSPOT_STAGE_ID_COMMISSION_LOGGED}",
    "amount": 25.00,
    "affiliate_id": "aff_001",
    "commission_amount": 25.00,
    "conversion_id": "conv_abc123",
    "affiliate_tier": "Silver"
  }
}

Receives bill creation requests from Agent 2 at each monthly payout cycle close. One bill is raised per affiliate with the total commission owed for the month. Finance approves and releases payment manually: the automation does not process bank transfers.

// POST /Bills  (create draft bill for one affiliate)
{
  "Type": "ACCPAY",
  "Contact": { "ContactID": "{xero_contact_id}" },
  "DueDateString": "2024-05-10",
  "Status": "DRAFT",
  "LineAmountTypes": "Exclusive",
  "LineItems": [
    {
      "Description": "Affiliate commission - May 2024 - aff_001",
      "Quantity": 1,
      "UnitAmount": 125.00,
      "AccountCode": "{XERO_ACCOUNT_CODE_COMMISSIONS}"
    }
  ],
  "Reference": "AFFPAY-2024-05-aff_001"
}

Used by Agent 2 to send payment confirmation emails to affiliates after Xero bill approval, and to send the onboarding sequence when a new affiliate is approved in Tapfiliate. All emails are sent from the authorised programme mailbox.

// Gmail API send payload (payment confirmation)
{
  "to": "partner@example.com",
  "from": "{GMAIL_SENDER_ADDRESS}",
  "subject": "Your affiliate commission payment: $125.00",
  "body_html": "<p>Hi {{affiliate_name}}, ...</p>",  // rendered from TEMPLATE_PAYMENT_CONFIRMATION
  "reply_to": "{GMAIL_SENDER_ADDRESS}"
}

Receives a weekly performance digest post from Agent 3 every Monday morning. Also receives error alert messages from any agent when a failure requires human attention.

// chat.postMessage payload (weekly digest)
{
  "channel": "{SLACK_DIGEST_CHANNEL_ID}",
  "blocks": [
    { "type": "header", "text": { "type": "plain_text", "text": "Affiliate Performance: w/e 5 May 2024" } },
    { "type": "section", "fields": [
      { "type": "mrkdwn", "text": "*Total conversions:* 31" },
      { "type": "mrkdwn", "text": "*Total commission accrued:* $875.00" },
      { "type": "mrkdwn", "text": "*Top affiliate:* partner@example.com (8 conversions)" }
    ]},
    { "type": "divider" }
  ]
}

// Credential store contents (all values are secret references, not literal values)

TAPFILIATE_API_KEY              = <secret>   // Tapfiliate API key (Administrator role)
TAPFILIATE_WEBHOOK_SECRET       = <secret>   // HMAC-SHA256 shared secret for webhook validation

GSHEETS_SERVICE_ACCOUNT_JSON    = <secret>   // Google service account JSON key (base64 encoded)
GSHEETS_SPREADSHEET_ID          = <secret>   // Target spreadsheet ID (not URL, not hardcoded)

HUBSPOT_PRIVATE_APP_TOKEN       = <secret>   // HubSpot private app Bearer token
HUBSPOT_PIPELINE_ID             = <config>   // Affiliate Conversions pipeline ID
HUBSPOT_STAGE_ID_COMMISSION_LOGGED = <config> // Deal stage: Commission Logged
HUBSPOT_STAGE_ID_PAID           = <config>   // Deal stage: Paid

XERO_CLIENT_ID                  = <secret>   // Xero OAuth app client ID
XERO_CLIENT_SECRET              = <secret>   // Xero OAuth app client secret
XERO_ACCESS_TOKEN               = <secret>   // Short-lived access token (refreshed automatically)
XERO_REFRESH_TOKEN              = <secret>   // Long-lived refresh token
XERO_TENANT_ID                  = <config>   // Xero organisation tenant ID
XERO_ACCOUNT_CODE_COMMISSIONS   = <config>   // Xero chart of accounts code for commission expense
XERO_WEBHOOK_KEY                = <secret>   // HMAC key for Xero webhook signature validation

GMAIL_CLIENT_ID                 = <secret>   // Gmail OAuth client ID
GMAIL_CLIENT_SECRET             = <secret>   // Gmail OAuth client secret
GMAIL_REFRESH_TOKEN             = <secret>   // Gmail OAuth refresh token for sender mailbox
GMAIL_SENDER_ADDRESS            = <config>   // From address for all outbound programme emails
TEMPLATE_PAYMENT_CONFIRMATION   = <config>   // HTML email template (payment confirmation)
TEMPLATE_ONBOARDING_WELCOME     = <config>   // HTML email template (affiliate onboarding)

SLACK_BOT_TOKEN                 = <secret>   // Slack bot OAuth token (xoxb-...)
SLACK_DIGEST_CHANNEL_ID         = <config>   // Slack channel ID for weekly digest
SLACK_ALERTS_CHANNEL_ID         = <config>   // Slack channel ID for automation error alerts