Swagger Documentation

Swagger is an interactive API documentation tool that lets you explore, test, and understand ShipEdge Core API endpoints directly from your browser. Instead of reading static documentation, you can see all available endpoints, their parameters, and test them in real-time.

Quick Start

Access Swagger documentation at /apirest/v4/oms/docs for OMS endpoints or /apirest/v4/wms/docs for WMS endpoints. No authentication needed for OMS Swagger.

Why Use Swagger?

Interactive Testing

Test API endpoints directly from your browser without writing code or using command-line tools.

See Exact Parameters

View all required and optional parameters for each endpoint with descriptions and examples.

Understand Responses

See example responses for each endpoint to understand the data structure you’ll receive.

Explore Endpoints

Browse all available endpoints organized by category (Orders, Inventory, etc.) to discover functionality.

Validate Requests

Swagger validates your requests before sending, helping you avoid errors and understand requirements.

Copy Code Examples

Generate code examples in multiple languages (cURL, JavaScript, Python, etc.) from Swagger UI.

---

Available Swagger Documentation

ShipEdge Core provides Swagger documentation for different API versions and access levels:

REST API v4 (OMS)

URL: https://your-instance.shipedge.com/apirest/v4/oms/docs

Access: Public (no authentication required to view)

Features:

• Complete documentation of all OMS endpoints
• Interactive testing with authentication
• Request and response examples
• Parameter descriptions and validation
• Code generation for multiple languages

Endpoints Covered:

• Orders (create, list, get, update, cancel)
• Inventory (products, stock, aliases, synsets)
• Replenishments
• Returns
• Serial numbers
• Attributes
• Distribution centers
• Manufacture orders

REST API v4 (WMS)

URL: https://your-instance.shipedge.com/apirest/v4/wms/docs

Access: Requires WMS session authentication (must be logged in to WMS)

Features:

• Complete documentation of all WMS endpoints
• Interactive testing with warehouse credentials
• Request and response examples
• Parameter descriptions

Endpoints Covered:

• Order weight updates
• Inventory recounts
• Shipment operations
• Product bin information

Internal API (Restricted)

URL: https://your-instance.shipedge.com/apirest/v4/oms/internal/docs

Access: Requires VPN access (internal use only)

Features:

• Internal API endpoints documentation
• Restricted to internal network access

---

Accessing Swagger Documentation

OMS Swagger (Public Access)

1. Open your browser

   Navigate to your ShipEdge instance URL.

2. Go to Swagger URL

   Visit: https://your-instance.shipedge.com/apirest/v4/oms/docs

   Replace your-instance.shipedge.com with your actual ShipEdge instance URL.

3. View Documentation

   Swagger UI loads automatically showing all available endpoints organized by category.

WMS Swagger (Session Required)

1. Log in to WMS

   First, log in to your Warehouse Management System account.

2. Navigate to Swagger

   Visit: https://your-instance.shipedge.com/apirest/v4/wms/docs

   You must be logged in to WMS for this to work.

3. View Documentation

   Swagger UI loads showing all WMS endpoints.

---

Using Swagger UI

Exploring Endpoints

1. Browse Categories: Endpoints are organized by category (Orders, Inventory, etc.)
2. Expand Endpoints: Click on any endpoint to see details
3. View Parameters: See all required and optional parameters
4. Read Descriptions: Each parameter includes a description and example

Testing Endpoints

1. Select an Endpoint

   Click on an endpoint to expand it (e.g., POST /ping).

2. Click “Try it out”

   This enables interactive testing mode.

3. Enter Parameters

   Fill in required parameters:

   • Headers: Add AccountID and Key for OMS, or userName and Key for WMS
   • Body: Enter JSON data if required
   • Query Parameters: Add any query parameters

4. Click “Execute”

   Swagger sends the request and displays the response.

5. View Response

   See the response code, headers, and body data.

Authentication in Swagger

OMS Swagger:

• Add headers manually in the “Try it out” section
• Headers required: AccountID and Key
• Get credentials from My Account > Preferences > API Integration

WMS Swagger:

• Uses your current WMS session
• Additional headers may be required: userName and Key
• Get credentials from System Config > Preferences > Operations

Example: Testing Ping Endpoint

1. Find Ping Endpoint: Look for POST /ping in the Status section
2. Click “Try it out”
3. Add Headers:

   AccountID: 100
   Key: abcde12345

4. Click “Execute”
5. View Response:

   {
     "data": {
       "status": "Successful",
       "result": "pong!"
     }
   }

---

Swagger UI Features

Endpoint Information

Each endpoint shows:

• HTTP Method: GET, POST, PUT, PATCH, DELETE
• Path: The endpoint URL path
• Description: What the endpoint does
• Parameters: Required and optional parameters with descriptions
• Request Body: JSON schema for POST/PUT requests
• Responses: Example responses for different status codes
• Response Schema: Structure of response data

Code Generation

Swagger UI can generate code examples in multiple languages:

1. Click “Try it out” on any endpoint
2. Fill in parameters
3. Click “Execute”
4. Scroll down to see generated code examples
5. Select language: Choose from cURL, JavaScript, Python, PHP, Java, etc.
6. Copy code: Use the generated code in your application

Request Validation

Swagger validates your requests before sending:

• Required Fields: Highlights missing required parameters
• Data Types: Validates parameter types (string, integer, etc.)
• Format Validation: Checks email formats, dates, etc.
• Error Messages: Shows specific validation errors

---

Understanding Swagger Schemas

Request Schemas

Request schemas show the structure of data you need to send:

{
  "data": [
    {
      "order_number": "string",
      "shipping_method": "string",
      "customer": {
        "firstname": "string",
        "address1": "string",
        "city": "string",
        "state": "string",
        "zip": "integer",
        "country": "string"
      },
      "items": [
        {
          "sku": "string",
          "quantity": "integer"
        }
      ]
    }
  ]
}

Response Schemas

Response schemas show the structure of data you’ll receive:

{
  "data": {
    "order_id": "integer",
    "order_number": "string",
    "status": "string"
  },
  "metadata": {
    "page": "integer",
    "per_page": "integer",
    "total_records": "integer"
  }
}

---

💡 Best Practices

Test Before Coding

Use Swagger to test endpoints and understand responses before writing integration code.

Check Latest Version

Swagger documentation is updated automatically. Always check Swagger for the most current endpoint information.

Use Code Generation

Generate code examples from Swagger to ensure correct request formatting in your language.

Read Descriptions

Read parameter descriptions carefully to understand what each field does and when it’s required.

Test Error Cases

Try invalid requests in Swagger to see error responses and understand validation requirements.

Save Examples

Copy successful request examples from Swagger to use as templates in your code.

Check Response Codes

Review all possible response codes (200, 400, 401, etc.) to handle errors properly.

Use Latest Versions

When multiple versions are available (v1, v2, v3), use the latest version for best features and data.

---

Troubleshooting

Swagger Page Won’t Load

Common causes:

• Incorrect URL
• Network connectivity issues
• Server configuration problems

Solution:

1. Verify the URL is correct (/apirest/v4/oms/docs or /apirest/v4/wms/docs)
2. Check your internet connection
3. Try accessing from a different browser
4. Contact support if the issue persists

Can’t Test Endpoints

Common causes:

• Missing authentication headers
• Invalid credentials
• Endpoint requires specific permissions

Solution:

1. Ensure you’ve clicked “Try it out” to enable testing
2. Add required headers (AccountID and Key for OMS)
3. Verify your credentials are correct
4. Check that your account has necessary permissions

WMS Swagger Requires Login

Common causes:

• Not logged in to WMS
• Session expired
• Incorrect URL

Solution:

1. Log in to WMS first
2. Then navigate to /apirest/v4/wms/docs
3. Ensure you’re using the correct URL
4. Refresh the page if session expired

Response Shows Errors

Common causes:

• Invalid parameters
• Missing required fields
• Authentication issues
• Server errors

Solution:

1. Check error message in response body
2. Verify all required parameters are included
3. Validate parameter formats (strings vs integers)
4. Check authentication headers are correct
5. Review Swagger parameter descriptions

Code Generation Not Working

Common causes:

• Browser compatibility issues
• JavaScript disabled
• Swagger UI not fully loaded

Solution:

1. Use a modern browser (Chrome, Firefox, Edge)
2. Enable JavaScript
3. Wait for Swagger UI to fully load
4. Try refreshing the page

---

Swagger vs. API Documentation

Swagger:

• Interactive testing
• Real-time endpoint exploration
• Code generation
• Always up-to-date with code

Written Documentation:

• Detailed explanations
• Step-by-step guides
• Best practices
• Troubleshooting tips
• Use case examples

Use Both

Use Swagger for quick testing and exploration, and written documentation for detailed understanding and best practices.

---

Related Links

• API Overview - General API information and comparison
• REST API v4 (OMS) - Detailed OMS endpoints documentation
• REST API v4 (WMS) - Detailed WMS endpoints documentation
• API Authentication - Authentication guide
• Webhooks - Webhook configuration guide

---

Next Step: REST API v4 (OMS) - Learn to use OMS endpoints for order and inventory management