Carrier Integration

Karrio is designed to be easily extensible with new carrier integrations. This guide will walk you through the process of creating a custom carrier integration, from setting up the initial structure to implementing the specific API calls and data mapping.

Overview

Integrating a new carrier into Karrio involves several key steps:

1. Bootstrapping the Extension: Creating the initial package structure and boilerplate code
2. Generating Schemas: Converting carrier API documentation into Python types
3. Defining Metadata: Setting up carrier connection settings and data units
4. Implementing API Requests: Creating the communication layer with the carrier’s API
5. Mapping Data: Transforming between Karrio’s unified format and carrier-specific formats
6. Testing and Validation: Ensuring the integration works correctly

Prerequisites

Before you begin, make sure you have:

• A development environment set up for Karrio
• Basic knowledge of Python programming
• Access to the carrier’s API documentation
• Understanding of the carrier’s API request/response format

Extension Structure Overview

A Karrio carrier extension follows a standardized structure. Here’s the recommended structure:

1modules/connectors/[carrier_name]/
2├── setup.py                # Package setup file
3├── generate                # Schema generation script
4├── schemas/                # API schema files
5│   ├── rate_request.json   # (or .xsd for XML APIs)
6│   ├── rate_response.json
7│   └── ...
8└── karrio/
9    ├── plugins/            # Plugin registration (new structure)
10    │   └── [carrier_name]/
11    │       └── __init__.py    # Contains METADATA
12    ├── mappers/            # Integration layer
13    │   └── [carrier_name]/
14    │       ├── __init__.py    # Contains METADATA (legacy structure)
15    │       ├── mapper.py      # Data mapping functions
16    │       ├── proxy.py       # API client
17    │       └── settings.py    # Connection settings
18    ├── providers/          # Provider-specific code
19    │   └── [carrier_name]/
20    │       ├── __init__.py
21    │       ├── units.py       # Enums & constants
22    │       ├── utils.py       # Utility functions
23    │       ├── error.py       # Error handling
24    │       ├── rate.py        # Rating implementation
25    │       ├── tracking.py    # Tracking implementation
26    │       ├── shipment/      # Shipping implementation
27    │       │   ├── __init__.py
28    │       │   ├── create.py
29    │       │   └── cancel.py
30    │       └── ...
31    └── schemas/            # Generated API data types
32        └── [carrier_name]/
33            ├── __init__.py
34            ├── rate_request.py
35            ├── rate_response.py
36            └── ...

Extension Anatomy

At the core of Karrio’s design is a modular architecture that separates carrier integrations from the unified interface abstraction. Each carrier integration is contained in its own Python package, making it easy to add, update, or remove carriers without affecting the rest of the system.

Key Components

1. Metadata: Defined in the plugin’s __init__.py file (either in plugins/[carrier_name]/__init__.py or mappers/[carrier_name]/__init__.py), this identifies your extension to Karrio.

2. Settings: The settings.py file defines the connection parameters needed for the carrier’s API.

3. Proxy: The proxy.py file implements the API client that communicates with the carrier’s services.

4. Mapper: The mapper.py file contains functions that transform data between Karrio’s unified format and carrier-specific formats.

5. Schemas: Generated Python data types that represent the carrier’s API request and response structures.

Bootstrapping a New Extension

Karrio provides a CLI tool to quickly scaffold a new carrier extension. The tool creates all the necessary files and directories with the appropriate structure.

Run the extension creation command
1kcli add-extension

This will start an interactive process:

1Carrier slug: freight_express            # Unique carrier identifier (e.g., dhl_express, ups, fedex)
2Display name: Freight Express            # Human-readable carrier name (e.g., DHL, UPS, FedEx)
3Features [tracking, rating, shipping]:   # The features you want to implement
4Version [2024.3]:                        # The extension version
5Is XML API? [y/N]:                       # Whether the carrier uses XML for API communication

After confirmation, the tool will generate the extension structure in the modules/connectors/[carrier_name] directory.

Detailed Guides

To complete your carrier integration, follow these detailed guides:

• Schema Generation: Learn how to generate Python data types from carrier API documentation
• Metadata: Define carrier connection settings and data units
• API Requests: Implement API calls for different carrier operations
• Data Mapping: Transform data between Karrio’s unified format and carrier-specific formats

Final Steps

After implementing your carrier integration, you’ll need to:

1. Test your integration thoroughly with unit tests
2. Set up the carrier in the Karrio dashboard

Example Integrations

For reference, you can explore existing carrier integrations in the Karrio codebase:

• Canada Post
• DHL Express
• FedEx
• UPS

These integrations cover a variety of API types (REST, SOAP) and carrier features (rating, shipping, tracking, etc.).

Troubleshooting

If your carrier integration isn’t working correctly:

1. Check the extension structure matches the expected format
2. Ensure the METADATA object is properly defined in the __init__.py file
3. Verify all required dependencies are installed
4. Look for import errors in the application logs
5. Use get_failed_plugin_modules() to get information about plugins that failed to load

For more information on plugin loading and registration, see the Plugin Development Guide.