Using Shipping Channels

This guide explains how to integrate with shipping providers using Shipping Channels.

What are Shipping Channels?

Shipping Channels are connections to different shipping providers (like DHL, DPD) that allow you to:

• Track parcels with consistent status updates
• Maintain unified access to multiple shipping providers
• Centralize shipping provider credentials

Available Shipping Providers

Shipping Channels currently supports the following providers:

Provider Code	Description
dhl	DHL International
dhl_pl	DHL Poland
dpd	DPD International
dpd_pl	DPD Poland
spx	Świat Przesyłek
mrw	MRW
poste_italiane	Poste Italiane

Creating a Shipping Channel

You can create shipping channels through the API or the dashboard. Each channel requires:

1. A unique name for identification
2. Provider selection (dhl, dhl_pl, dpd, dpd_pl)
3. Provider-specific credentials

Provider-Specific Settings

Each shipping provider requires different credential information:

DHL Settings

{
  "api_key": "your_dhl_api_key",
  "account_number": "your_dhl_account_number"
}

DHL Poland Settings

{
  "api_key": "your_dhl_pl_api_key",
  "account_number": "your_dhl_pl_account_number",
  "sap_number": "your_dhl_pl_sap_number"
}

DPD Settings

{
  "api_key": "your_dpd_api_key",
  "account_number": "your_dpd_account_number"
}

DPD Poland Settings

{
  "api_key": "your_dpd_pl_api_key",
  "account_number": "your_dpd_pl_account_number",
  "fid": "your_dpd_pl_fid"
}

SPX Settings

{
  "api_key": "your_spx_api_key"
}

MRW Settings

{
  "api_key": "your_mrw_api_key",
  "account_number": "your_mrw_account_number"
}

Poste Italiane Settings

{
  "api_key": "your_poste_italiane_api_key",
  "account_number": "your_poste_italiane_account_number"
}

Validating Shipping Channels

After creating a channel, you must validate the credentials. This ensures:

1. All required credentials are provided
2. The credentials grant proper access
3. The provider's API can be reached successfully

The validation process will:

1. Check all credentials format
2. Attempt to connect to the provider's API
3. Update the channel status to active if successful

If validation fails, the channel status remains pending_validation with error details.

Shipping Channel Statuses

Shipping channels can have the following statuses:

Status	Description
pending_validation	Newly created, awaiting validation
active	Validated and working correctly
inactive	Manually disabled by the user
error	Failed validation or encountered an error

Using Shipping Channels for Tracking

Once a shipping channel is validated and active, you can:

1. Create tracking parcels linked to the channel
2. Receive status updates automatically
3. Query tracking information through the API

Maintaining Shipping Channels

To ensure reliable service:

1. Monitor channel status via API or dashboard
2. Update credentials when they change or expire
3. Configure webhook notifications for channel status changes

Security Considerations

Shipping provider credentials are sensitive information. The API follows security best practices:

• API credentials are encrypted at rest
• Credential values are never exposed in API responses
• Access to shipping channels is restricted to their owners

Troubleshooting

Common issues with shipping channels include:

1. Invalid Credentials: Double-check all credential values
2. API Limits: Providers may enforce rate limits
3. Permissions: Ensure credentials have proper permissions
4. Network Issues: Check if provider API is accessible

When troubleshooting, utilize the validation endpoint to verify credentials and check the detailed error messages returned.