Integrated Carrier Package

Integrated Carrier Package

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:

Package	Version	Purpose
integrated-carrier-core-schema	0.0.1	Core data models for carrier integration (9 models)
integrated-carrier-core-flows	0.0.1	Orchestration flows for routing and label printing
integrated-carrier-core-screens	0.0.1	Administrative UI screens (20 screens with routes)
integrated-carrier-fedex	0.0.2	FedEx carrier implementation with services and flows
integrated-carrier-ups	0.0.2	UPS carrier implementation with services and flows
integrated-carrier-addon-plex	0.0.1	Plex ERP system integration addon

Note: Install packages in dependency order: core-schema first, then core-flows and core-screens, followed by carrier-specific packages (fedex, ups), and finally any addon packages (plex).

Note: The original KB article includes six downloadable .fuuz package files — integrated-carrier-core-schema0011.fuuz, integrated-carrier-core-flows0011.fuuz, integrated-carrier-core-screens0011.fuuz, integrated-carrier-fedex0021.fuuz, integrated-carrier-ups0021.fuuz, and integrated-carrier-addon-plex0011.fuuz. These files must be re-attached or linked in this repository; until then, download them from the original article.

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:

Data Model	Label Field	Key Fields	Relationships
IntegratedCarrier	name	id, name, description	services, accounts, billingTypes, requestFlows, connectionConfigurations, shipments
IntegratedCarrierService	name	id, name, code, description	integratedCarrier, shipments
IntegratedCarrierAccount	name	id, name, accountNumber, meterNumber, address, phoneNumber	integratedCarrier, integratedCarrierBillingType, shipments
IntegratedCarrierBillingType	name	id, name, code, description	integratedCarrier, accounts
IntegratedCarrierConnectionConfiguration	name	id, name, productionConnectionId, sandboxConnectionId, shipperIntegratedCarrierAccountId	integratedCarrier, productionConnection, sandboxConnection, shipperIntegratedCarrierAccount
IntegratedCarrierRequestType	label	id, label, description	flows, requests
IntegratedCarrierRequestFlow	—	id, integratedCarrierRequestTypeId, dataFlowId	integratedCarrierRequestType, integratedCarrier, dataFlow
IntegratedCarrierShipment	number	id, number, shipTo, shipToAddress, shipFrom, shipFromAddress, packageDefinitions, trackingNumber, packageLabels, totalCharges	integratedCarrier, integratedCarrierService, integratedCarrierBillToAccount, integratedCarrierConnectionConfiguration
IntegratedCarrierRequest	—	id, sandbox, error, request, rawRequest, response, errors, rawResponse	connection, integratedCarrierRequestType, integratedCarrierShipment

Note: All data models are GraphQL-exposed with full CRUD operations (create, update, delete) and 120-day data change capture retention for audit compliance.

Pre-populated Request Types

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

Request Type ID	Label	Description
createShipment	Create Shipment	Sends a shipment to a carrier and retrieves tracking number and labels
voidShipment	Void Shipment	Cancels an existing shipment with the carrier
rateShipment	Rate Shipment	Retrieves shipping rates for a proposed shipment
validateAddress	Validate Address	Validates the ship-to address with the carrier
printLabels	Print Labels	Prints labels returned by a carrier to configured devices

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 Edge 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.

Tip: Example MCP Tool Definition: The Integrated Carrier Router flow can be exposed as an MCP tool allowing LLMs to create shipments, rate shipments, validate addresses, print labels, and void shipments through natural language commands.

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

Route Path	Screen Type	Purpose
/materialsManagement/logistics/integratedCarriers	Table	List all configured carriers
/materialsManagement/logistics/integratedCarriers/:id	Form	View/edit carrier details
/materialsManagement/logistics/integratedCarrierServices	Table	List carrier services
/materialsManagement/logistics/integratedCarrierAccounts	Table	List carrier accounts
/materialsManagement/logistics/integratedCarrierBillingTypes	Table	List billing types per carrier
/materialsManagement/logistics/integratedCarrierConnectionConfigurations	Table	Manage API connections
/materialsManagement/logistics/integratedCarrierRequestTypes	Table	View request types
/materialsManagement/logistics/integratedCarrierRequestFlows	Table	Manage request-to-flow mappings
/materialsManagement/logistics/integratedCarrierShipments	Table	List shipments
/materialsManagement/logistics/integratedCarrierRequests	Table	View API request audit log

5. Technical Details

Carrier Implementations

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

Component	Details
Carrier ID	fedex
Services	FedEx Ground (FEDEX_GROUND), Standard Overnight (STANDARD_OVERNIGHT), Second Day (FEDEX_2_DAY)
Billing Types	Shipper (SENDER), Third Party (THIRD_PARTY), Receiver (RECIPIENT)
Data Flows	fedExCreateShipment, fedExVoidShipment

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

Component	Details
Carrier ID	ups
Services	Next Day Air (01), Second Day Air (02), Ground (03)
Billing Types	Shipper (BillShipper), Receiver (BillReceiver), Third Party (BillThirdParty)
Data Flows	upsCreateShipment, upsVoidShipment

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 Edge 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

Issue	Cause	Resolution
"No request flow found for carrier"	IntegratedCarrierRequestFlow not configured for the carrier/request type combination	Verify carrier package is installed and request flow record exists linking the carrier, request type, and data flow
"No ship to information provided"	Shipment missing required shipTo address data	Populate shipTo or shipToAddress field on the IntegratedCarrierShipment record
"No bill to account found"	Shipment missing billing account reference	Set integratedCarrierBillToAccountId on the shipment
Labels not printing	Edge Gateway not configured or device IDs incorrect	Verify Edge Gateway configuration and ensure correct device IDs are set in the Print Labels Standard flow
Carrier API authentication failure	Connection credentials expired or incorrect	Update credentials in the Connection record referenced by IntegratedCarrierConnectionConfiguration
Sandbox vs Production confusion	Using wrong connection configuration	Check IntegratedCarrierRequest.sandbox flag; ensure sandboxConnectionId is set for testing

Important: Review IntegratedCarrierRequest records for detailed error information. The rawRequest and rawResponse fields contain the complete carrier API payloads for debugging.

8. Revision History

Version	Date	Editor	Description
1.0	2025-01-24	Fuuz Documentation Team	Initial release documenting Integrated Carrier Package Ecosystem v0.0.1/v0.0.2

See Also

• Getting-started-with-Shipping-Creating-and-configuring-a-new-Integrated-Carrier
• Getting-started-with-Shipping-Creating-and-configuring-a-new-Integrated-Carrier-Shipment
• Getting-started-with-Shipping-Creating-and-configuring-a-new-Integrated-Carrier-Shipment-for-the-Plex-Package
• Fuuz-Standard-Packages
• Printing-Documents-From-Fuuz
• How-do-we-integrate-with-Plex-ERP

---

Source: support.fuuz.com