Integration and API Spec

Integration and API Spec

3PL / Warehouse Coordination Automation

Primary 3PL data source. The automation reads inventory snapshots, inbound receiving records, and outbound fulfillment order statuses. ShipBob also emits webhooks for inbound and outbound status changes that serve as the event-based trigger for Agent 1.

// Inputs
Scheduled trigger (daily cron) OR webhook POST from ShipBob
SHIPBOB_API_TOKEN, SHIPBOB_CHANNEL_ID from credential store
SHIPBOB_SKU_MAP (JSON) from config store
// Outputs
Normalised inventory snapshot array: [{ sku_internal, sku_shipbob, qty_on_hand, qty_committed, qty_receiving }]
Normalised ASN list: [{ asn_id, po_number, sku_internal, qty_expected, received_date, status }]
Normalised outbound list: [{ order_id, sku_internal, qty_shipped, dispatch_date, carrier, tracking }]

OMS and inventory master record. Agent 2 reads current stock levels per SKU to compare against the ShipBob dataset. Agent 3 writes approved stock adjustments back to Cin7 with a structured adjustment note per change.

// Inputs (Agent 2 read)
Normalised SKU list from Agent 1 output
CIN7_ACCOUNT_ID, CIN7_API_KEY, CIN7_BASE_URL, CIN7_WAREHOUSE_ID from credential store
// Outputs (Agent 2)
Cin7 inventory snapshot: [{ sku_internal, cin7_product_id, qty_on_hand }]
Classified result set: [{ sku_internal, cin7_product_id, shipbob_qty, cin7_qty, variance, classification }]
// Inputs (Agent 3 write)
Classified result set filtered to classification == 'minor_variance' or 'matched'
CIN7_ADJUSTMENT_REASON, CIN7_WAREHOUSE_ID from config store
// Outputs (Agent 3)
Cin7 StockAdjustment confirmation: [{ sku_internal, cin7_product_id, adjustment_qty, adjustment_id, timestamp }]

Storefront inventory system. Agent 3 pushes confirmed stock levels to Shopify after Cin7 adjustments are written, updating available inventory per variant so the storefront reflects accurate counts without manual entry.

// Inputs
Cin7 adjustment confirmation list from Agent 3 Cin7 write step
SHOPIFY_ACCESS_TOKEN, SHOPIFY_STORE_DOMAIN, SHOPIFY_LOCATION_ID, SHOPIFY_INVENTORY_MAP from credential/config store
// Outputs
Shopify inventory level set confirmation: [{ sku_internal, inventory_item_id, location_id, available_set, timestamp }]
Warning list for unmapped SKUs: [{ sku_internal, reason }]

Notification delivery channel. Agent 3 posts structured exception alerts for major discrepancies and missing ASNs, and sends a daily reconciliation summary to the designated fulfilment channel.

// Inputs
Classified discrepancy list: items where classification == 'major_discrepancy' or asn_status == 'missing'
Daily summary payload: { run_date, total_skus, matched, minor_variance, major_discrepancy, adjustments_written, open_exceptions }
SLACK_BOT_TOKEN, SLACK_CHANNEL_FULFILMENT, SLACK_CHANNEL_FINANCE from credential/config store
// Outputs
Slack message timestamp (ts) for each posted message: [{ channel_id, ts, message_type }]
Delivery confirmation or error response from Slack API

Audit log and reconciliation record. Agent 2 appends one row per reconciliation run to the master log sheet, capturing run metadata, SKU-level variance counts, adjustments made, and open exceptions for operations and finance review.

// Inputs
Reconciliation run summary: { run_date, run_id, total_skus, matched, minor_variance, major_discrepancy, adjustments_written, open_exceptions, duration_seconds, triggered_by }
GOOGLE_SERVICE_ACCOUNT_KEY, GOOGLE_SHEETS_LOG_ID, GOOGLE_SHEETS_LOG_TAB from credential/config store
// Outputs
Sheets API append response: { spreadsheetId, tableRange, updates.updatedRows }
Confirmed row number of appended entry (for logging)

// === CREDENTIAL STORE (secret, encrypted at rest) ===

SHIPBOB_API_TOKEN          // Bearer token from ShipBob Merchant Dashboard
SHIPBOB_WEBHOOK_SECRET     // HMAC-SHA256 signing secret for webhook validation
CIN7_ACCOUNT_ID            // Cin7 account identifier (Basic Auth username)
CIN7_API_KEY               // Cin7 API key (Basic Auth password)
SHOPIFY_ACCESS_TOKEN       // Custom app OAuth access token (X-Shopify-Access-Token header)
SLACK_BOT_TOKEN            // Slack bot OAuth token (Bearer, chat:write scope)
GOOGLE_SERVICE_ACCOUNT_KEY // Full JSON key for Google Cloud service account (multi-line)

// === CONFIG STORE (non-secret, auditable) ===

SHIPBOB_CHANNEL_ID         // ShipBob merchant channel ID (passed as channel_id param)
SHIPBOB_SKU_MAP            // JSON object: { 'SHIPBOB-SKU-001': 'INTERNAL-SKU-001', ... }

CIN7_BASE_URL              // 'https://api.cin7.com/api/v1'
CIN7_WAREHOUSE_ID          // Cin7 location ID for the ShipBob warehouse
CIN7_ADJUSTMENT_REASON     // e.g. '3PL Reconciliation - Automated'

SHOPIFY_STORE_DOMAIN       // e.g. 'yourcompany.myshopify.com'
SHOPIFY_LOCATION_ID        // Shopify inventory location ID for ShipBob fulfilment location
SHOPIFY_INVENTORY_MAP      // JSON object: { 'INTERNAL-SKU-001': 'shopify_inventory_item_id', ... }

SLACK_CHANNEL_FULFILMENT   // Slack channel ID for fulfilment alerts (e.g. 'C04XXXXXXXX')
SLACK_CHANNEL_FINANCE      // Slack channel ID for daily finance summary
SLACK_ALERT_MENTION_USER   // Optional Slack user ID for @mention on critical alerts

GOOGLE_SHEETS_LOG_ID       // Spreadsheet ID of the master reconciliation log sheet
GOOGLE_SHEETS_LOG_TAB      // Sheet tab name (default: 'Reconciliation Log')

RECONCILIATION_MINOR_THRESHOLD  // Integer: max variance to auto-correct (default: 2)
RECONCILIATION_MAJOR_THRESHOLD  // Integer: variance triggering Slack alert (default: 10)

DAILY_TRIGGER_TIME         // Cron expression for scheduled daily run (e.g. '0 6 * * 1-5')
RUN_TIMEZONE               // Timezone for cron scheduling (e.g. 'America/New_York')