Integration and API Spec

Integration and API Spec

Supplier Onboarding Automation

Hosts the supplier intake form. The orchestration layer polls the linked Google Sheet responses tab for new rows, or consumes a Google Apps Script webhook push. Form structure and sheet column order must match the field mapping table in Section 03 exactly.

// Output (row object from Sheets API)
{
  "timestamp": "2024-05-13T09:14:22Z",
  "supplier_legal_name": "Acme Supplies Pty Ltd",
  "supplier_abn_tax_id": "51 824 753 556",
  "primary_contact_name": "Jane Doe",
  "primary_contact_email": "jane.doe@acmesupplies.com",
  "primary_contact_phone": "+61 2 9999 0000",
  "bank_bsb": "062-000",
  "bank_account_number": "12345678",
  "bank_account_name": "Acme Supplies Pty Ltd",
  "payment_terms_requested": "Net 30",
  "supplier_type": "Goods"
}

Sends all outbound emails: the initial intake form link, timed reminder emails at 48 hours and 96 hours post-invite, and exception notifications when documents are flagged incomplete. Template IDs are stored in the credential store and must not be hardcoded in workflow logic.

// Input (intake send payload)
{
  "to": "jane.doe@acmesupplies.com",
  "subject": "Action required: Supplier onboarding for Acme Supplies",
  "body_template": "GMAIL_INTAKE_TEMPLATE_ID",
  "placeholders": {
    "{{supplier_name}}": "Acme Supplies Pty Ltd",
    "{{form_url}}": "https://forms.gle/XXXXXXXXXXXXXXXX",
    "{{deadline_date"}}": "2024-05-15"
  }
}
// Output
{ "message_id": "18f3a2c9d4e1b7a0", "thread_id": "18f3a2c9d4e1b7a0", "status": "sent" }

Sends the trading agreement envelope to the supplier once the intake form is submitted. Monitors envelope status via webhook callback. Envelope template must be pre-configured in the DocuSign account with named merge fields matching intake form output.

// Input (envelope create request, simplified)
{
  "templateId": "{{DOCUSIGN_TEMPLATE_ID}}",
  "templateRoles": [{
    "roleName": "Supplier",
    "name": "Jane Doe",
    "email": "jane.doe@acmesupplies.com",
    "tabs": {
      "textTabs": [
        { "tabLabel": "supplier_legal_name", "value": "Acme Supplies Pty Ltd" },
        { "tabLabel": "supplier_abn_tax_id", "value": "51 824 753 556" }
      ]
    }
  }],
  "status": "sent"
}
// Output (Connect webhook payload, key fields)
{
  "envelopeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "completedDateTime": "2024-05-14T11:32:00Z"
}

Creates the supplier contact record in Xero once the finance lead approves compliance. Contact is created with bank account details, payment terms, and tax ID sourced directly from the intake form response. No data is keyed manually.

// Input (POST /api.xro/2.0/Contacts payload)
{
  "Contacts": [{
    "Name": "Acme Supplies Pty Ltd",
    "ContactStatus": "ACTIVE",
    "IsSupplier": true,
    "TaxNumber": "51824753556",
    "PaymentTerms": { "Bills": { "Day": 30, "Type": "DAYSAFTERBILLDATE" } },
    "ContactPersons": [{
      "FirstName": "Jane",
      "LastName": "Doe",
      "EmailAddress": "jane.doe@acmesupplies.com",
      "IncludeInEmails": true
    }],
    "BankAccountDetails": "062-000 12345678"
  }]
}
// Output (key fields from Xero response)
{
  "ContactID": "xero-contact-uuid-001",
  "Name": "Acme Supplies Pty Ltd",
  "ContactStatus": "ACTIVE"
}

Creates a matching supplier contact in HubSpot immediately after the Xero record is confirmed. The contact is tagged as an active supplier using a custom property. The Xero Contact ID is stored as a custom property to maintain cross-system traceability.

// Input (POST /crm/v3/objects/contacts payload)
{
  "properties": {
    "firstname": "Jane",
    "lastname": "Doe",
    "email": "jane.doe@acmesupplies.com",
    "phone": "+61 2 9999 0000",
    "company": "Acme Supplies Pty Ltd",
    "lifecyclestage": "other",
    "supplier_status": "active",
    "xero_contact_id": "xero-contact-uuid-001",
    "supplier_type": "Goods",
    "abn_tax_id": "51824753556",
    "payment_terms": "Net 30"
  }
}
// Output (key fields)
{
  "id": "hubspot-contact-id-002",
  "properties": { "supplier_status": "active", "xero_contact_id": "xero-contact-uuid-001" }
}

Used by Agent 2 (Document Review Agent) to post the compliance routing alert and sign-off request to the finance lead, and by Agent 3 (Supplier Activation Agent) to post the final activation confirmation to the operations channel. Slash commands or interactive message buttons can be used for the finance lead's approval action.

// Input (compliance routing message payload to finance lead)
{
  "channel": "{{SLACK_FINANCE_CHANNEL_ID}}",
  "text": "Supplier compliance review required: Acme Supplies Pty Ltd",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn", "text": "*Supplier:* Acme Supplies Pty Ltd\n*ABN:* 51 824 753 556\n*Documents received:* Certificate of Insurance, NDA, Tax Form\n*Gaps:* None" } },
    { "type": "actions", "elements": [
      { "type": "button", "text": { "type": "plain_text", "text": "Approve" }, "value": "approve", "action_id": "supplier_approve" },
      { "type": "button", "text": { "type": "plain_text", "text": "Request Changes" }, "value": "request_changes", "action_id": "supplier_reject" }
    ]}
  ]
}
// Inbound interactive payload (approval action, key fields)
{
  "type": "block_actions",
  "actions": [{ "action_id": "supplier_approve", "value": "approve" }],
  "user": { "id": "U0FINANCE01", "name": "tom.bassett" }
}

// Credential store contents (all values stored as encrypted env vars)
// Google / Gmail / Forms
GOOGLE_CLIENT_ID=<oauth2_client_id>
GOOGLE_CLIENT_SECRET=<oauth2_client_secret>
GOOGLE_REFRESH_TOKEN=<oauth2_refresh_token>
GOOGLE_FORMS_FORM_ID=<forms_form_id>
GOOGLE_FORMS_SHEET_ID=<linked_sheet_id>
GOOGLE_FORMS_PUBLIC_URL=https://forms.gle/<form_hash>
GMAIL_SENDER_ADDRESS=onboarding@[YourCompany.com]
GMAIL_INTAKE_TEMPLATE_SUBJECT=Action required: Supplier onboarding
GMAIL_REMINDER_TEMPLATE_SUBJECT=Reminder: Supplier form outstanding
GFORMS_WEBHOOK_SECRET=<shared_secret_for_apps_script_push>

// DocuSign
DOCUSIGN_INTEGRATION_KEY=<docusign_app_integration_key>
DOCUSIGN_PRIVATE_KEY_BASE64=<base64_encoded_rsa_private_key>
DOCUSIGN_ACCOUNT_ID=<docusign_account_uuid>
DOCUSIGN_IMPERSONATION_USER_ID=<docusign_user_uuid>
DOCUSIGN_TEMPLATE_ID=<envelope_template_uuid>
DOCUSIGN_BASE_URL=https://na3.docusign.net/restapi
DOCUSIGN_CONNECT_HMAC_KEY=<connect_webhook_hmac_key>

// Xero
XERO_CLIENT_ID=<xero_app_client_id>
XERO_CLIENT_SECRET=<xero_app_client_secret>
XERO_REFRESH_TOKEN=<xero_oauth2_refresh_token>
XERO_TENANT_ID=<xero_organisation_uuid>
XERO_DEFAULT_PAYMENT_TERMS=30
XERO_ACCOUNT_CODE_PURCHASES=300

// HubSpot
HUBSPOT_PRIVATE_APP_TOKEN=pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

// Slack
SLACK_BOT_TOKEN=xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx
SLACK_SIGNING_SECRET=<slack_app_signing_secret>
SLACK_FINANCE_CHANNEL_ID=C01FINANCE01
SLACK_OPS_CHANNEL_ID=C01OPSXXX01