Integration and API Spec

Integration and API Spec

Order Processing and Fulfilment

Order source for Agent 1 trigger and fulfilment status target for Agent 2. Also provides order tag data consumed by Agent 3.

// Trigger payload (orders/paid webhook)
order.id, order.name, order.email, order.line_items[].sku,
order.line_items[].quantity, order.shipping_address,
order.shipping_lines[].title, order.tags, order.total_price
// Write-back (fulfilment)
POST /admin/api/2024-04/orders/{order_id}/fulfillments.json
{ tracking_number, tracking_company, tracking_url, location_id }

Used exclusively by Agent 2 (Dispatch Agent) to create shipment records, select service levels, and retrieve tracking numbers.

// POST /orders/createorder
{ orderNumber, orderDate, orderStatus: 'awaiting_shipment',
  billTo: { name, street1, city, postalCode, country },
  shipTo: { name, street1, city, postalCode, country },
  items: [{ sku, quantity, unitPrice }],
  carrierCode, serviceCode, packageCode: 'package',
  warehouseId }
// GET /shipments?orderNumber={id} response
{ trackingNumber, carrierCode, shipDate }

Used by Agent 1 for real-time stock verification and by Agent 2 for post-dispatch stock deduction.

// Stock check: POST /api/Stock/GetStockLevel
{ StockItemIds: ['uuid-sku-1', 'uuid-sku-2'] }
// Response
[ { StockItemId, Available, InOrder, MinimumLevel } ]
// Stock deduction: POST /api/Stock/SetStockLevel
{ StockItemId, LocationId, Level, ChangeSource: 'DISPATCH' }

Used exclusively by Agent 3 (Finance Agent) to create draft invoices for wholesale and B2B orders.

// POST https://api.xero.com/api.xro/2.0/Invoices
{ Type: 'ACCREC', Status: 'DRAFT',
  Contact: { ContactID: '{xero_contact_id}' },
  Reference: 'SHOPIFY-{order_name}',
  LineItems: [{ Description, Quantity, UnitAmount,
                AccountCode: XERO_SALES_ACCOUNT_CODE,
                TaxType: XERO_TAX_TYPE }] }

Used by Agent 1 to post structured out-of-stock alerts to the fulfilment channel. Also used by the error handler across all agents for unhandled exception notifications.

// POST https://slack.com/api/chat.postMessage
{ channel: SLACK_FULFILMENT_CHANNEL_ID,
  text: 'Out-of-stock alert',
  blocks: [
    { type: 'section', text: { type: 'mrkdwn',
      text: '*Order {order_name}* | SKUs short: {sku_list}\nQty available: {qty_map}\n<{shopify_admin_url}|View order>' }
    }
  ]
}

Used by Agent 2 to send the personalised tracking confirmation email to the customer after ShipStation returns a tracking number.

// Gmail send action (Make module: Gmail > Send an Email)
{ to: order.email,
  from: GMAIL_FROM_ADDRESS,
  replyTo: GMAIL_REPLY_TO,
  subject: 'Your order {order_name} has shipped!',
  content: '{customer_first_name}, your order is on its way.\n
             Carrier: {carrier_name}\n
             Tracking: {tracking_url}' }

// Shopify
SHOPIFY_API_KEY              = '<custom_app_api_key>'
SHOPIFY_API_SECRET           = '<custom_app_api_secret>'
SHOPIFY_WEBHOOK_SECRET       = '<hmac_shared_secret>'
SHOPIFY_SHOP_DOMAIN          = '<store>.myshopify.com'
SHOPIFY_LOCATION_ID          = '<fulfilment_location_id>'
SHOPIFY_WHOLESALE_TAG        = 'wholesale'   // or 'b2b' — confirm with owner

// ShipStation
SHIPSTATION_API_KEY          = '<api_key>'
SHIPSTATION_API_SECRET       = '<api_secret>'
SHIPSTATION_WAREHOUSE_ID     = '<warehouse_id>'
SHIPSTATION_CARRIER_ID_UPS   = '<ups_carrier_id>'
SHIPSTATION_CARRIER_ID_USPS  = '<usps_carrier_id>'
SHIPSTATION_SERVICE_MAP      = '{"Standard Shipping":{"carrierCode":"stamps_com","serviceCode":"usps_first_class_mail"}, "Express":{"carrierCode":"ups","serviceCode":"ups_next_day_air"}}'

// Linnworks
LINNWORKS_APP_ID             = '<application_id>'
LINNWORKS_APP_SECRET         = '<application_secret>'
LINNWORKS_LOCATION_ID        = '<primary_warehouse_location_id>'

// Xero
XERO_CLIENT_ID               = '<oauth_client_id>'
XERO_CLIENT_SECRET           = '<oauth_client_secret>'
XERO_REFRESH_TOKEN           = '<offline_refresh_token>'   // updated on every token refresh
XERO_TENANT_ID               = '<xero_organisation_tenant_id>'
XERO_SALES_ACCOUNT_CODE      = '200'
XERO_TAX_TYPE                = 'OUTPUT2'

// Slack
SLACK_BOT_TOKEN              = 'xoxb-<bot_token>'
SLACK_FULFILMENT_CHANNEL_ID  = '<channel_id>'
SLACK_ERRORS_CHANNEL_ID      = '<channel_id>'

// Gmail
GMAIL_CLIENT_ID              = '<oauth_client_id>'
GMAIL_CLIENT_SECRET          = '<oauth_client_secret>'
GMAIL_REFRESH_TOKEN          = '<oauth_refresh_token>'
GMAIL_FROM_ADDRESS           = 'orders@[YourCompany.com]'
GMAIL_REPLY_TO               = 'support@[YourCompany.com]'
GMAIL_SUBJECT_TEMPLATE       = 'Your order {order_name} has shipped!'