Auto Parts Integration Manual

Developer guidance for integrating DecisioQ Auto Parts decisions with retail, wholesale, inventory, warehouse, eCommerce, returns, core, and supplier workflows.
1Auto Parts Overview

The Auto Parts sector in the DecisioQ Decision Catalog is identified by AUTO-PART. It currently covers 76 decision types across parts availability, replenishment, inventory control, warehouse operations, supplier selection, eCommerce orders, returns, warranty, core handling, compatibility, delivery, and customer-service workflows.

DecisioQ integrations should load sector, category, decision, Decision Preparation Model, and scenario metadata from the Decision Catalog. Do not hard-code old template names, static decision lists, or legacy request models.

Recommended first deployment: start with one high-frequency workflow such as backorder prioritization, substitute part recommendation, supplier selection, replenishment priority, or core return handling. Compare DecisioQ recommendations against current buyer, counter-sales, and warehouse decisions before automating downstream actions.

2Catalog Discovery Flow

Auto Parts client applications should use the same discovery flow as the Business Decision Studio:

  1. Load GET /decisioncatalog through the approved server-side Decision Catalog gateway.
  2. Populate Sector from catalog.sectors[] and select AUTO-PART for Auto Parts.
  3. Populate Category from selectedSector.categories[]. Example categories include Inventory Control, Purchasing and Replenishment, Warehouse Operations, Order Fulfillment, Returns and Warranty, Core Handling, Compatibility and Fitment, and Delivery Logistics.
  4. Populate Decision from selectedCategory.decisions[] when available, or call /decisioncatalog/sectors/{sectorCode}/categories/{categoryCode}/decisions.
  5. Display Decision Name only in the dropdown while keeping decisionId as the option value.
  6. Load full decision detail from /decisioncatalog/decisions/{decisionId} before rendering Guided Data Collection.

Decision detail is the source of truth for criterion names, data guidance, scale, direction, profile options, scenarios, and overview metadata.

For regional deployments, keep DecisioQ technical identifiers stable and localize only user-facing labels and guidance. Unless the selected endpoint and decision schema explicitly support unit-qualified input, convert mileage, distance, pressure, temperature, mass, volume, speed, fuel consumption, and other measurements to the required canonical units before submission. Do not infer units or currency from locale.

3Auto Parts Use Cases
Use CasePrimary UsersTypical Inputs
Backorder and stockout prioritizationInventory planners, branch managers, counter salesCustomer priority, SLA urgency, sales velocity, margin, substitute availability, lead time.
Supplier and sourcing selectionPurchasing, fulfillment, eCommerce operationsVendor cost, fill rate, lead time, return policy, warranty support, freight cost, reliability.
Substitute part and fitment recommendationCounter sales, catalog teams, online shoppers, repair partnersCompatibility confidence, brand preference, price, quality tier, availability, warranty, customer need.
Inventory replenishment and allocationInventory control, distribution operationsDemand trend, safety stock, days on hand, stockout risk, branch transfer cost, seasonality.
Returns, warranty, and goodwill handlingReturns desk, customer support, warranty administratorsReturn reason, purchase age, condition, defect evidence, customer history, supplier rules, margin impact.
Core return evaluationWarehouse, service counter, remanufacturing program ownersCore condition, eligibility, completeness, contamination risk, deposit amount, remanufacturer acceptance.
Warehouse picking and slottingWarehouse supervisors, WMS teamsPicker availability, zone proximity, item size, velocity, workload, accuracy history, safety compliance.
Delivery route and carrier selectionDispatch, shipping, eCommerce checkoutDelivery promise, distance, cost, route capacity, package constraints, customer priority.
4Business Data Mapping

Auto Parts integrations should map operational SKU, inventory, supplier, customer, order, warehouse, and return data into decision-specific Business Data. The selected decision detail defines which criteria are required and how each value should be measured.

Business Data SourceCommon UseIntegration Notes
SKU, part number, order ID, supplier ID, branch ID, or return authorization IDoptionId and audit correlation.Keep stable source-system IDs so recommendations can be traced back to POS, ERP, WMS, catalog, and RMA records.
Inventory and demand signalsReplenishment, allocation, stockout response, slow-moving inventory review.Normalize quantities, velocity, days on hand, reserved stock, and forecast horizon before execution.
Supplier performanceSourcing, drop-ship, purchasing, backorder handling.Separate current availability from historical reliability so decisions can weigh both correctly.
Fitment and compatibility dataSubstitute recommendation and compatibility validation.Use the latest catalog/interchange data and distinguish confirmed fit from uncertain or inferred fit.
Price, margin, freight, and handling costSupplier selection, discount exception, shipping, return handling.Keep currency and unit assumptions explicit. Avoid mixing customer price, net cost, and landed cost.
Warranty, RMA, and core condition dataReturn, goodwill, warranty, chargeback, and core credit decisions.Capture reason codes, condition, completeness, eligibility, and evidence quality separately.
Warehouse and delivery operations dataPicking, slotting, putaway, route, carrier, and branch transfer decisions.Refresh workload and capacity data close to execution time to avoid stale operational recommendations.

Do not invent criterion IDs. Use the canonical criteria returned by /decisioncatalog/decisions/{decisionId}, including criterion overview metadata, unit, direction, scale, and data guidance.

5Preview and Execute Workflow

Production integrations should keep credentials and bearer tokens on trusted servers or server-side gateways. Browser pages should use same-origin proxy handlers or their own backend service.

  1. Trusted backend obtains a JWT token from identity.vinquery.com.
  2. Application loads catalog and decision detail metadata.
  3. User or system prepares Business Data for candidate suppliers, SKUs, orders, returns, inventory actions, delivery options, or warehouse tasks.
  4. Call POST /api/v1/validate to validate and prepare the decision input before execution.
  5. Call POST /api/v1/decide to return the authoritative Decision Result.
  6. Display the recommendation, ranked alternatives, warnings, assumptions, and Explanation of Decision Result.
  7. Keep execution trace and diagnostics available to integrators, but collapsed or hidden by default for business users.

Use /api/v1/decide for both Prepared Criteria Mode and business-data integrations that submit a businessData object. New public onboarding should prefer Preview Decision and Execute Decision terminology.

6Example Request Shape

The exact fields depend on the selected Auto Parts decision. The example below shows the integration style rather than a guaranteed schema for every decision.

{
  "decisionId": "AUTO-PART-001",
  "decisionPreparationModelId": "AUTO-PART-PROFILE-STANDARD",
  "scenarioId": "AUTO-PART-SCENARIO-BACKORDER-PRIORITY",
  "businessData": {
    "candidates": [
      {
        "optionId": "BACKORDER-90217",
        "name": "Brake rotor set for fleet account",
        "values": {
          "customerPriorityScore": 92,
          "slaUrgencyScore": 88,
          "grossMarginScore": 73,
          "substituteAvailabilityScore": 36,
          "supplierLeadTimeDays": 2,
          "stockoutImpactScore": 84
        }
      },
      {
        "optionId": "BACKORDER-90244",
        "name": "Alternator for retail order",
        "values": {
          "customerPriorityScore": 65,
          "slaUrgencyScore": 71,
          "grossMarginScore": 81,
          "substituteAvailabilityScore": 68,
          "supplierLeadTimeDays": 5,
          "stockoutImpactScore": 59
        }
      }
    ]
  },
  "requestContext": {
    "correlationId": "parts-workbench-20260717-001"
  }
}
7Backend Call Pattern

This pattern belongs in a trusted backend, not directly in browser JavaScript.

async function executeAutoPartsDecision(decisionInput, jwtToken) {
  const response = await fetch(`${process.env.DECISIOQ_BASE_URL}/api/v1/decide`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${jwtToken}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(decisionInput)
  });

  if (!response.ok) {
    throw new Error(`DecisioQ execution failed: ${response.status} ${await response.text()}`);
  }

  return await response.json();
}
8UI and Workflow Integration
UI ElementRecommended DisplayWhy It Matters
Choose a DecisionSector, Category, Decision, Profile, and Scenario selectors populated from catalog metadata.Users see business names while integrators retain stable IDs.
Selection OverviewSector, category, and decision overviews in one collapsible panel.Parts, inventory, and operations users understand the decision before entering data.
Guided Data CollectionCriterion label, field, data type indicator, summary, and expandable "More about this criterion".Improves SKU, supplier, inventory, and return data quality.
Candidate CasesTwo fields per row where practical, editable option ID, and visible units or data type indicators.Counter, warehouse, and planning users can compare alternatives quickly.
Decision ResultRecommendation, ranking, confidence, and key drivers.Users need the answer and the reason.
Outcome Follow-upAccepted, Rejected, or Overridden; selected option and override reason when applicable.Connects the recommendation to the action actually taken.
Realized ValueOutcome status plus a consistently defined financial or operational metric.Measures adoption and business value without changing deterministic scoring.
ExplanationBusiness-friendly explanation without AI provider branding.Supports trust while keeping the UI provider-neutral.
DiagnosticsCollapsed technical panel for status, timings, warnings, and errors.Useful for integrators without distracting business users.
9Production Readiness
  • Store identity credentials, Decision API base URL, and proxy configuration in trusted server configuration or a secret manager.
  • Do not expose bearer tokens or integration credentials in browser code.
  • Use catalog metadata rather than hard-coded categories, decisions, criteria, profiles, or scenarios.
  • Validate Business Data before execution and show user-friendly validation messages.
  • Persist correlation ID, order ID, SKU, branch ID, supplier ID, decision ID, profile ID, scenario ID, selected option, score, and explanation for audit.
  • Retain the successful decision response requestId with the host business transaction, then call POST /api/v1/decision-outcomes when the action and realized result are known.
  • Require an overrideReason for overridden recommendations; never infer acceptance merely because a result was displayed.
  • Monitor GET /api/v1/decision-outcomes/summary for acceptance rate, override rate, and realized-value aggregates. Treat outcome feedback as reporting evidence, not automatic model training.
  • Redact customer identifiers, payment data, supplier cost details, and sensitive contract terms in logs and diagnostics.
  • Monitor catalog load failures, token refresh failures, API latency, validation failures, account verification failures, and unusual exclusion rates.
  • Define fallback behavior so counter sales, eCommerce, purchasing, and warehouse workflows remain usable when DecisioQ is unavailable.
  • Review Decision Preparation Models and scenario assumptions with purchasing, inventory, warehouse, and customer-service owners when supplier policies or demand patterns change.
10Troubleshooting
SymptomLikely CauseFix
Category list is empty.The catalog response does not include categories for the selected sector, or the client is reading an old category layer.Use selectedSector.categories[] from /decisioncatalog.
Decision dropdown shows IDs only.The client did not load decision detail or category decision names.Display Decision Name as the label and keep decision ID as the option value.
Criterion guidance is missing.Decision detail lacks criterion overview metadata or the page is not rendering it.Read criterion overview from /decisioncatalog/decisions/{decisionId} and show available summaries.
Secure session could not be refreshed.Token proxy or identity service configuration failed.Check server-side identity configuration and proxy logs; do not request tokens directly from browser JavaScript.
Decision execution failed.Decision API unavailable, invalid Business Data, authorization failure, or account verification issue.Check response envelope, HTTP status, correlation ID, Decision API health, and server logs.
Unexpected recommendation.Scale, units, direction, or values do not match catalog criterion guidance.Compare Business Data fields against criterion overview and validation metadata.
Fitment or substitute output seems wrong.Catalog, interchange, or vehicle context may be stale or incomplete.Refresh fitment data and distinguish confirmed compatibility from inferred compatibility before execution.