Working with Channels

Channels represent different sales platforms or sources for orders in the Unified Order Service. This guide explains how to create, configure, and manage channels through the API.

Channel Types

The UOS system supports various channel types, including:

  • Amazon
  • JET
  • Uber Eats
  • Just Eat
  • Salesforce
  • ICOM
  • Naveo Enterprise

Each channel type has specific configuration requirements and order schema definitions.

Creating a Channel

To create a new channel, send a POST request to the /v1/channels endpoint with the channel configuration.

Example Request

curl -X POST "https://api.uos.example.com/v1/channels" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Amazon US Store",
    "type": "amazon",
    "config": {
      "api_key": "your-amazon-api-key",
      "marketplace_id": "ATVPDKIKX0DER"
    }
  }'

Example Response

{
  "id": "channel-123",
  "name": "Amazon US Store",
  "type": "amazon",
  "config": {
    "api_key": "your-amazon-api-key",
    "marketplace_id": "ATVPDKIKX0DER"
  },
  "status": "active",
  "health": "unknown",
  "created_at": "2023-06-01T12:00:00Z",
  "updated_at": "2023-06-01T12:00:00Z"
}

Retrieving Channels

Getting a List of Channels

To retrieve a list of channels, send a GET request to the /v1/channels endpoint.

curl -X GET "https://api.uos.example.com/v1/channels" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameters:

  • page: Page number for pagination (default: 1)
  • limit: Number of channels per page (default: 10)

Getting a Specific Channel

To retrieve a specific channel, send a GET request to the /v1/channels/{channelId} endpoint.

curl -X GET "https://api.uos.example.com/v1/channels/channel-123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Updating a Channel

To update an existing channel, send a PUT request to the /v1/channels/{channelId} endpoint with the updated channel data.

curl -X PUT "https://api.uos.example.com/v1/channels/channel-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Amazon US Store - Updated",
    "type": "amazon",
    "config": {
      "api_key": "your-new-amazon-api-key",
      "marketplace_id": "ATVPDKIKX0DER"
    }
  }'

Channel Health Check

To check the health of a channel, send a POST request to the /v1/channels/{channelId}/health-check endpoint.

curl -X POST "https://api.uos.example.com/v1/channels/channel-123/health-check" \
  -H "Authorization: Bearer YOUR_API_KEY"

This will initiate a health check for the channel and update its health status.

Channel Order Schema

Each channel has a specific order schema that defines the required fields and format for creating orders in that channel. Understanding these schemas is crucial for correctly integrating with each sales channel.

Getting the Base Order Schema

To retrieve the base order schema (common fields for all channels), send a GET request to the /v1/channels/base-schema endpoint.

curl -X GET "https://api.uos.example.com/v1/channels/base-schema" \
  -H "Authorization: Bearer YOUR_API_KEY"

This returns the JSON Schema that defines standard fields required across all channel types.

Getting a Channel-Specific Schema

To retrieve the order schema for a specific channel, send a GET request to the /v1/channels/{channelId}/order-schema endpoint.

curl -X GET "https://api.uos.example.com/v1/channels/channel-123/order-schema" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes:

  • A JSON Schema defining all required and optional fields
  • Custom validations specific to the channel
  • Field format requirements
  • An example order for this channel type

Working with Channel Schemas

Each channel adapter provides:

  1. Schema Definition: Specifies required fields and their formats
  2. Field Validation: Ensures order data meets channel requirements
  3. Example Order: Demonstrates correctly formatted orders

Channel schemas are essential for:

  • Creating orders with the correct format for each channel
  • Transforming data between different systems
  • Validating orders before submitting them
  • Understanding data requirements for each integration

Schema Example Response

When requesting a channel's order schema, you'll receive a response like this:

{
  "schema": {
    "type": "object",
    "required": ["channel_id", "order_number", "order_date", "items", "channel_specific_data"],
    "properties": {
      "channel_id": {
        "type": "string",
        "description": "ID of the channel this order belongs to",
        "const": "uber-eats-channel-123"
      },
      "order_number": {
        "type": "string", 
        "description": "Order reference number"
      },
      // Additional schema properties...
    }
  },
  "example": {
    "channel_id": "uber-eats-channel-123",
    "order_number": "UE-1234567890",
    "order_date": "2023-08-15T14:30:00Z",
    // Example order data...
  }
}

Channel-Specific Data Fields

Each channel type requires specific data fields. For example:

Uber Eats

  • food_type for each item
  • restaurant_id in channel_specific_data
  • Customization options for menu items

Amazon

  • Amazon-specific identifiers (ASIN, order ID)
  • Marketplace information
  • Fulfillment details (MFN, FBA)

Salesforce

  • Salesforce record IDs
  • Business unit information
  • Customer account references

For specifics on each channel's requirements, see the Orders guide for detailed examples.

Channel Types Management

Getting Available Channel Types

To retrieve a list of available channel types, send a GET request to the /v1/channels/types endpoint.

curl -X GET "https://api.uos.example.com/v1/channels/types" \
  -H "Authorization: Bearer YOUR_API_KEY"

Adding a New Channel Type

To add a new channel type (requires admin access), send a POST request to the /v1/channels/types endpoint.

curl -X POST "https://api.uos.example.com/v1/channels/types" \
  -H "Authorization: Bearer SYSTEM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "new-channel-type"
  }'

Channel Configuration Examples

Here are examples of configuration settings for different channel types:

Amazon Channel

{
  "name": "Amazon US Store",
  "type": "amazon",
  "config": {
    "api_key": "your-amazon-api-key",
    "marketplace_id": "ATVPDKIKX0DER"
  }
}

Uber Eats Channel

{
  "name": "Uber Eats Integration",
  "type": "uber-eats",
  "config": {
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }
}

ICOM Channel

{
  "name": "ICOM Integration",
  "type": "icom",
  "config": {
    "store_id": "12345",
    "api_endpoint": "https://icom-api.example.com"
  }
}

Best Practices

  • Secure Credentials: Store API keys, client secrets, and other sensitive information securely.
  • Regular Health Checks: Periodically check the health of your channels to ensure they are functioning properly.
  • Consistent Naming: Use consistent naming conventions for your channels to make them easier to manage.
  • Documentation: Document the specific configuration requirements for each of your channels.
  • Testing: Test your channel configurations thoroughly before using them in production.
Last Updated: