Integration and API Spec

Integration and API Spec

Pricing Approval Workflow

Used by Agent 1 (Request Intake Agent) as the workflow trigger source, and by Agent 3 (CRM Update Agent) to write the final decision back to the deal record. A private app token is preferred over legacy API keys; the token is scoped to the minimum set of CRM objects required.

// Trigger payload (inbound webhook from HubSpot)
X-HubSpot-Signature-v3: <hmac-sha256>
{
  "objectId": "<deal_id>",
  "propertyName": "pricing_exception_status",
  "propertyValue": "Requested",
  "changeSource": "CRM_UI",
  "eventId": "<uuid>"
}
// Agent 3 write-back (PATCH /crm/v3/objects/deals/{deal_id})
{
  "properties": {
    "approval_status": "Approved",
    "approved_price": "12500.00",
    "approver_name": "Renata Solano",
    "approval_date": "2025-07-05",
    "approval_conditions": "Valid for 30 days only"
  }
}

Used by Agent 1 (Request Intake Agent) to write structured approval log entries, and read by Agent 2 (Approval Routing Agent) to pick up new rows for routing. Acts as the inter-agent handoff datastore. A service account with a JSON key is the recommended auth method to avoid user-session expiry interrupting scheduled polling.

// Agent 1 append (POST spreadsheets/{id}/values/{range}:append)
{
  "range": "ApprovalLog!A:Q",
  "values": [[
    "LOG-0042", "12345678", "Acme Corp - Enterprise",
    "tom.rep@company.com", 18, 12500, "Competitive pressure",
    68000, "tier2", "Pending", "U04ABCD1234",
    "finance@company.com", "", "", "", "", "false"
  ]]
}
// Agent 2 poll read (GET spreadsheets/{id}/values/{range})
Filter: col J (routing_status) == 'Pending'

Used by Agent 2 (Approval Routing Agent) to send interactive one-click approval messages to the sales manager, and by Agent 3 (CRM Update Agent) to notify the sales rep of the final decision. A Slack app with bot token and interactive components enabled is required. The app must be installed by a workspace admin.

// Agent 2 outbound approval message (chat.postMessage)
{
  "channel": "U04ABCD1234",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn",
      "text": "*Pricing Exception Request*\nDeal: Acme Corp - Enterprise\nDiscount: 18% ($12,500)\nReason: Competitive pressure" } },
    { "type": "actions", "elements": [
      { "type": "button", "text": { "type": "plain_text", "text": "Approve" },
        "style": "primary", "action_id": "pricing_approve", "value": "LOG-0042" },
      { "type": "button", "text": { "type": "plain_text", "text": "Deny" },
        "style": "danger", "action_id": "pricing_deny", "value": "LOG-0042" }
    ]}
  ]
}
// Inbound interactive payload validation
X-Slack-Signature: v0=<hmac-sha256>
payload.actions[0].action_id -> 'pricing_approve' | 'pricing_deny'
payload.actions[0].value -> log_id (e.g. 'LOG-0042')

Used by Agent 2 (Approval Routing Agent) exclusively for finance escalation emails when the requested discount exceeds the manager-only threshold. Sends a structured email to the finance approver with deal context and an approval link. Auth is via OAuth 2.0 using a dedicated sender Google account.

// Agent 2 outbound finance escalation (POST /gmail/v1/users/me/messages/send)
{
  "raw": "<base64url-encoded RFC 2822 message>",
  // Decoded headers:
  "From": "pricing-approvals@[YourCompany.com]",
  "To": "finance@[YourCompany.com]",
  "Cc": "sales.manager@[YourCompany.com]",
  "Subject": "Finance Approval Required: Acme Corp - 18% Discount",
  // Body includes approve_link and deny_link with HMAC tokens
  "approve_link": "https://hooks.platform.internal/approve?log_id=LOG-0042&token=<hmac>",
  "deny_link":    "https://hooks.platform.internal/deny?log_id=LOG-0042&token=<hmac>"
}

Used downstream after the CRM Update Agent records the final approval. DocuSign is not directly orchestrated by any of the three agents; it is referenced here for completeness and to document the integration credentials required if the automation is extended to trigger quote sending automatically in a future phase.

// Future extension: POST /restapi/v2.1/accounts/{accountId}/envelopes
{
  "templateId": "<DOCUSIGN_QUOTE_TEMPLATE_ID>",
  "templateRoles": [{
    "roleName": "Signer1",
    "email": "prospect@client.com",
    "name": "Prospect Name",
    "tabs": {
      "textTabs": [
        { "tabLabel": "ApprovedPrice", "value": "12500" },
        { "tabLabel": "DealName", "value": "Acme Corp - Enterprise" }
      ]
    }
  }],
  "status": "sent"
}

// Credential store contents (pricing-approval-prod namespace)

// HubSpot
HUBSPOT_PRIVATE_APP_TOKEN        = "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
HUBSPOT_CLIENT_SECRET            = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
HUBSPOT_PIPELINE_ID              = "default"
HUBSPOT_STAGE_ID_APPROVAL_PENDING = "12345678"
HUBSPOT_DEAL_PROPERTY_MAP        = "{\"requested_discount_pct\":\"requested_discount_pct\", ...}"

// Google Sheets
GSHEETS_SERVICE_ACCOUNT_JSON     = "{...full service account JSON key...}"
GSHEETS_LOG_SPREADSHEET_ID       = "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms"
GSHEETS_LOG_SHEET_NAME           = "ApprovalLog"

// Slack
SLACK_BOT_TOKEN                  = "xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx"
SLACK_SIGNING_SECRET             = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
SLACK_APPROVAL_CHANNEL_ID        = "C04XXXXXXXX"
SLACK_REP_NOTIFY_CHANNEL_ID      = "C04YYYYYYYYY"
SLACK_FINANCE_USER_ID            = "U04ZZZZZZZZ"
SLACK_APPROVAL_MSG_TEMPLATE      = "{...Block Kit JSON...}"
SLACK_OUTCOME_MSG_TEMPLATE       = "{...Block Kit JSON...}"

// Gmail
GMAIL_CLIENT_ID                  = "xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com"
GMAIL_CLIENT_SECRET              = "GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxx"
GMAIL_OAUTH_REFRESH_TOKEN        = "1//xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
GMAIL_SENDER_ADDRESS             = "pricing-approvals@[YourCompany.com]"
GMAIL_ESCALATION_TEMPLATE_HTML   = "<path-or-inline-HTML-template>"
GMAIL_ESCALATION_CC              = "sales.manager@[YourCompany.com]"
FINANCE_APPROVER_EMAIL           = "finance@[YourCompany.com]"

// Approval link (Gmail callback)
APPROVAL_LINK_BASE_URL           = "https://hooks.platform.internal"
APPROVAL_LINK_SECRET             = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

// DocuSign (future extension)
DOCUSIGN_INTEGRATION_KEY         = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
DOCUSIGN_RSA_PRIVATE_KEY         = "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
DOCUSIGN_USER_ID                 = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
DOCUSIGN_ACCOUNT_ID              = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
DOCUSIGN_BASE_URL                = "https://na4.docusign.net"
DOCUSIGN_QUOTE_TEMPLATE_ID       = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

// Discount tier thresholds
DISCOUNT_TIER_THRESHOLDS         = "{\"tier1_max_pct\": 10, \"tier2_max_pct\": 20, \"finance_threshold_pct\": 20}"