Channels API Reference

This page documents the Channels endpoints in the Core API.

List Channels

Returns a paginated list of sales channels.

URL: /v1/channels

Method: GET

Auth required: Yes

Parameters:

Parameter	Type	Required	Description
`page`	integer	No	Page number for pagination (default: 1)
`limit`	integer	No	Number of items per page (default: 10)

Example Request:

curl -X GET "https://api.uos.example.com/v1/channels?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response:

Code: 200 OK
Content:

{
  "data": [
    {
      "id": "channel-123",
      "name": "Amazon US Store",
      "type": "amazon",
      "status": "active",
      "health": "healthy",
      "capabilities": {
        "supports_webhooks": true,
        "supports_order_sync": true
      },
      "created_at": "2023-06-01T10:00:00Z",
      "updated_at": "2023-06-01T10:00:00Z"
    },
    {
      "id": "channel-456",
      "name": "Uber Eats Integration",
      "type": "uber-eats",
      "status": "active",
      "health": "healthy",
      "capabilities": {
        "supports_webhooks": true,
        "supports_order_sync": true
      },
      "created_at": "2023-06-01T11:00:00Z",
      "updated_at": "2023-06-01T11:00:00Z"
    }
  ],
  "pagination": {
    "total": 2,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}

Get Channel by ID

Returns detailed information about a specific sales channel.

URL: /v1/channels/{channelId}

Method: GET

Auth required: Yes

Example Request:

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

Success Response:

Code: 200 OK
Content:

{
  "id": "channel-123",
  "name": "Amazon US Store",
  "type": "amazon",
  "config": {
    "api_key": "masked-for-security",
    "marketplace_id": "ATVPDKIKX0DER"
  },
  "status": "active",
  "health": "healthy",
  "capabilities": {
    "supports_webhooks": true,
    "supports_order_sync": true
  },
  "settings": {
    "auto_sync": true
  },
  "webhook_url": "https://webhook.example.com/amazon-callback",
  "webhook_secret": "masked-for-security",
  "webhook_enabled": true,
  "webhook_events": ["order:created", "order:updated"],
  "created_at": "2023-06-01T10:00:00Z",
  "updated_at": "2023-06-01T10:00:00Z",
  "last_sync": "2023-06-01T12:00:00Z"
}

Error Responses:

Code: 404 Not Found
- Content: { "error": "Channel not found" }

Create Channel

Creates a new sales channel in the system.

URL: /v1/channels

Method: POST

Auth required: Yes

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Display name of the channel
`type`	string	Yes	Type of the sales channel
`config`	object	Yes	Channel configuration settings
`settings`	object	No	Channel-specific settings
`metadata`	object	No	Additional metadata

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"
    },
    "settings": {
      "auto_sync": true
    },
    "metadata": {
      "team_owner": "sales-team"
    }
  }'

Success Response:

Code: 201 Created
Content:

{
  "id": "channel-123",
  "name": "Amazon US Store",
  "type": "amazon",
  "config": {
    "api_key": "masked-for-security",
    "marketplace_id": "ATVPDKIKX0DER"
  },
  "status": "active",
  "health": "unknown",
  "capabilities": {
    "supports_webhooks": true,
    "supports_order_sync": true
  },
  "settings": {
    "auto_sync": true
  },
  "metadata": {
    "team_owner": "sales-team"
  },
  "created_at": "2023-06-01T10:00:00Z",
  "updated_at": "2023-06-01T10:00:00Z"
}

Error Responses:

Code: 400 Bad Request
- Content: { "error": "Invalid channel data" }

Update Channel

Updates an existing sales channel configuration.

URL: /v1/channels/{channelId}

Method: PUT

Auth required: Yes

Request Body: Same as for creating a channel

Example Request:

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-updated-amazon-api-key",
      "marketplace_id": "ATVPDKIKX0DER"
    },
    "settings": {
      "auto_sync": false
    }
  }'

Success Response:

Code: 200 OK
Content:

{
  "id": "channel-123",
  "name": "Amazon US Store - Updated",
  "type": "amazon",
  "config": {
    "api_key": "masked-for-security",
    "marketplace_id": "ATVPDKIKX0DER"
  },
  "status": "active",
  "health": "unknown",
  "capabilities": {
    "supports_webhooks": true,
    "supports_order_sync": true
  },
  "settings": {
    "auto_sync": false
  },
  "created_at": "2023-06-01T10:00:00Z",
  "updated_at": "2023-06-01T14:00:00Z"
}

Error Responses:

Code: 400 Bad Request
- Content: { "error": "Invalid channel data" }
Code: 404 Not Found
- Content: { "error": "Channel not found" }

Check Channel Health

Initiates a health check for a specific sales channel.

URL: /v1/channels/{channelId}/health-check

Method: POST

Auth required: Yes

Example Request:

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

Success Response:

Code: 202 Accepted
Content:

{
  "message": "Health check initiated",
  "jobId": "job-456789",
  "channel_id": "channel-123"
}

Error Responses:

Code: 404 Not Found
- Content: { "error": "Channel not found" }

Get Order Schema Requirements

Retrieve JSON schema with required fields and format for creating orders in a specific channel.

URL: /v1/channels/{channelId}/order-schema

Method: GET

Auth required: Yes

Example Request:

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

Success Response:

Code: 200 OK
Content:

{
  "schema": {
    "type": "object",
    "properties": {
      "channel_id": {
        "type": "string",
        "description": "ID of the channel this order belongs to"
      },
      "order_number": {
        "type": "string",
        "description": "Order reference number"
      },
      // Additional channel-specific fields
    },
    "required": ["channel_id", "order_number", "items", "channel_specific_data"]
  },
  "channel_type": "amazon",
  "channel_id": "channel-123",
  "example": {
    "channel_id": "channel-123",
    "order_number": "AMZN-123-456",
    "items": [
      {
        "item_id": "item-123",
        "quantity": 2
      }
    ],
    "channel_specific_data": {
      "marketplace_id": "ATVPDKIKX0DER",
      "amazon_order_id": "123-4567890-1234567"
    }
  }
}

Error Responses:

Code: 404 Not Found
- Content: { "error": "Channel not found" }

Get Base Order Schema

Retrieve the base JSON schema with required fields and format for creating orders across all channels.

URL: /v1/channels/base-schema

Method: GET

Auth required: Yes

Example Request:

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

Success Response:

Code: 200 OK
Content:

{
  "schema": {
    "type": "object",
    "properties": {
      "channel_id": {
        "type": "string",
        "description": "ID of the channel this order belongs to"
      },
      "order_number": {
        "type": "string",
        "description": "Order reference number"
      },
      "order_date": {
        "type": "string",
        "format": "date-time",
        "description": "Date and time when the order was placed"
      },
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "item_id": {
              "type": "string",
              "description": "Unique identifier for the item"
            },
            "quantity": {
              "type": "number",
              "description": "Quantity of the item"
            }
          },
          "required": ["item_id", "quantity"]
        }
      }
    },
    "required": ["channel_id", "order_number", "items"]
  },
  "channel_type": "base",
  "example": {
    "channel_id": "channel-123",
    "order_number": "ORD-123",
    "order_date": "2023-06-01T12:00:00Z",
    "items": [
      {
        "item_id": "item-123",
        "quantity": 2
      }
    ]
  }
}

List Channel Types

Returns all available channel types that can be used when creating channels.

URL: /v1/channels/types

Method: GET

Auth required: Yes

Example Request:

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

Success Response:

Code: 200 OK
Content:

{
  "channel_types": [
    { "type_name": "amazon" },
    { "type_name": "jet" },
    { "type_name": "uber-eats" },
    { "type_name": "just-eat" },
    { "type_name": "salesforce" },
    { "type_name": "icom" },
    { "type_name": "naveo-enterprise" }
  ]
}

Add Channel Type

Adds a new channel type that can be used when creating channels.

URL: /v1/channels/types

Method: POST

Auth required: Yes (admin access required)

Request Body:

Field	Type	Required	Description
`type`	string	Yes	The new channel type to add

Example Request:

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

Success Response:

Code: 201 Created
Content:

{
  "success": true,
  "message": "Channel type 'new-marketplace' added successfully",
  "type": "new-marketplace"
}

Error Responses:

Code: 400 Bad Request
- Content: { "error": "Missing type" }
Code: 409 Conflict
- Content: { "error": "Channel type already exists" }