Article Type: Concept
Audience: Solution Architects, Application Designers, Developers, Partners
Module: Logistics / Materials Management
Applies to Versions: Fuuz Platform 2024.1+

1. Overview

The Integrated Carrier Package Ecosystem is a modular solution for multi-carrier shipping automation within the Fuuz Industrial Operations Platform. This package suite provides a unified abstraction layer enabling organizations to integrate with multiple shipping carriers such as FedEx and UPS while maintaining consistent data structures, workflows, and user interfaces across all carrier implementations.

The ecosystem consists of six interconnected packages that together deliver a comprehensive shipping management solution:

2. Architecture & Data Flow

Definitions

• Integrated Carrier: A shipping carrier entity (e.g., FedEx, UPS) configured within the platform with associated services, accounts, and connection settings.
• Carrier Service: A specific shipping service offered by a carrier (e.g., FedEx Ground, UPS Next Day Air) identified by a unique service code.
• Connection Configuration: Production and sandbox API connection settings for a carrier, including shipper account associations.
• Request Flow: A data flow mapped to a specific request type and carrier that handles the carrier-specific API communication.
• Request Type: A category of carrier operation such as Create Shipment, Void Shipment, Rate Shipment, Validate Address, or Print Labels.
• Billing Type: The party responsible for shipping charges (Sender, Receiver, or Third Party).
• Carrier Request: An audit record capturing the request/response data for each API call to a carrier.

Package Architecture

The Integrated Carrier ecosystem follows a layered architecture pattern:

┌─────────────────────────────────────────────────────────────────────┐
│                         ADDON LAYER                                  │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │  integrated-carrier-addon-plex                                │   │
│  │  • Plex ERP Integration • Load Plex Integrated Shipper Flow  │   │
│  └──────────────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────────────┤
│                     CARRIER IMPLEMENTATION LAYER                     │
│  ┌────────────────────────┐  ┌────────────────────────┐             │
│  │ integrated-carrier-    │  │ integrated-carrier-    │             │
│  │ fedex                  │  │ ups                    │             │
│  │ • FedEx Services       │  │ • UPS Services         │             │
│  │ • FedEx Billing Types  │  │ • UPS Billing Types    │             │
│  │ • Create/Void Flows    │  │ • Create/Void Flows    │             │
│  └────────────────────────┘  └────────────────────────┘             │
├─────────────────────────────────────────────────────────────────────┤
│                          CORE LAYER                                  │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────┐  │
│  │ core-schema     │  │ core-flows      │  │ core-screens        │  │
│  │ • 9 Data Models │  │ • Router Flow   │  │ • 20 Admin Screens  │  │
│  │ • Request Types │  │ • Print Labels  │  │ • Table & Form UIs  │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

Data Models (Core Schema)

The core schema package defines nine reference data models in the logistics/materialsManagement module:

Pre-populated Request Types

The core schema package pre-populates five standard request types:

Core Data Flows

The core-flows package provides two orchestration flows:

1. Integrated Carrier Router (integratedCarrierRouter) - 20 nodes

The central orchestration flow that routes carrier requests to the appropriate carrier-specific implementation based on request type. It performs validation, executes the mapped carrier flow via $executeFlow(), creates IntegratedCarrierRequest audit records, and updates shipment tracking/label data on success.

2. Integrated Carrier Print Labels Standard (integratedCarrierPrintLabelsStandard) - 12 nodes

Handles label printing by detecting label format (ZPL/ZPLII vs PDF) and routing to the appropriate print device. Uses devicePrintRaw for ZPL thermal labels and devicePrintDocument for PDF labels.

3. Use Cases

Multi-Carrier Shipping Automation

Configure multiple carriers (FedEx, UPS, or custom implementations) with production and sandbox environments. The unified abstraction layer allows your application to work with any carrier using consistent data structures and API patterns, reducing development effort and enabling carrier switching without code changes.

Rate Shopping

Query multiple carriers simultaneously for shipping rates before shipment creation. Compare costs across FedEx Ground, UPS Ground, and premium services to select the optimal carrier/service combination based on cost, delivery time, or other business rules.

Label Generation and Printing

Create shipments with carriers, receive tracking numbers and labels, then print labels to thermal (ZPL) or standard (PDF) printers. The Print Labels Standard flow automatically detects label format and routes to the appropriate device gateway for seamless integration with existing print infrastructure.

Address Validation

Validate ship-to addresses with carriers before shipment creation to prevent delivery failures and additional charges. Integrate address validation into order entry workflows to catch errors early in the process.

Shipment Tracking and Audit

Store tracking numbers, package labels, and charges on shipment records. The IntegratedCarrierRequest model provides a complete audit trail of all carrier API interactions, including raw request/response data for troubleshooting and compliance.

MCP/LLM Integration

Expose carrier operations as MCP (Model Context Protocol) tools for AI agents and LLMs on the Fuuz platform. Enable natural language shipping automation where users can say "Ship this order via FedEx Ground" and have the system execute the complete workflow automatically.

Plex ERP Integration

Connect Plex manufacturing system to carrier services using the addon-plex package. The "Load Plex Integrated Shipper" flow queries Plex data and creates corresponding IntegratedCarrierShipment records, enabling seamless shipping automation for Plex-managed orders.

4. Screen Details

The core-screens package provides 20 administrative screens organized as table/form pairs for each data model:

/materialsManagement/logistics/integratedCarriers

Administrative Routes

5. Technical Details

Carrier Implementations

FedEx Package (integrated-carrier-fedex v0.0.2)

UPS Package (integrated-carrier-ups v0.0.2)

GraphQL API Examples

Query Carriers with Services:

query {
  integratedCarriers {
    id
    name
    description
    services {
      id
      name
      code
    }
    billingTypes {
      id
      name
      code
    }
  }
}

Create a Shipment Record:

mutation($payload: [IntegratedCarrierShipmentCreatePayloadInput!]!) {
  createIntegratedCarrierShipment(payload: $payload) {
    id
    number
    trackingNumber
  }
}

Invoking the Router Flow

The Integrated Carrier Router is invoked with a request payload containing the shipment and request type:

{
  "integratedCarrierRequestTypeId": "createShipment",
  "shipment": {
    "id": "shipment-id-here",
    "integratedCarrierId": "fedex",
    "integratedCarrierServiceId": "fedex-ground-service-id",
    "integratedCarrierBillToAccountId": "fedex-shipper-account-id",
    "integratedCarrierConnectionConfigurationId": "fedex-config-id",
    "shipTo": { ... },
    "shipFrom": { ... },
    "packageDefinitions": [ ... ]
  }
}

Implementation Outcomes

Organizations implementing this package ecosystem can expect:

• Unified Carrier Abstraction: Single API pattern for all carriers eliminates carrier-specific code in applications
• Sandbox/Production Separation: Test carrier integrations without affecting production shipments
• Complete Audit Trail: Every carrier API call is logged with request/response data for compliance and troubleshooting
• Extensible Architecture: Add new carriers by implementing request flows and registering them via IntegratedCarrierRequestFlow
• Device-Agnostic Label Printing: Support for ZPL thermal printers and PDF printers through the gateway
• AI/LLM Ready: Data flows can be exposed as MCP tools for natural language automation
• ERP Integration: Ready-made Plex integration with extensible pattern for other ERP systems

6. Resources

• Fuuz Industrial Operations Platform
• FedEx Developer Portal - API documentation and sandbox access
• UPS Developer Kit - API documentation and testing tools
• Plex Systems - Plex ERP integration documentation

7. Troubleshooting

8. Revision History