ERP Order Verification API Reference

This document provides technical details for developers working with the ERP Order Verification system. It covers the API endpoints, data structures, and implementation patterns.

Core Verification Methods

1. `fetchVerifiedOrderItems`

Located in src/services/erp/implementations/prophet21-service.ts, this private method fetches the actual order items from the P21 Data Services API.

private async fetchVerifiedOrderItems(
  connection: ERPConnection,
  erpOrderId: string
): Promise<Array<{ itemId: string; quantityOrdered: number; unitPrice: number; }> | null> {
  // ...implementation details...
}

Purpose: Makes a GET request to P21 Data Services API endpoint /data/erp/views/v1/p21_view_oe_line to retrieve the actual items in an order as recorded in the ERP system.

Parameters:

connection: ERPConnection object with authentication details
erpOrderId: The ERP order ID to verify

Returns: Array of verified items from the ERP or null if the request fails.

Error Handling: Returns null on API error and logs detailed error information.

2. `executeOrderVerification`

private async executeOrderVerification(
  connection: ERPConnection,
  erpOrderId: string,
  sentItems: Array<{ id: string; name: string; quantity: number; price: number; }>
): Promise<
  | { status: 'verified'; erpOrderId: string; verifiedItems: Array<{ itemId: string; quantityOrdered: number; unitPrice: number; }>; }
  | { status: 'mismatch'; erpOrderId: string; missingOrMismatchedItems: ErpUnverifiedItemDetail[]; verifiedItems: Array<{ itemId: string; quantityOrdered: number; unitPrice: number; }>; }
  | { status: 'verification_failed'; erpOrderId: string; error: { message: string; details?: any }; }
>

Purpose: Compares the items sent to the ERP with what was actually stored in the ERP system.

Parameters:

connection: ERPConnection object
erpOrderId: The ERP order ID to verify
sentItems: Array of items that were sent to the ERP

Returns: Verification result with appropriate status and details:

verified: All items match
mismatch: Some items missing or have quantity discrepancies
verification_failed: Error during verification process

API Endpoints

1. Generate Quote Endpoint

Path: /api/erp/orders/generate-quote
Method: POST
File: src/pages/api/erp/orders/generate-quote.ts

Request Payload:

{
  localOrderId: string; // ID of the extracted order
  erpCustomerId: string;
  customerName: string;
  erpCompanyId: string;
  erpShipToId: string;
  poNumber: string;
  items: Array<{
    erpItemId: string;
    quantity: number;
    price: number;
    name: string;
    productId: string;
    unitOfMeasure?: string;
    isDeleted?: boolean;
  }>;
}

Response (Success):

{
  erpOrderNumber: string;
  orderId: string;
  warnings: string[];
  verificationStatus: 'verified' | 'mismatch' | 'verification_failed' | null;
  verificationMessage: string;
  unverifiedItems: ErpUnverifiedItemDetail[];
}

Response (Error):

{
  error: string;
  erpMessage?: string;
}

2. Update Quote Endpoint

Path: /api/erp/orders/[id]/update-quote
Method: PUT
File: src/pages/api/erp/orders/[id]/update-quote.ts

Request Payload:

{
  items: Array<{
    erpItemId: string;
    quantity: number;
    price: number;
    name?: string;
    unitOfMeasure?: string;
  }>;
  erpCustomerId?: string;
  erpShipToId?: string;
  poNumber?: string;
}

Response (Success):

{
  erpOrderNumber: string;
  verificationStatus: 'verified' | 'mismatch' | 'verification_failed' | null;
  verificationMessage: string;
  unverifiedItems: ErpUnverifiedItemDetail[];
}

Response (Error):

{
  error: string;
  erpMessage?: string;
}

Data Types

1. ErpUnverifiedItemDetail

interface ErpUnverifiedItemDetail {
  id: string; // erpItemId
  name: string; // Item name
  sentQuantity: number; // Quantity that was sent to ERP
  erpQuantity?: number; // Quantity found in ERP (if item exists but with different quantity)
  reason: 'missing' | 'quantity_mismatch'; // Why the item failed verification
}

2. VerificationResult

type VerificationResult =
  | { status: 'verified'; erpOrderId: string; verifiedItems: P21VerifiedItem[] }
  | {
      status: 'mismatch';
      erpOrderId: string;
      missingOrMismatchedItems: ErpUnverifiedItemDetail[];
      verifiedItems: P21VerifiedItem[];
    }
  | {
      status: 'verification_failed';
      erpOrderId: string;
      error: { message: string; details?: any };
    };

3. P21VerifiedItem

interface P21VerifiedItem {
  itemId: string; // from p21_view_oe_line.item_id
  quantityOrdered: number; // from p21_view_oe_line.qty_ordered
  unitPrice: number; // from p21_view_oe_line.unit_price
}

Database Schema

The verification system adds these fields to the orders table:

erpVerificationStatus: text('erp_verification_status').default('pending');
erpUnverifiedItemIds: jsonb('erp_unverified_item_ids').$type<ErpUnverifiedItemDetail[]>();

Frontend Integration

1. Store Management

The verification data is managed in pdfOrderStore.ts. Key properties:

// In ExtractedOrderData interface
erpVerificationStatus?: 'verified' | 'mismatch' | 'verification_failed' | 'pending' | null;
erpUnverifiedItemDetails?: ErpUnverifiedItemDetail[] | null;

// Store atom for displaying verification messages
submissionMessage = atom<string | null>(null);

2. API Calls

The store has two methods that interact with verification:

generateQuoteInERP - Creates a new quote and processes verification results
updateQuoteInERP - Updates an existing quote and processes verification results

Both methods handle the verification data in a similar way:

// Example from updateQuoteInERP (simplified)
const updatedOrder = { ...orderToUpdate };
if (data.verificationStatus) updatedOrder.erpVerificationStatus = data.verificationStatus;
if (data.unverifiedItems) updatedOrder.erpUnverifiedItemDetails = data.unverifiedItems;
editingOrder.set(updatedOrder);
if (data.verificationMessage) submissionMessage.set(data.verificationMessage);

Implementation Notes

Data Services API vs Transaction API: The verification system uses the P21 Data Services API (/data/erp/views/v1/p21_view_oe_line) because the transaction-based approach failed with 400 errors.
Error Handling Strategy: The system logs details at various levels but keeps user-facing errors actionable and context-appropriate.
Verification Timing: Verification runs immediately after successful order creation or update. It’s a separate process from the order creation/update itself.
Persistence Strategy: Verification data is stored in the database to ensure it’s available after page refreshes or navigation.
Backward Compatibility: The verification functionality is designed as an enhancement, not a requirement. If verification fails, the order creation/update is still considered successful.

Debugging Tips

Look at the erpVerificationStatus and erpUnverifiedItemIds fields in the order record
Check the logs for calls to fetchVerifiedOrderItems and executeOrderVerification
Verify that the P21 Data Services API is accessible (may require different permissions than the transaction API)
If verification is failing, check the error details in the logs

Known Limitations

The verification depends on the P21 Data Services API, which may have different permissions or availability than the transaction API
Verification is a point-in-time check and does not continuously monitor the order
Some order modifications in the ERP might not be detected if they don’t affect item IDs or quantities