Standard-Order-API
Standard Order Experience API
Version: v1.0.0
Status: Production Ready
API Type: Experience Layer
Protocol: REST/HTTPS
Last Updated: June 15, 2026
Table of Contents
- Overview
- API Architecture
- API Endpoints
- POST /order - Create an order using Basic Authentication
- POST /orderUpdate - Receive order status updates from backend systems
- POST /v2/order - Create an order using OAuth 2.0 Authentication
- Data Models
- Field Specifications
- Schema Validation Rules
- Error Handling
- Authentication
Overview
General Information
| Property | Value |
|---|---|
| API Name | standard-order-api |
| Version | v1 |
| Base URL | https://muleqc.diam.compucom.com |
| Base URI | /api/standard-order/ |
| Full Endpoint | https://muleqc.diam.compucom.com/api/standard-order/ |
| Protocol | HTTPS |
| Format | JSON |
Environment URLs
| Environment | Base URL |
|---|---|
| Development | https://muledev.diam.compucom.com |
| QC (Quality Control) | https://muleqc.diam.compucom.com |
| Production | https://muleprod.diam.compucom.com |
đ Note: This documentation uses the QC environment (
https://muleqc.diam.compucom.com) in all examples. Replace with the appropriate environment URL for your specific needs.
Purpose
The Standard Order Experience API serves as a centralized integration layer for managing device and inventory orders across multiple enterprise clients. It provides a unified interface for order processing, status updates, and workflow orchestration between client systems and backend order management platforms.
Key Features
đ Order Creation
Accept and process orders from various client portals with comprehensive validation, transformation, and intelligent routing to backend systems such as DIMS or LCAM.
đ Status Updates
Receive real-time order status updates from backend systems and propagate them to the appropriate client applications, ensuring seamless communication throughout the order lifecycle.
đ Client Routing
Intelligent routing based on client identifiers with support for client-specific data transformations, business rules, and processing workflows.
đĄī¸ Error Handling
Comprehensive error handling with automatic retry mechanisms in the Mule runtime. Errors are returned to customers for the order creation flow, and to backend systems for order updates, enabling graceful recovery and retry capabilities.
Use Cases
- Multi-Client Integration: Single API endpoint serving multiple client organizations with customized requirements and workflows
- Order Lifecycle Management: End-to-end order tracking from creation through fulfillment
- System Orchestration: Seamless integration between client portals and backend order management systems
- Real-Time Status Updates: Bi-directional communication for order status changes
API Architecture
High-Level Architecture
ââââââââââââââââââââââââââââââââââââââââââââ
â Client Systems & Portals â
â (Web, Mobile, ERP Systems) â
ââââââââââââââââââŦââââââââââââââââââââââââââ
â HTTPS/REST
â
ââââââââââââââââââŧâââââââââââââââââââââââââââââââââââ
â Standard Order Experience API â
â ââââââââââââââââââââââââââââââââââââââââââââ â
â â APIKit Router (RAML Validation) â â
â âââââââââââââââŦâââââââââââââââââââââââââââââ â
â â â
â âââââââââââââââŧâââââââââââââââââââââââââââââ â
â â Client Identification & Routing â â
â â âĸ Parent Customer Number Resolution â â
â â âĸ Dynamic Client Configuration â â
â âââââââââââââââŦâââââââââââââââââââââââââââââ â
â â â
â âââââââââââââââŧâââââââââââââââââââââââââââââ â
â â Data Transformation Layer â â
â â âĸ Schema Validation â â
â â âĸ Field Mapping & Truncation â â
â â âĸ Client-Specific Transformations â â
â â âĸ Sales Reference Number Generation â â
â âââââââââââââââŦâââââââââââââââââââââââââââââ â
âââââââââââââââââââŧâââââââââââââââââââââââââââââââââ
â
ââââââââââ´âââââââââ
â â
ââââââŧââââââââââ ââââââŧââââââââââ
â DIMS System â â LCAM System â
â (Backend) â â (Backend) â
ââââââââââââââââ ââââââââââââââââIntegration Points
| Component | Purpose | Protocol | Authentication |
|---|---|---|---|
| Backend Systems | Core order processing and inventory management | REST/HTTPS | Basic Auth / OAuth 2.0 |
| Database | Sales reference number generation and configuration storage | JDBC | Username/Password |
| Object Store | OAuth token caching and session management | MuleSoft Runtime | N/A |
âšī¸ Architecture Pattern
This API follows the MuleSoft API-Led Connectivity approach as an Experience Layer API. It abstracts client-specific complexities and provides a consistent, easy-to-use interface while delegating core business processing to backend system APIs.
API Endpoints
The API exposes three main endpoints for order creation and status management. All endpoints are prefixed with /api/standard-order/
POST /order
Flow Type: Synchronous
Response Code: 201 Created
Response Time: ~2-5 seconds (typical)
Authentication: Basic Auth
Description
Creates a new order with synchronous processing. This endpoint provides immediate validation, processes the order, and returns confirmation upon successful submission to the backend system (DIMS or LCAM).
Features
- Comprehensive Field Validation: Enforces backend system field length and format requirements
- Intelligent Client Routing: Automatic routing based on parent customer number
- Sales Reference Number Generation: Auto-generates unique order reference numbers if not provided
- Real-Time Processing: Synchronous order creation with immediate confirmation
Request Example
Endpoint: POST https://muleqc.diam.compucom.com/api/standard-order/order
Headers:
Content-Type: application/json
Authorization: Basic <base64-encoded-credentials>
Body:
json
{
"order": [{
"salesRefNumber": "M0001234",
"customerNumber": "530101390",
"parentCustomerNumber": "799249461",
"entryDate": "08/26/20",
"requestedDate": "08/26/20",
"shipCustomerName": "Dane, Jane",
"shipCity": "FORT MILL",
"shipZipCode": "29707",
"shipAddress1": "8106 Calvin Hall Road",
"shipAddress2": "",
"shipAddress3": "",
"shipState": "SC",
"shipCountry": "US",
"shipPhone": "803-555-0123",
"requestedByEmail": "jane.dane@example.com",
"requestedForEmail": "recipient@example.com",
"requestedForName": "John Smith",
"requestedForPhone": "803-555-0456",
"customerPOReleaseNumber": "1098723456",
"customerPONumber": "PO-2020-08-001",
"viaCode": "bw",
"geoCode": 41,
"token": "",
"creditCardType": "",
"orderDetails": [
{
"orderLine": 1,
"customerPOLine": 1300,
"quantityOrdered": 2.0,
"price": 65.44,
"itemNumber": "R65736",
"description": "APC RACK SCREWS AND NUTS",
"manPartNo": "AR8100"
},
{
"orderLine": 2,
"customerPOLine": 1301,
"quantityOrdered": 1.0,
"price": 24.40,
"itemNumber": "R61591",
"description": "NETGEAR FS108 SWITCH 8 PORTS",
"manPartNo": "FS108NA"
}
],
"udf": [
{
"fieldNumber": 1,
"orderLine": 0,
"fieldName": "user_id",
"fieldDescription": "jdane",
"fieldLevel": "H"
},
{
"fieldNumber": 2,
"orderLine": 0,
"fieldName": "employee_number",
"fieldDescription": "EMP123456",
"fieldLevel": "H"
},
{
"fieldNumber": 3,
"orderLine": 0,
"fieldName": "email-addr",
"fieldDescription": "jane.dane@example.com",
"fieldLevel": "H"
}
],
"memo": [
{
"orderLine": 0,
"type": "o",
"comments": "Please deliver to front door reception desk"
}
]
}]
}
Response Example
201 Created - Success Response
{
"status": "Success",
"salesRefNumber": "M0047665"
}400 Bad Request - Validation Error
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Missing required field: parentCustomerNumber"
}
}500 Internal Server Error - System Error
{
"error": {
"code": "BACKEND_ERROR",
"message": "Unable to connect to backend system. Please try again later."
}
}POST /orderUpdate
Flow Type: Synchronous
Response Code: 200 OK
Retry Attempts: 3 attempts with exponential backoff
Authentication: Client-Specific (Basic Auth or OAuth 2.0)
Description
Receives order status updates from backend systems (DIMS or LCAM) and routes them to the appropriate client systems. This endpoint handles various order lifecycle events including shipment notifications, invoice generation, and order completion.
Features
- Automatic Retry Logic: Built-in retry mechanism with exponential backoff for transient failures
- OAuth Token Refresh: Automatic token refresh for expired OAuth credentials
- Multi-Client Routing: Intelligent routing based on parent customer number
- Comprehensive Status Updates: Supports order status, shipment tracking, invoice details, and serial numbers
Request Example
Endpoint: POST https://muleqc.diam.compucom.com/api/standard-order/orderUpdate
Headers:
Content-Type: application/json
Authorization: Depeds on client system
Body:
json
{
"orderHeader": [{
"transactionId": 82,
"salesRefNumber": "M0000286",
"orderNumber": 109593246,
"customerPONumber": "PO-2022-01-027",
"orderDate": "01/27/22",
"scheduledDate": "01/28/22",
"carrierId": "BW",
"orderStatus": "80",
"orderStatusDescription": "Partial Shipment",
"taxAmount": 72.50,
"totalAmount": 1010.00,
"currencyId": "USD",
"invoiceDate": "01/28/22",
"paymentTermId": "09",
"invoiceNumber": 65426326,
"customerNumber": "000054602",
"parentCustomerNumber": "ASSOCPURC",
"shipDate": "01/28/22",
"shipViaDesc": "Ground Shipping",
"dueDate": "02/27/22",
"ppsNumber": 21942216,
"callBackURL": "https://workflow.example.com/callback/243833/OAUpdateCallback/4863287883744102164",
"orderHeaderUdf": [
{
"orderNumber": 109593246,
"fieldName": "employee_number",
"fieldDescription": "EMP123456"
},
{
"orderNumber": 109593246,
"fieldName": "user_id",
"fieldDescription": "jsmith"
}
],
"orderDetails": [
{
"orderNumber": 109593246,
"lineNumber": 1,
"itemNumber": "EN4356",
"quantityOrdered": 2,
"quantityShipped": 2,
"customerPOLine": 1300,
"manPartNo": "32MU59-B",
"itemDescription": "32IN 4K 3840X2160 LED LCD MONITOR"
},
{
"orderNumber": 109593246,
"lineNumber": 2,
"itemNumber": "EG1181",
"quantityOrdered": 1,
"quantityShipped": 0,
"customerPOLine": 1301,
"manPartNo": "KB-800",
"itemDescription": "WIRELESS KEYBOARD"
}
],
"waybill": [
{
"ppsNumber": 21942216,
"packageId": "001",
"waybillNumber": "1Z999AA10123456784"
}
],
"invoiceLine": [
{
"invoiceNumber": 65426326,
"invoiceLinesId": 1,
"customerPOLine": 1300,
"qtyInvoiced": 2,
"itemNo": "EN4356",
"itemPrice": 500.00,
"grossAmount": 1000.00,
"taxAmount": 72.50,
"manPartNo": "32MU59-B",
"itemDescription": "32IN 4K 3840X2160 LED LCD MONITOR",
"invoiceLineUdf": [
{
"documentLineNo": 1,
"fieldName": "warranty_code",
"fieldDescription": "3YR-ONS"
}
],
"serialNumber": [
{
"invoiceLinesId": 1,
"serialNumber": "SN123456789ABC"
},
{
"invoiceLinesId": 1,
"serialNumber": "SN987654321XYZ"
}
]
}
]
}]
}
Response Example
200 OK - Success Response
{
"status": 200,
"message": "Order update processed successfully"
}400 Bad Request - Invalid Payload
{
"error": {
"code": "INVALID_REQUEST",
"message": "Invalid order update payload format"
}
}Error Handling & Retry Logic
- Connectivity Issues: Automatic retry with exponential backoff (1s, 2s, 4s intervals)
- Authentication Failures: OAuth token refresh with automatic retry
- Timeout Handling: 30-second timeout per attempt with retry on timeout
- Final Failure: After 3 failed attempts, error details are logged and returned to the backend system
POST /v2/order
Flow Type: Synchronous
Response Code: 201 Created
Version: 2.0
Authentication: OAuth 2.0
Description
This endpoint provides the same order creation functionality as /order but uses OAuth 2.0 authentication instead of Basic Auth. This version is maintained as part of the API versioning strategy to support clients requiring OAuth-based authentication.
Features
- OAuth 2.0 Authentication: Token-based authentication with automatic refresh
- Identical Functionality: Same validation, routing, and processing as
/order - Version Isolation: Future breaking changes will be isolated to this versioned endpoint
âšī¸ Version Strategy
This endpoint is maintained for API versioning and authentication flexibility. Future breaking changes to the order creation logic will be implemented in this versioned endpoint for OAuth clients, while/ordercontinues to serve clients using Basic Authentication.
Request & Response
The request and response formats are identical to the POST /order endpoint, with the only difference being the authentication method.
Authentication Header:
Authorization: Bearer <oauth-access-token>
Data Models
Create Order Request Schema
{
"order": [{
"customerNumber": "string (optional, max 9)",
"parentCustomerNumber": "string (required, max 14)",
"entryDate": "string (required, format: MM/DD/YY)",
"requestedDate": "string (required, format: MM/DD/YY)",
"customerPONumber": "string (required, max 25)",
"shipCustomerName": "string (required, max 35)",
"shipAddress1": "string (required)",
"shipAddress2": "string (optional, max 35)",
"shipAddress3": "string (optional, max 35)",
"shipCity": "string (required)",
"shipState": "string (required, max 2)",
"shipZipCode": "string (required, max 9)",
"shipCountry": "string (required, max 3)",
"shipPhone": "string (optional, max 25)",
"requestedForEmail": "string (optional, max 250)",
"requestedByEmail": "string (optional, max 250)",
"requestedForName": "string (optional, max 50)",
"requestedForPhone": "string (optional, max 50)",
"customerPOReleaseNumber": "string (optional, max 35)",
"shipPartially": "boolean (optional)",
"viaCode": "string (optional, max 2)",
"geoCode": "integer (optional, 0-999999999)",
"token": "string (optional, max 20)",
"creditCardType": "string (optional, max 30)",
"tokenName": "string (optional)",
"threeDeltaExpire": "string (optional, max 5, format: MM/YY)",
"partnerBillingStreet": "string (optional, max 50)",
"partnerBillingZip": "string (optional, max 10)",
"callBackURL": "string (optional, max 250)",
"salesRefNumber": "string (optional, max 8)",
"orderDetails": [{
"customerPOLine": "integer (optional, 0-999999999)",
"orderLine": "integer (required, 0-999999999)",
"quantityOrdered": "integer (required, 0-999999999)",
"price": "number (required, multipleOf: 0.01)",
"itemNumber": "string (required)",
"description": "string (required)",
"manPartNo": "string (optional)"
}],
"udf": [{
"fieldNumber": "integer (optional, 0-99)",
"fieldLevel": "string (optional, max 1)",
"fieldName": "string (optional)",
"fieldDescription": "string (optional, max 250)",
"orderLine": "integer (optional, 0-999)"
}],
"memo": [{
"orderLine": "integer (optional, 0-999)",
"type": "string (optional, max 3)",
"comments": "string (optional, max 32000)"
}]
}]
}Update Order Request Schema
{
"orderHeader": [{
"transactionId": "integer (optional, max 999999999)",
"salesRefNumber": "string (optional)",
"customerNumber": "string (optional)",
"parentCustomerNumber": "string (optional)",
"orderNumber": "integer (optional, max 999999999)",
"orderDate": "string (optional, format: MM/DD/YY)",
"scheduledDate": "string (optional, format: MM/DD/YY)",
"carrierId": "string (optional)",
"orderStatus": "string (optional)",
"orderStatusDescription": "string (optional)",
"taxAmount": "number (optional, multipleOf: 0.01)",
"totalAmount": "number (optional, multipleOf: 0.01)",
"currencyId": "string (optional)",
"invoiceDate": "string (optional, format: MM/DD/YY)",
"paymentTermId": "string (optional)",
"invoiceNumber": "integer (optional, max 999999999)",
"anticipatedArrivalDate": "string (optional, format: MM/DD/YY)",
"shipDate": "string (optional, format: MM/DD/YY)",
"shipViaDesc": "string (optional)",
"dueDate": "string (optional, format: MM/DD/YY)",
"ppsNumber": "integer (optional, max 999999999)",
"callBackURL": "string (optional)",
"orderDetails": [{
"orderNumber": "integer (optional, max 999999999)",
"lineNumber": "integer (optional, max 999)",
"itemNumber": "string (optional)",
"quantityOrdered": "integer (optional, 0-999999999)",
"quantityShipped": "integer (optional, 0-999999999)",
"customerPOLine": "integer (optional, 0-999999999)",
"manPartNo": "string (optional)",
"itemDescription": "string (optional)",
"orderLineUdf": [{
"documentLineNo": "integer (optional, max 999999999)",
"fieldName": "string (optional)",
"fieldDescription": "string (optional)"
}]
}],
"orderHeaderUdf": [{
"orderNumber": "integer (optional, max 999999999)",
"fieldName": "string (optional)",
"fieldDescription": "string (optional)"
}],
"waybill": [{
"ppsNumber": "integer (optional, max 999999999)",
"packageId": "string (optional)",
"waybillNumber": "string (optional)"
}],
"invoiceLine": [{
"invoiceNumber": "integer (optional, max 999999999)",
"invoiceLinesId": "integer (optional, max 999999999)",
"customerPOLine": "integer (optional, 0-999999999)",
"qtyInvoiced": "integer (optional, 0-999999999)",
"itemNo": "string (optional)",
"itemPrice": "number (optional, multipleOf: 0.01)",
"grossAmount": "number (optional, multipleOf: 0.01)",
"taxAmount": "number (optional, multipleOf: 0.01)",
"manPartNo": "string (optional)",
"itemDescription": "string (optional)",
"invoiceLineUdf": [{
"documentLineNo": "integer (optional, max 999999999)",
"fieldName": "string (optional)",
"fieldDescription": "string (optional)"
}],
"serialNumber": [{
"invoiceLinesId": "integer (optional, max 999999999)",
"serialNumber": "string (optional)"
}]
}]
}]
}Field Specifications
Create Order - Header Fields
| Field Name | Type | Required | Max Length | Description |
|---|---|---|---|---|
customerNumber | String | â No | 9 | The 'sold-to' customer number in the backend system |
parentCustomerNumber | String | â Yes | 14 | Parent customer number - used for client identification and routing |
entryDate | String | â Yes | - | Order entry date. Format: MM/DD/YY (e.g., 08/26/20) |
requestedDate | String | â Yes | - | Requested delivery date. Format: MM/DD/YY |
customerPONumber | String | â Yes | 25 | Client purchase order number |
shipCustomerName | String | â Yes | 35 | Ship-to recipient name |
shipAddress1 | String | â Yes | - | Primary shipping address line |
shipAddress2 | String | â No | 35 | Secondary shipping address line (optional) |
shipAddress3 | String | â No | 35 | Third shipping address line (optional) |
shipCity | String | â Yes | - | Shipping city |
shipState | String | â Yes | 2 | Two-letter state/province code (e.g., SC, NY, CA) |
shipZipCode | String | â Yes | 9 | Postal/ZIP code |
shipCountry | String | â Yes | 3 | Country code (e.g., US, CA, MX) |
shipPhone | String | â No | 25 | Shipping contact phone number |
requestedForEmail | String | â No | 250 | Email address of order recipient |
requestedByEmail | String | â No | 250 | Email address of order requester |
requestedForName | String | â No | 50 | Name of order recipient |
requestedForPhone | String | â No | 50 | Phone number of order recipient |
customerPOReleaseNumber | String | â No | 35 | Customer PO release number for blanket orders |
shipPartially | Boolean | â No | true/false | Allow partial shipments flag |
viaCode | String | â No | 2 | Shipping method code (e.g., bw = Best Way, pr = Priority) |
geoCode | Integer | â No | 0-999999999 | Geographic code for routing |
token | String | â No | 20 | Payment token for credit card transactions |
creditCardType | String | â No | 30 | Credit card type (e.g., Visa, MasterCard, Amex) |
tokenName | String | â No | - | Token identifier name |
threeDeltaExpire | String | â No | 5 | Payment token expiration date. Format: MM/YY |
partnerBillingStreet | String | â No | 50 | Partner billing street address |
partnerBillingZip | String | â No | 10 | Partner billing ZIP code |
callBackURL | String | â No | 250 | URL for asynchronous status callbacks |
salesRefNumber | String | â No | 8 | System-generated reference number. Auto-generated if not provided |
Create Order - Order Detail Fields
| Field Name | Type | Required | Max Length | Description |
|---|---|---|---|---|
customerPOLine | Integer | â No | 0-999999999 | Customer PO line number reference |
orderLine | Integer | â Yes | 0-999999999 | Line item sequence number (must be unique within order) |
quantityOrdered | Integer | â Yes | 0-999999999 | Quantity of items to order (must be > 0) |
price | Number | â Yes | multipleOf: 0.01 | Unit price (decimal format, e.g., 100.00) |
itemNumber | String | â Yes | - | SKU or item identifier from catalog |
description | String | â Yes | - | Item description |
manPartNo | String | â No | - | Manufacturer part number |
Create Order - UDF (User Defined Fields)
| Field Name | Type | Required | Max Length | Description |
|---|---|---|---|---|
fieldNumber | Integer | â No | 0-99 | UDF field number identifier |
fieldLevel | String | â No | 1 | Field level: H = Header, L = Line |
fieldName | String | â No | - | Custom field name/key |
fieldDescription | String | â No | 250 | Custom field value/description |
orderLine | Integer | â No | 0-999 | Associated order line number (0 = header level) |
Create Order - Memo Fields
| Field Name | Type | Required | Max Length | Description |
|---|---|---|---|---|
orderLine | Integer | â No | 0-999 | Associated order line number (0 = header level) |
type | String | â No | 3 | Memo type code (e.g., o = Order Memo) |
comments | String | â No | 32000 | Memo text/comments |
Update Order - Header Fields
| Field Name | Type | Required | Max Length | Description |
|---|---|---|---|---|
transactionId | Integer | â No | 0-999999999 | Unique transaction identifier |
salesRefNumber | String | â No | - | System-generated reference number |
customerNumber | String | â No | - | Customer number |
parentCustomerNumber | String | â No | - | Parent customer number |
orderNumber | Integer | â No | 0-999999999 | Backend system order number |
orderDate | String | â No | - | Order date. Format: MM/DD/YY |
scheduledDate | String | â No | - | Scheduled delivery date. Format: MM/DD/YY |
carrierId | String | â No | - | Carrier/shipping method code |
orderStatus | String | â No | - | Order status code (e.g., 10, 80, 90) |
orderStatusDescription | String | â No | - | Order status description (e.g., Open, Partial, Complete) |
taxAmount | Number | â No | multipleOf: 0.01 | Tax amount |
totalAmount | Number | â No | multipleOf: 0.01 | Total order amount |
currencyId | String | â No | - | Currency code (e.g., USD, CAD) |
invoiceDate | String | â No | - | Invoice date. Format: MM/DD/YY |
paymentTermId | String | â No | - | Payment terms code |
invoiceNumber | Integer | â No | 0-999999999 | Invoice number |
anticipatedArrivalDate | String | â No | - | Anticipated arrival date. Format: MM/DD/YY |
shipDate | String | â No | - | Shipment date. Format: MM/DD/YY |
shipViaDesc | String | â No | - | Shipping method description |
dueDate | String | â No | - | Payment due date. Format: MM/DD/YY |
ppsNumber | Integer | â No | 0-999999999 | Package processing system number |
callBackURL | String | â No | - | URL for asynchronous status callbacks |
Update Order - Order Detail Fields
| Field Name | Type | Required | Max Length | Description |
|---|---|---|---|---|
orderNumber | Integer | â No | 0-999999999 | Backend system order number |
lineNumber | Integer | â No | 0-999 | Order line number |
itemNumber | String | â No | - | SKU or item identifier |
quantityOrdered | Integer | â No | 0-999999999 | Quantity ordered |
quantityShipped | Integer | â No | 0-999999999 | Quantity shipped |
customerPOLine | Integer | â No | 0-999999999 | Customer PO line number |
manPartNo | String | â No | - | Manufacturer part number |
itemDescription | String | â No | - | Item description |
Update Order - Waybill Fields
| Field Name | Type | Required | Max Length | Description |
|---|---|---|---|---|
ppsNumber | Integer | â No | 0-999999999 | Package processing system number |
packageId | String | â No | - | Package identifier |
waybillNumber | String | â No | - | Tracking/waybill number (e.g., UPS, FedEx tracking) |
Update Order - Invoice Line Fields
| Field Name | Type | Required | Max Length | Description |
|---|---|---|---|---|
invoiceNumber | Integer | â No | 0-999999999 | Invoice number |
invoiceLinesId | Integer | â No | 0-999999999 | Invoice line identifier |
customerPOLine | Integer | â No | 0-999999999 | Customer PO line number |
qtyInvoiced | Integer | â No | 0-999999999 | Quantity invoiced |
itemNo | String | â No | - | Item number |
itemPrice | Number | â No | multipleOf: 0.01 | Item unit price |
grossAmount | Number | â No | multipleOf: 0.01 | Gross amount (before tax) |
taxAmount | Number | â No | multipleOf: 0.01 | Tax amount |
manPartNo | String | â No | - | Manufacturer part number |
itemDescription | String | â No | - | Item description |
Schema Validation Rules
Create Order - Required Fields Validation
| Field Name | Validation Rule | Error Code | Error Message |
|---|---|---|---|
parentCustomerNumber | Required, non-empty string, max 14 characters | 400 | Missing required field: parentCustomerNumber |
entryDate | Required, must match format MM/DD/YY | 400 | Invalid date format for entryDate. Expected: MM/DD/YY |
requestedDate | Required, must match format MM/DD/YY | 400 | Invalid date format for requestedDate. Expected: MM/DD/YY |
customerPONumber | Required, non-empty string, max 25 characters | 400 | Missing required field: customerPONumber |
shipCustomerName | Required, non-empty string, max 35 characters | 400 | Missing required field: shipCustomerName |
shipAddress1 | Required, non-empty string | 400 | Missing required field: shipAddress1 |
shipCity | Required, non-empty string | 400 | Missing required field: shipCity |
shipState | Required, exactly 2 characters | 400 | Invalid shipState. Must be 2-letter state code (e.g., SC, NY) |
shipZipCode | Required, non-empty string, max 9 characters | 400 | Missing required field: shipZipCode |
shipCountry | Required, 2-3 characters | 400 | Invalid shipCountry. Must be valid country code (e.g., US, CA) |
orderDetails | Required, must be non-empty array | 400 | Order must contain at least one order detail line |
Create Order - Order Details Required Fields
| Field Name | Validation Rule | Error Code | Error Message |
|---|---|---|---|
orderLine | Required, integer, range: 0-999999999 | 400 | Missing or invalid orderLine number |
quantityOrdered | Required, integer > 0, range: 0-999999999 | 400 | quantityOrdered must be greater than 0 |
price | Required, number, multipleOf: 0.01 | 400 | Invalid price format. Must be decimal (e.g., 100.00) |
itemNumber | Required, non-empty string | 400 | Missing required field: itemNumber |
description | Required, non-empty string | 400 | Missing required field: description |
Data Type Validations
| Data Type | Validation Rule | Example Valid | Example Invalid |
|---|---|---|---|
| String | Must be text, respect maxLength if specified | "John Doe" | 123 (number), true (boolean) |
| Integer | Must be whole number, respect min/max range | 100, 0, 999 | 100.5 (decimal), "100" (string) |
| Number | Must be numeric, can be decimal, respect multipleOf | 100.00, 65.44, 0.01 | "100.00" (string), 100.001 (invalid precision) |
| Boolean | Must be true or false (lowercase) | true, false | "true" (string), 1/0 (integer), TRUE (uppercase) |
| Date String | Must match format MM/DD/YY | "08/26/20", "12/31/25" | "2020-08-26", "26/08/20", "8/26/2020" |
| Array | Must be JSON array with proper brackets [] | [{...}, {...}] | {...} (object), "array" (string) |
Field Length Validations
| Field Group | Field Name | Max Length | Truncation Behavior |
|---|---|---|---|
| Address Fields | shipAddress1 | System-dependent | Validation error if exceeds limit |
shipAddress2 | 35 | Validation error if exceeds limit | |
shipAddress3 | 35 | Validation error if exceeds limit | |
| Email Fields | requestedForEmail | 250 | Validation error if exceeds limit |
requestedByEmail | 250 | Validation error if exceeds limit | |
| Code Fields | viaCode | 2 | Validation error if exceeds limit |
shipState | 2 | Validation error if exceeds limit | |
| Reference Numbers | customerPONumber | 25 | Validation error if exceeds limit |
salesRefNumber | 8 | Validation error if exceeds limit | |
| Comments | memo.comments | 32000 | Validation error if exceeds limit |
| UDF Description | udf.fieldDescription | 250 | Validation error if exceeds limit |
Numeric Range Validations
| Field Name | Minimum | Maximum | Special Rules |
|---|---|---|---|
orderLine | 0 | 999999999 | Must be unique within order |
quantityOrdered | 1 | 999999999 | Must be greater than 0 |
price | 0.00 | No limit | Must be multiple of 0.01 (two decimal places) |
customerPOLine | 0 | 999999999 | Optional field |
geoCode | 0 | 999999999 | Optional field |
udf.fieldNumber | 0 | 99 | User-defined field identifier |
udf.orderLine | 0 | 999 | Associates UDF with order line (0 = header level) |
memo.orderLine | 0 | 999 | Associates memo with order line (0 = header level) |
transactionId | 0 | 999999999 | Update order transaction identifier |
orderNumber | 0 | 999999999 | Backend system order number |
âšī¸ RAML Validation
All requests are validated against RAML 1.0 schema definitions using the MuleSoft APIKit Router. Invalid requests are rejected with HTTP 400 Bad Request before reaching the application logic, ensuring data integrity and security.
â ī¸ Validation Best Practices
- Always send numeric values as JSON numbers, not strings (e.g.,100not"100")
- Ensure dates follow the exact format: MM/DD/YY (e.g.,08/26/20)
- Use lowercase for boolean values:true/false
- Empty strings ("") are different from null/missing fields in validation
- Arrays must have at least one item if required (e.g.,orderDetails)
- Validate field lengths client-side to avoid unnecessary API calls
Error Handling
Error Response Format
All error responses follow a consistent format for easy parsing and error handling:
{
"error": {
"code": "ERROR_CODE",
"message": "Detailed error message describing what went wrong"
}
}HTTP Status Codes
| Status Code | Description | Common Causes | Resolution |
|---|---|---|---|
| 200 OK | Request successful | Order update processed successfully | N/A - Success response |
| 201 Created | Resource created successfully | New order created successfully | N/A - Success response |
| 400 Bad Request | Invalid request payload | Missing required fields, validation errors, invalid data format | Review request payload against schema documentation |
| 401 Unauthorized | Authentication failed | Invalid or missing credentials, expired token | Check credentials or refresh OAuth token |
| 403 Forbidden | Insufficient permissions | Client not authorized for requested operation | Contact support for access permissions |
| 404 Not Found | Resource not found | Invalid endpoint URL or order not found | Verify endpoint URL and resource identifiers |
| 408 Request Timeout | Request timeout | Backend system not responding within timeout period | Retry request after brief delay |
| 500 Internal Server Error | Server error | Backend connectivity issues, system errors, unexpected exceptions | Retry after delay; contact support if persists |
| 502 Bad Gateway | Backend system unavailable | Backend system down or unreachable | Retry after delay; check system status |
| 503 Service Unavailable | Service temporarily unavailable | System maintenance or overload | Retry with exponential backoff |
Common Error Codes
| Error Code | Description | Example Scenario |
|---|---|---|
VALIDATION_ERROR | Request validation failed | Missing required field or invalid format |
AUTHENTICATION_ERROR | Authentication failed | Invalid credentials or expired token |
BACKEND_ERROR | Backend system error | Unable to connect to DIMS or LCAM |
DATABASE_ERROR | Database operation failed | Unable to generate sales reference number |
ROUTING_ERROR | Client routing failed | Unknown parent customer number |
TIMEOUT_ERROR | Request timeout | Backend system response timeout |
SYSTEM_ERROR | Unexpected system error | Unhandled exception or system failure |
Retry Strategy
The API implements intelligent retry logic for transient failures:
- Automatic Retry: Failed requests are automatically retried up to 3 times
- Exponential Backoff: Retry intervals: 1 second, 2 seconds, 4 seconds
- Retry Conditions: Retries are attempted for:
- Network connectivity issues (502, 503, 504)
- Timeout errors (408)
- Transient backend errors (500 with retry-able flag)
- Non-Retry Conditions: No retry for:
- Validation errors (400)
- Authentication failures (401)
- Authorization failures (403)
- Resource not found (404)
Client Retry Recommendations:
Implement exponential backoff in client applications
Maximum retry attempts: 3-5
Initial retry delay: 1-2 seconds
Log all retry attempts for troubleshooting
đ¨ Error Monitoring
Critical errors trigger automated alerts for immediate investigation:
- Backend system connectivity failures
- Database connection issues
- Authentication/authorization failures
- High error rates exceeding thresholds
Alerts are sent to the operations team via email, Slack, and monitoring dashboards.
Authentication
The API supports two authentication methods to accommodate different client requirements and security policies.
Supported Authentication Methods
đ Basic Authentication
Traditional username and password authentication where credentials are base64-encoded in the Authorization header.
Use Case: Suitable for server-to-server integrations with secure credential storage.
Header Format:
Authorization: Basic <base64-encoded-credentials>
Example:
```
Username: api_user
Password: api_password
Base64 Encoded: YXBpX3VzZXI6YXBpX3Bhc3N3b3Jk
Header:
Authorization: Basic YXBpX3VzZXI6YXBpX3Bhc3N3b3Jk
```
Supported Endpoints:
POST /orderPOST /orderUpdate
đĢ OAuth 2.0
Token-based authentication with automatic token refresh. Provides enhanced security with time-limited access tokens and refresh capabilities.
Use Case: Recommended for client applications, web portals, and integrations requiring enhanced security.
Supported Grant Types:
Client Credentials
Resource Owner Password Credentials (ROPC)
Header Format:
Authorization: Bearer <oauth-access-token>
Supported Endpoints:
POST /v2/orderPOST /orderUpdate
OAuth 2.0 Token Endpoints
Development Environment
| Property | Value |
|---|---|
| Token URL | https://sandboxapi.compucom.com/oauth/token |
| Grant Type | client_credentials or password |
| Scope | read write (optional) |
Production Environment
| Property | Value |
|---|---|
| Token URL | https://prodapi.compucom.com/oauth/token |
| Grant Type | client_credentials or password |
| Scope | read write (optional) |
OAuth 2.0 Token Request
Client Credentials Grant:
POST /oauth/token HTTP/1.1
Host: sandboxapi.compucom.com
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=<your-client-id>
&client_secret=<your-client-secret>Response:
json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 300,
}
OAuth 2.0 Token Flow
The API implements intelligent OAuth token management with caching and automatic refresh:
1. Client requests API access
â
2. Check Object Store for cached token
â
3. If token exists and valid:
â Use cached token
4. If token missing or expired:
a. Request new token from OAuth provider
b. Cache token in Object Store with expiration
c. Use new token for API request
â
5. Make API request with Bearer token
â
6. If token expires during request:
â Automatic refresh and retryToken Caching Benefits:
Performance: Reduces authentication overhead by caching tokens
Efficiency: Minimizes calls to OAuth token endpoint
Reliability: Automatic token refresh ensures uninterrupted service
Scalability: Shared token cache across API instances
â Token Management Best Practices
- Cache tokens on the client side to reduce token requests
- Implement automatic token refresh before expiration
- Store tokens securely (never log or expose in URLs)
- Use HTTPS for all token requests and API calls
- Monitor token expiration and implement proactive refresh
Authentication Examples
Example 1: Order Creation with Basic Auth
curl -X POST https://muleqc.diam.compucom.com/api/standard-order/order \
-H "Content-Type: application/json" \
-H "Authorization: Basic YXBpX3VzZXI6YXBpX3Bhc3N3b3Jk" \
-d '{
"order": [{
"parentCustomerNumber": "799249461",
"entryDate": "08/26/20",
"requestedDate": "08/26/20",
"customerPONumber": "PO-2020-08-001",
"shipCustomerName": "John Doe",
"shipAddress1": "123 Main St",
"shipCity": "New York",
"shipState": "NY",
"shipZipCode": "10001",
"shipCountry": "US",
"orderDetails": [{
"orderLine": 1,
"quantityOrdered": 1,
"price": 100.00,
"itemNumber": "ITEM001",
"description": "Test Product"
}]
}]
}'Example 2: Order Creation with OAuth 2.0
# Step 1: Get OAuth Token
curl -X POST https://sandboxapi.compucom.com/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=your-client-id" \
-d "client_secret=your-client-secret"
# Response:
# {
# "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
# "token_type": "Bearer",
# "expires_in": 300
# }
# Step 2: Create Order with Token
curl -X POST https://muleqc.diam.compucom.com/api/standard-order/v2/order \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-d '{
"order": [{
"parentCustomerNumber": "799249461",
"entryDate": "08/26/20",
"requestedDate": "08/26/20",
"customerPONumber": "PO-2020-08-001",
"shipCustomerName": "John Doe",
"shipAddress1": "123 Main St",
"shipCity": "New York",
"shipState": "NY",
"shipZipCode": "10001",
"shipCountry": "US",
"orderDetails": [{
"orderLine": 1,
"quantityOrdered": 1,
"price": 100.00,
"itemNumber": "ITEM001",
"description": "Test Product"
}]
}]
}Standard Order Experience API | Version 1.0.0
Š 2026 CompuCom Systems, Inc. All rights reserved.
Last Updated: June 15, 2026