Integration and API Spec

Integration and API Spec

Inventory Reorder Management

Cin7 is the source of truth for stock levels and the system in which draft purchase orders are created. The automation platform polls the Cin7 Products endpoint on a scheduled interval to detect SKUs at or below their reorder point, then writes a draft PO via the Purchase Orders endpoint.

// Poll input
GET /api/v1/stock?page=1&limit=250
// Poll output (filtered)
{ "productId": "P-1042", "sku": "BLK-HOODIE-M", "onHand": 12, "reorderPoint": 20, "preferredSupplierId": "SUP-007" }
// PO create input
POST /api/v1/purchaseorders
{ "supplierId": "SUP-007", "lines": [{ "productId": "P-1042", "qty": 60, "unitPrice": 14.50 }], "expectedDate": "2024-07-15", "status": "Draft" }
// PO create output
{ "purchaseOrderId": "PO-20240701-042", "status": "Draft", "totalValue": 870.00 }

Google Sheets serves two distinct purposes: (1) the sales velocity and lead time reference table read by Agent 1 to calculate reorder quantities, and (2) the open PO tracking log written by Agent 2 after each PO is dispatched.

// Reference sheet read input
GET sheets/v4/spreadsheets/{GSHEETS_REFERENCE_SHEET_ID}/values/SKUReference!A2:F
// Reference sheet read output (one row)
{ "sku": "BLK-HOODIE-M", "avg_daily_sales": 4.2, "lead_time_days": 14, "safety_stock_units": 10, "preferred_supplier_email": "orders@supplier.com" }
// Tracker append input
POST sheets/v4/spreadsheets/{GSHEETS_TRACKER_SHEET_ID}/values/POTracker!A:L:append
{ "values": [["PO-20240701-042", "BLK-HOODIE-M", "Apex Garments", "orders@supplier.com", 60, 14.50, 870.00, "2024-07-01", "2024-07-15", "Sent", "Pending"]] }

Slack is used by Agent 2 to send an approval request to the operations manager when a PO value exceeds the configured approval threshold. The manager responds via Slack interactive buttons (Approve or Reject). A secondary alert is posted to the operations channel if no supplier acknowledgement is received within 24 hours.

// Approval request payload (chat.postMessage)
POST https://slack.com/api/chat.postMessage
{ "channel": "{SLACK_MANAGER_USER_ID}",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn", "text": "*PO Approval Required*\nSKU: BLK-HOODIE-M | Qty: 60 | Value: $870.00 | Supplier: Apex Garments" } },
    { "type": "actions", "elements": [
      { "type": "button", "text": { "type": "plain_text", "text": "Approve" }, "style": "primary", "value": "PO-20240701-042|approve" },
      { "type": "button", "text": { "type": "plain_text", "text": "Reject" }, "style": "danger", "value": "PO-20240701-042|reject" }
    ]}
  ]
}
// Interaction callback received
{ "type": "block_actions", "actions": [{ "value": "PO-20240701-042|approve" }], "user": { "id": "U0123456789" } }

Gmail is used by Agent 2 to send the finalised purchase order PDF to the supplier and, if no acknowledgement is received within 24 hours, to send an automatic follow-up chaser. Both sends originate from the operations team's designated sending address.

// Gmail send input (POST users.messages.send)
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
{ "raw": "<Base64url-encoded RFC 2822 message>" }
// Decoded MIME structure
From: operations@yourcompany.com
To: orders@supplier.com
Subject: Purchase Order PO-20240701-042 - BLK-HOODIE-M
Content-Type: multipart/mixed
  -- Part 1: text/plain body with {{po_number}}, {{qty}}, {{total_value}} resolved
  -- Part 2: application/pdf; name=PO-20240701-042.pdf (Base64-encoded)
// Gmail send output
{ "id": "18a3f9c2b1d4e5f6", "threadId": "18a3f9c2b1d4e5f6", "labelIds": ["SENT"] }

Xero receives a draft bill creation call from Agent 2 after the PO is dispatched to the supplier. The bill records the expected liability against the correct supplier contact, linked to the PO number as a reference, so the accounts team has immediate visibility of incoming payables.

// Supplier contact lookup
GET https://api.xero.com/api.xro/2.0/Contacts?where=Name%3D%3D%22Apex%20Garments%22
// Contact lookup response
{ "Contacts": [{ "ContactID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "Name": "Apex Garments" }] }
// Bill create input
POST https://api.xero.com/api.xro/2.0/Invoices
{ "Type": "ACCPAY", "Contact": { "ContactID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" },
  "Date": "2024-07-01", "DueDate": "2024-07-15", "Status": "DRAFT",
  "Reference": "PO-20240701-042",
  "LineItems": [{ "Description": "BLK-HOODIE-M x60", "Quantity": 60, "UnitAmount": 14.50, "AccountCode": "{XERO_PURCHASES_ACCOUNT_CODE}" }]
}
// Bill create response
{ "Invoices": [{ "InvoiceID": "x9y8z7w6-v5u4-3210-fedc-ba9876543210", "InvoiceNumber": "BILL-0042", "Status": "DRAFT" }] }

// Credential store contents (all keys required before first run)

// Cin7
CIN7_ACCOUNT_ID           = "<cin7-account-id>"
CIN7_API_KEY              = "<cin7-application-key>"

// Google Sheets
GSHEETS_SERVICE_ACCOUNT_JSON    = "<full JSON key file contents>"
GSHEETS_REFERENCE_SHEET_ID      = "<spreadsheet-id-of-sku-reference-sheet>"
GSHEETS_TRACKER_SHEET_ID        = "<spreadsheet-id-of-po-tracker-sheet>"

// Gmail
GMAIL_OAUTH_REFRESH_TOKEN = "<oauth2-refresh-token>"
GMAIL_CLIENT_ID           = "<google-cloud-client-id>"
GMAIL_CLIENT_SECRET       = "<google-cloud-client-secret>"
GMAIL_SENDER_ADDRESS      = "operations@yourcompany.com"

// Xero
XERO_CLIENT_ID            = "<xero-app-client-id>"
XERO_CLIENT_SECRET        = "<xero-app-client-secret>"
XERO_ACCESS_TOKEN         = "<xero-oauth2-access-token>"
XERO_REFRESH_TOKEN        = "<xero-oauth2-refresh-token>"
XERO_TENANT_ID            = "<xero-organisation-tenant-id>"
XERO_PURCHASES_ACCOUNT_CODE = "<chart-of-accounts-code-for-purchases>"

// Slack
SLACK_BOT_TOKEN           = "xoxb-<slack-bot-token>"
SLACK_SIGNING_SECRET      = "<slack-app-signing-secret>"
SLACK_MANAGER_USER_ID     = "U<slack-user-id-of-operations-manager>"
SLACK_OPS_CHANNEL_ID      = "C<slack-channel-id-of-ops-channel>"
SLACK_INTERACTION_WEBHOOK_URL = "https://<platform-host>/webhooks/slack-interactions"

// Internal agent-to-agent webhook
AGENT_WEBHOOK_SECRET      = "<hmac-sha256-shared-secret>"
AGENT2_INBOUND_WEBHOOK_URL = "https://<platform-host>/webhooks/po-dispatch-agent"

// Business logic thresholds (configurable without code change)
APPROVAL_THRESHOLD_USD    = 500
POLL_INTERVAL_MINUTES     = 5
CHASER_DELAY_HOURS        = 24