E-Commerce API for AI Agent Integration

The five backend systems presented a complex integration challenge:

• E-commerce platform - REST API with inconsistent JSON types (integers, floats, strings for the same field across different responses)
• E-commerce pricing service - Bearer token authentication returning session cookies for downstream APIs
• Financial services system - Portfolio holdings and account projections, optional for new users
• Portal API - Customer account details and transaction history
• Enquiries database - Legacy system with ad-hoc query interfaces

Each system used different authentication mechanisms (bearer tokens, cookies, API keys), different date formats, and different approaches to error handling. The API layer needed to abstract these differences while maintaining type safety.

Traditional web applications store user credentials in a local database and validate authentication requests against that database. This approach was not viable for several reasons:

• No user database available - The API was designed as a stateless gateway, not a full user management system
• Single source of truth - The e-commerce platform's existing authentication system was the authoritative source for token validity
• Synchronisation complexity - Maintaining a local copy of user credentials would require complex synchronisation logic and introduce consistency risks
• Security concerns - Storing credentials locally multiplies the attack surface and compliance requirements

Instead, the API acts as a proxy, validating tokens by calling the e-commerce platform's existing authentication endpoint. This keeps the API stateless while ensuring authentication decisions align with the platform's security policies.

The authentication system uses a hierarchical exception structure organised by the external system that failed:

• TokenNotFoundException - E-commerce API rejected the token
• MagentoUserNotFoundException - Token valid but user missing in Magento (sync issue)
• SoaNotFoundException - User has no SOA vault records (expected for new users)

Each exception maps to a specific HTTP status code and error message:

• TokenNotFoundException → 401 Bad Credentials (user should re-authenticate)
• MagentoUserNotFoundException → 503 Service Unavailable (temporary sync issue, contact support)
• SoaNotFoundException → Handled gracefully (empty vault collection, no error)

This granular approach enables the AI to provide appropriate user feedback instead of generic "authentication failed" messages. It also helps operations teams diagnose issues quickly by identifying which backend system caused the failure.

The authentication system implements several security measures beyond basic token validation:

• Token masking in logs - Only the first 4 and last 4 characters are logged, preventing token leakage while enabling support team debugging
• Log level attributes - Missing authorization headers log at INFO level (expected behaviour), while server errors log at ERROR level (requires investigation)
• Environment-aware error detail exposure - Development environments expose full exception details, production returns sanitised messages
• Rate limiting considerations - The 15-minute cache naturally rate limits authentication attempts (failed tokens aren't cached)

These measures balance security with debuggability, reducing alert fatigue while ensuring genuine security events are visible to operations teams.

The legacy e-commerce API's type inconsistencies were not theoretical. They appeared in real production responses:

• Price field variations:
  • Product A: "price": 100 (integer)
  • Product B: "price": 99.95 (float)
  • Product C: "price": "99.99" (string)
  • Product D: "final_price": "<span class=\"price\">47.22 USD$</span>" (HTML)
• Boolean inconsistencies:
  • "in_stock": true (boolean)
  • "in_stock": 1 (integer)
  • "in_stock": "true" (string)
  • "is_new": "0" (string zero)
• Category field chaos:
  • "categories": ["Gold", "Silver"] (string array)
  • "categories": [123, 456] (integer array)
  • "categories": ["Gold", 123] (mixed types!)

These variations likely arose from different code paths in the legacy platform. Some endpoints returned raw database values (integers), others ran through view helpers (strings or HTML), and older code paths used different type conventions. The denormaliser needed to handle all variations reliably.

The legacy e-commerce product response has an unusual structure that wraps products in multiple levels of nesting:

{
  "right": "ignored presentation content",
  "left": {
    "products": {
      "1761": {
        "tiers": { "tiers": [ {...}, {...} ] },
        "product": { "entity_id": "1761", ... }
      }
    }
  }
}

This structure comes from the legacy platform's frontend presentation layer, where "right" contains sidebar HTML and "left" contains main content. The API exposed this internal structure directly rather than providing a clean data-only response.

The denormaliser extracts products from data['left']['products'], discards the "right" content, and handles cases where intermediate levels (left, products) might be missing, null, or malformed. This defensive approach prevents API failures when the legacy platform's response structure varies.

Prices are stored as strings in the DTOs rather than being immediately converted to Money objects from the moneyphp/money library. This decision was driven by the legacy API's behaviour.

The legacy e-commerce API sometimes returns prices as HTML-formatted strings: <span class="price">47.22 USD$</span>. Immediate conversion to Money objects would require complex HTML parsing or result in data loss.

By storing prices as strings in DTOs, we preserve the original data exactly as received. Service layer code can then decide how to interpret each price field:

• Numeric strings ("99.99") convert cleanly to Money objects
• HTML strings parse to extract the numeric value or fall back to another field
• Invalid formats log warnings and use default values

This approach separates concerns: the denormaliser handles type coercion to get strings, while services handle business logic about which price field to use and how to interpret it. The trade-off is that services must explicitly convert strings to Money objects, but this is acceptable given the complexity of the upstream data.