Integration and API Spec

Integration and API Spec

Delivery Exception Handling

ShipStation is the automation entry point. It delivers a webhook payload to the orchestration layer the moment a shipment status changes to a failed, held, or undeliverable state. A 15-minute polling fallback is required for carriers that do not push status changes reliably.

// Inbound webhook payload (key fields)
shipmentId        : string   // unique ShipStation shipment identifier
orderNumber       : string   // maps to Shopify order name (#1234)
carrierCode       : string   // e.g. 'usps', 'fedex', 'ups', 'dhl'
carrierStatusCode : string   // raw exception code from carrier
carrierStatusDescription : string  // human-readable exception message
trackingNumber    : string
shipDate          : string   // ISO 8601
// Output to Exception Triage Agent
exceptionPayload  : object   // above fields plus parsed carrierCode and statusCode

Shopify is called twice in the automation: once by the Exception Triage Agent to fetch the full order record, and once by the Resolution Agent to apply the reship (draft order) or refund. Both calls use the Admin REST API.

// GET /admin/api/2024-04/orders.json?name={orderNumber}&status=any
order.id              : integer  // Shopify internal order ID
order.name            : string   // #1234 format
order.email           : string   // customer email for Gmail step
order.total_price     : string   // string decimal, compare to threshold
order.shipping_address: object   // address fields for triage
order.line_items[]    : array    // product titles and quantities
order.customer.first_name : string
// POST /admin/api/2024-04/draft_orders.json (reship)
draft_order.line_items: array    // copied from original order.line_items
draft_order.shipping_address: object
draft_order.note      : string   // 'Reship: exception ref {exceptionId}'
// POST /admin/api/2024-04/orders/{id}/refunds.json
refund.shipping.full_refund: boolean
refund.note           : string   // 'Refund: exception ref {exceptionId}'

Gorgias receives an API call from the Resolution Agent to create a support ticket immediately after exception classification. The ticket is tagged with the exception type and assigned to the fulfilment queue. The ticket ID is stored in the workflow state for later update.

// POST /api/tickets (create ticket)
ticket.channel        : 'email'
ticket.subject        : string   // 'Exception: {exceptionType} - Order {orderName}'
ticket.assignee_team  : {id: GORGIAS_FULFILMENT_QUEUE_ID}
ticket.tags[]         : string[] // from GORGIAS_TAG_MAP lookup
ticket.messages[0].body_html : string  // exception detail HTML
ticket.messages[0].from_agent: true
// Response
ticket.id             : integer  // store as workflowState.gorgiasTicketId
// PUT /api/tickets/{id} (update with resolution)
ticket.status         : 'closed'
ticket.tags           : append 'resolved-reship' or 'resolved-refund'

Gmail sends the customer-facing exception notification email using a template matched to the classified exception type. Four templates are required, one per exception category. The send is triggered by the Resolution Agent immediately after the Gorgias ticket is created.

// Input from Resolution Agent
customer_email        : string   // order.email from Shopify
customer_first_name   : string   // order.customer.first_name
order_name            : string   // e.g. #1042
exception_type        : string   // one of: address_issue, failed_attempt, customs_hold, lost_parcel
carrier_name          : string   // human-readable carrier name
tracking_number       : string
gorgias_reply_email   : string   // Gorgias ticket reply-to address
// Gmail API call
POST /gmail/v1/users/me/messages/send
body: { raw: base64url(MIMEmessage) }
// MIMEmessage headers
To: {customer_email}
From: {GMAIL_SENDER_ADDRESS}
Reply-To: {gorgias_reply_email}
Subject: 'Update on your order {order_name}'

Slack is used for two distinct purposes: a manager approval prompt (interactive message with Approve/Reject buttons) when order value exceeds the configured threshold, and a non-interactive resolution summary posted to the fulfilment channel after each case is closed.

// Approval prompt message (Block Kit)
channel               : SLACK_APPROVAL_CHANNEL_ID
blocks[].type         : 'section' | 'actions'
blocks[].text.text    : 'Exception: {exceptionType} on order {orderName} ({orderValue}). Recommended: {recommendedResolution}.'
blocks[].elements[0].action_id : 'approve_resolution'
blocks[].elements[1].action_id : 'reject_resolution'
metadata.callback_id  : workflowInstanceId  // used to resume correct workflow
// Inbound interaction payload (from Slack to orchestration layer)
payload.actions[0].action_id : string  // 'approve_resolution' or 'reject_resolution'
payload.user.id       : string   // Slack user ID of approver (log for audit)
payload.message.ts    : string   // message timestamp for chat.update
// Resolution summary message
channel               : SLACK_FULFILMENT_CHANNEL_ID
text                  : 'Resolved: Order {orderName} | {exceptionType} | {resolutionType} | {timestamp}'

Google Sheets receives a row append call from the Resolution Agent after every exception is resolved. It is the persistent audit log for all exceptions. The sheet structure must be created before go-live and must not be modified after the automation is live without updating the column index mapping in the workflow.

// POST spreadsheets/{SHEETS_SPREADSHEET_ID}/values/Exception Log!A:J:append
valueInputOption      : 'USER_ENTERED'
insertDataOption      : 'INSERT_ROWS'
body.values[0][0]     : timestamp          // ISO 8601, e.g. '2024-06-03T14:22:00Z'
body.values[0][1]     : order.name         // e.g. '#1042'
body.values[0][2]     : order.total_price  // e.g. '$124.00'
body.values[0][3]     : exception_type     // e.g. 'address_issue'
body.values[0][4]     : carrier_name       // e.g. 'USPS'
body.values[0][5]     : tracking_number
body.values[0][6]     : resolution_type    // 'reship' or 'refund'
body.values[0][7]     : approved_by        // Slack user ID or 'auto'
body.values[0][8]     : gorgias_ticket_id  // integer
body.values[0][9]     : notes              // free text or blank

// Credential store contents
// Store all values at platform credential level; reference by key name in node config

SHIPSTATION_API_KEY               : string   // ShipStation API key
SHIPSTATION_API_SECRET            : string   // ShipStation API secret
SHIPSTATION_WEBHOOK_SECRET_TOKEN  : string   // appended to webhook receiver URL as ?token=

SHOPIFY_STORE_DOMAIN              : string   // e.g. yourcompany.myshopify.com
SHOPIFY_ADMIN_API_TOKEN           : string   // custom app Admin API access token
SHOPIFY_API_VERSION               : string   // pinned, e.g. '2024-04'
SHOPIFY_ORDER_VALUE_THRESHOLD     : number   // approval threshold in USD, business-defined

GORGIAS_BASE_URL                  : string   // e.g. https://yourcompany.gorgias.com
GORGIAS_EMAIL                     : string   // service account email
GORGIAS_API_KEY                   : string   // Gorgias REST API key
GORGIAS_FULFILMENT_QUEUE_ID       : integer  // pre-fetched view ID, not name string
GORGIAS_TAG_MAP                   : JSON     // {address_issue:'exc-address', ...}

GMAIL_CLIENT_ID                   : string   // Google Cloud OAuth client ID
GMAIL_CLIENT_SECRET               : string   // Google Cloud OAuth client secret
GMAIL_REFRESH_TOKEN               : string   // long-lived refresh token
GMAIL_SENDER_ADDRESS              : string   // authorised sending address

SLACK_BOT_TOKEN                   : string   // xoxb- prefixed bot token
SLACK_SIGNING_SECRET              : string   // for HMAC-SHA256 request validation
SLACK_APPROVAL_CHANNEL_ID         : string   // channel or DM for manager approval
SLACK_FULFILMENT_CHANNEL_ID       : string   // channel for resolution summaries
APPROVAL_TIMEOUT_SECONDS          : integer  // default 86400 (24 hours)

GOOGLE_SERVICE_ACCOUNT_KEY_JSON   : string   // base64-encoded service account JSON
SHEETS_SPREADSHEET_ID             : string   // Google Sheets file ID from URL
SHEETS_LOG_SHEET_NAME             : string   // default 'Exception Log'

// Carrier exception code mapping (workflow variable, not a secret)
CARRIER_EXCEPTION_CODE_MAP        : JSON     // {usps:{A1:'address_issue',...}, fedex:{...}, ups:{...}, dhl:{...}}