Integration and API Spec

Integration and API Spec

Fulfilment Performance Reporting

Used by the Data Collection Agent (Agent 1) to retrieve all orders placed within the closed reporting period. The automation connects via a Shopify custom app with read-only access. No write operations are performed against Shopify at any point.

// Endpoint
GET https://{SHOPIFY_SHOP_DOMAIN}/admin/api/2024-01/orders.json
  ?status=any
  &created_at_min={period_start_iso8601}
  &created_at_max={period_end_iso8601}
  &limit=250
  &fields=id,name,created_at,fulfillment_status,fulfilled_at,line_items,financial_status

// Auth header
X-Shopify-Access-Token: {SHOPIFY_ACCESS_TOKEN}

// Output (per order record)
{ id, name, created_at, fulfillment_status, fulfilled_at, line_items[], financial_status }

Used by the Data Collection Agent (Agent 1) to retrieve shipment records for the same reporting window. ShipStation uses API key and secret pairs transmitted as a Base64-encoded Basic Auth header. No write operations are performed.

// Endpoint
GET https://ssapi.shipstation.com/shipments
  ?shipDateStart={period_start_yyyy-mm-dd}
  &shipDateEnd={period_end_yyyy-mm-dd}
  &voided=False
  &pageSize=500
  &page=1

// Auth header
Authorization: Basic {Base64(SHIPSTATION_API_KEY:SHIPSTATION_API_SECRET)}

// Output (per shipment record)
{ shipmentId, orderId, orderNumber, shipDate, deliveryDate, carrierCode,
  trackingNumber, shipmentStatusCode, voided }

Used by the Data Collection Agent (Agent 1) to retrieve credit notes and returns transactions issued during the reporting period. Xero uses OAuth 2.0 with PKCE. Tokens expire after 30 minutes and must be refreshed using the refresh token stored in the credential store.

// Endpoint
GET https://api.xero.com/api.xro/2.0/CreditNotes
  ?where=Date>={period_start_iso8601}&&Date<={period_end_iso8601}
  &&Status=="AUTHORISED"

// Auth headers
Authorization: Bearer {XERO_ACCESS_TOKEN}
Xero-tenant-id: {XERO_TENANT_ID}
Accept: application/json

// Output (per credit note record)
{ CreditNoteID, CreditNoteNumber, Date, Status, SubTotal, TotalTax,
  Total, CurrencyCode, Contact.Name, LineItems[] }

Used by all three agents. Agent 1 writes raw data to the staging sheet. Agent 2 reads staged data, runs KPI formulas, and writes calculated results. Agent 3 reads the final KPI row and writes a new row to the historical log sheet. All access is via the Google Sheets API v4 using a service account.

// Write raw data (Agent 1)
POST https://sheets.googleapis.com/v4/spreadsheets/{SHEETS_SPREADSHEET_ID}/values
     /raw_data!A2:Z{n}:clear
POST https://sheets.googleapis.com/v4/spreadsheets/{SHEETS_SPREADSHEET_ID}/values
     /raw_data!A2:Z{n}?valueInputOption=USER_ENTERED

// Read KPI results (Agent 3)
GET  https://sheets.googleapis.com/v4/spreadsheets/{SHEETS_SPREADSHEET_ID}/values
     /kpi_results!A2:J2

// Append to performance log (Agent 3)
POST https://sheets.googleapis.com/v4/spreadsheets/{SHEETS_SPREADSHEET_ID}/values
     /performance_log!A:J:append?valueInputOption=USER_ENTERED&insertDataOption=INSERT_ROWS

Used by the Report Distribution Agent (Agent 3) to post a formatted KPI summary to the designated operations channel. The automation uses a Slack Bot Token obtained from a registered Slack app with the chat:write scope.

// Endpoint
POST https://hooks.slack.com/services/{SLACK_WEBHOOK_PATH}

// Payload
{
  "text": "Fulfilment KPI Report: {period_label}",
  "blocks": [
    { "type": "header", "text": { "type": "plain_text", "text": "Fulfilment KPIs - {period_label}" } },
    { "type": "section", "text": { "type": "mrkdwn", "text": "{kpi_summary_markdown}" } },
    { "type": "section", "text": { "type": "mrkdwn", "text": "{commentary_text}" } },
    { "type": "actions", "elements": [{ "type": "button", "text": "View Full Report", "url": "{SHEETS_REPORT_URL}" }] }
  ]
}

Used by the Report Distribution Agent (Agent 3) to email the full report link and PDF export to the configured recipient list. Access is via the Gmail API using a Google service account with domain-wide delegation, or a delegated user account.

// Endpoint
POST https://gmail.googleapis.com/gmail/v1/users/{GMAIL_SENDER_ADDRESS}/messages/send

// Auth header
Authorization: Bearer {GMAIL_ACCESS_TOKEN}

// MIME payload (Base64url-encoded)
From: {GMAIL_SENDER_ADDRESS}
To: {GMAIL_RECIPIENT_LIST}
Subject: Fulfilment Performance Report - {period_label}
Content-Type: multipart/mixed

-- body part: text/html (report summary + Sheets link)
-- attachment part: application/pdf (Base64-encoded PDF export)

// Credential store contents (all values injected at runtime as environment variables)
// Do NOT hardcode any of these values in workflow step configuration.

// Shopify
SHOPIFY_ACCESS_TOKEN        = '<custom-app-admin-api-token>'
SHOPIFY_SHOP_DOMAIN         = '<yourstore.myshopify.com>'

// ShipStation
SHIPSTATION_API_KEY         = '<shipstation-api-key>'
SHIPSTATION_API_SECRET      = '<shipstation-api-secret>'

// Xero
XERO_CLIENT_ID              = '<xero-connected-app-client-id>'
XERO_CLIENT_SECRET          = '<xero-connected-app-client-secret>'
XERO_ACCESS_TOKEN           = '<current-access-token>'          // refreshed every run
XERO_REFRESH_TOKEN          = '<current-refresh-token>'          // rotated on each use
XERO_TENANT_ID              = '<xero-organisation-tenant-id>'

// Google (Sheets + Gmail, shared service account)
GOOGLE_SERVICE_ACCOUNT_JSON = '<full-json-key-file-content>'
SHEETS_SPREADSHEET_ID       = '<google-sheets-document-id>'
SHEETS_REPORT_URL           = '<shareable-link-to-report-sheet>'
GMAIL_SENDER_ADDRESS        = '<sender@yourdomain.com>'
GMAIL_RECIPIENT_LIST        = '<comma-separated-recipient-emails>'

// Slack
SLACK_BOT_TOKEN             = '<xoxb-slack-bot-token>'
SLACK_WEBHOOK_URL           = '<https://hooks.slack.com/services/...>'
SLACK_CHANNEL_ID            = '<C01234ABCDE>'

// Orchestration config (non-secret but stored centrally)
REPORTING_SCHEDULE_CRON     = '0 7 * * 1'                       // every Monday 07:00
MONTHLY_SCHEDULE_CRON       = '0 7 1 * *'                       // 1st of month 07:00
APPROVAL_TIMEOUT_HOURS      = '4'
KPI_THRESHOLDS_TAB_NAME     = 'thresholds'