Integration and API Spec

Integration and API Spec

Contract Generation and E-sign

Provides the deal trigger event and deal property payload for Agent 1. Receives the signed PDF attachment and contract status property update from Agent 3. All access is via the HubSpot Private App token model.

// Trigger payload (webhook POST)
{ "objectId": "<deal_id>", "propertyName": "dealstage", "propertyValue": "<stage_id>" }

// Secondary read (GET /crm/v3/objects/deals/{dealId})
Properties fetched: dealname, amount, closedate, deal_type, customer_name,
  customer_email, customer_address, product_line, payment_terms, contract_type

// Write back (PATCH /crm/v3/objects/deals/{dealId})
{ "properties": { "contract_status": "Signed", "hs_file_upload": "<signed_pdf_url>" } }

Stores the library of contract templates and receives the merged output document. Agent 1 reads templates and writes the populated draft. A dedicated shared drive folder structure separates templates from outputs.

// Template read
GET https://docs.googleapis.com/v1/documents/{templateDocId}

// Merge (placeholder substitution)
POST https://docs.googleapis.com/v1/documents/{copiedDocId}:batchUpdate
{ "requests": [ { "replaceAllText": { "containsText": { "text": "{{customer_name}}" },
    "replaceText": "<deal.customer_name>" } } ] }

// Export merged doc as PDF
GET https://www.googleapis.com/drive/v3/files/{docId}/export?mimeType=application/pdf

// Output stored at
GDRIVE_OUTPUT_FOLDER_ID / {dealname}_{closedate}_draft.pdf

Receives the merged PDF from Google Drive and creates a signature envelope for the customer. Agent 2 polls envelope status to trigger follow-up logic. Agent 3 responds to the envelope completed event to retrieve the signed PDF.

// Create envelope
POST https://{DOCUSIGN_BASE_URL}/restapi/v2.1/accounts/{DOCUSIGN_ACCOUNT_ID}/envelopes
{ "emailSubject": "Your contract is ready to sign",
  "documents": [{ "documentBase64": "<pdf_base64>", "name": "{dealname}_contract.pdf", "documentId": "1" }],
  "recipients": { "signers": [{ "email": "{customer_email}",
    "name": "{customer_name}", "recipientId": "1",
    "tabs": { "signHereTabs": [{ "anchorString": "{DOCUSIGN_TAB_ANCHOR_MAP[contract_type]}",
    "anchorUnits": "pixels" }] } }] },
  "status": "sent" }

// Poll or receive webhook for status
GET /accounts/{accountId}/envelopes/{envelopeId}
-> { "status": "completed" | "sent" | "delivered" | "voided" | "declined" }

// Download signed PDF
GET /accounts/{accountId}/envelopes/{envelopeId}/documents/combined

Delivers timed follow-up emails to the customer if the DocuSign envelope has not been opened or signed within defined windows. Agent 2 controls this step. Emails are sent from the authenticated sales user account, not a generic system address.

// Send follow-up (48h)
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
Authorization: Bearer {access_token}
{ "raw": "<base64url-encoded RFC 2822 message>" }

// Message headers
To: {customer_email}
From: {GMAIL_SENDER_ADDRESS}
Subject: Reminder: Your contract is waiting for your signature
Body: GMAIL_FOLLOWUP_48H_TEMPLATE rendered with {{customer_name}}, {{dealname}}, {{docusign_envelope_link}}

Handles two distinct interactions: the manager review prompt posted by Agent 1 (with an approve action), and the post-signature completion notification posted by Agent 3 to the sales, finance, and delivery channels.

// Post manager review prompt (Agent 1 output)
POST https://slack.com/api/chat.postMessage
{ "channel": "{SLACK_REVIEW_CHANNEL_ID}",
  "blocks": [ { "type": "section", "text": { "type": "mrkdwn",
    "text": "*Contract ready for review*\n*Deal:* {dealname} | *Value:* ${amount}\n*Customer:* {customer_name}\n<{gdrive_preview_link}|Open contract draft>" } },
  { "type": "actions", "elements": [
    { "type": "button", "text": { "type": "plain_text", "text": "Approve" },
      "style": "primary", "action_id": "manager_approve",
      "value": "{deal_id}:{gdrive_doc_id}" },
    { "type": "button", "text": { "type": "plain_text", "text": "Request Changes" },
      "style": "danger", "action_id": "manager_request_changes",
      "value": "{deal_id}:{gdrive_doc_id}" } ] } ] }

// Post completion notification (Agent 3 output)
POST https://slack.com/api/chat.postMessage
{ "channel": "{SLACK_SALES_CHANNEL_ID}",
  "text": ":white_check_mark: Contract signed: {dealname} ({customer_name}). Signed PDF attached to HubSpot deal." }

# Credential store entries (automation platform secrets vault)
# Do NOT hardcode any of these values in workflow logic or config fields.

# HubSpot
HUBSPOT_PRIVATE_APP_TOKEN       = "pat-na1-xxxxxxxxxxxxxxxxxxxx"
HUBSPOT_WEBHOOK_SECRET          = "<hmac secret from private app settings>"
HUBSPOT_PIPELINE_ID             = "<pipeline_id from GET /crm/v3/pipelines/deals>"
HUBSPOT_CLOSEDWON_STAGE_ID      = "<stage_id for Closed Won>"

# Google Drive / Docs
GOOGLE_SERVICE_ACCOUNT_JSON     = "<full service account JSON key>"
GDRIVE_TEMPLATES_FOLDER_ID      = "<Google Drive folder ID>"
GDRIVE_OUTPUT_FOLDER_ID         = "<Google Drive folder ID>"
GDRIVE_TEMPLATE_MAP             = '{"standard":"<file_id>","enterprise":"<file_id>","nda":"<file_id>"}'

# Gmail
GMAIL_OAUTH_REFRESH_TOKEN       = "<OAuth refresh token>"
GMAIL_SENDER_ADDRESS            = "contracts@[YourCompany.com]"
GMAIL_FOLLOWUP_48H_TEMPLATE     = "<template string or file reference>"
GMAIL_FOLLOWUP_96H_TEMPLATE     = "<template string or file reference>"

# DocuSign
DOCUSIGN_INTEGRATION_KEY        = "<integration key / client ID>"
DOCUSIGN_RSA_PRIVATE_KEY        = "<RSA private key PEM string>"
DOCUSIGN_USER_ID                = "<impersonated user GUID>"
DOCUSIGN_ACCOUNT_ID             = "<production account ID>"
DOCUSIGN_BASE_URL               = "https://na4.docusign.net"
DOCUSIGN_SANDBOX_ACCOUNT_ID     = "<developer sandbox account ID>"
DOCUSIGN_CONNECT_HMAC_KEY       = "<Connect HMAC key from DocuSign console>"
DOCUSIGN_CONNECT_ENDPOINT       = "https://<platform-inbound-url>/docusign/events"
DOCUSIGN_TAB_ANCHOR_MAP         = '{"standard":"[Signature]","enterprise":"[SignHere]","nda":"[Sign]"}'

# Slack
SLACK_BOT_TOKEN                 = "xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx"
SLACK_SIGNING_SECRET            = "<signing secret from Slack App settings>"
SLACK_INTERACTIVITY_ENDPOINT    = "https://<platform-inbound-url>/slack/actions"
SLACK_REVIEW_CHANNEL_ID         = "C0XXXXXXXXX"
SLACK_SALES_CHANNEL_ID          = "C0XXXXXXXXX"
SLACK_FINANCE_CHANNEL_ID        = "C0XXXXXXXXX"
SLACK_DELIVERY_CHANNEL_ID       = "C0XXXXXXXXX"
SLACK_OPS_CHANNEL_ID            = "C0XXXXXXXXX"