Skip to content

Overview

The 3 Clicks API enables external systems to securely interact with your 3 Clicks environment using RESTful endpoints. This guide outlines authentication, request formats, and common usage examples.

Quick Check - Before You Start
  • You have a valid API Key and API Secret from your 3 Clicks administrator.
  • For strict authentication, your integration can produce an HMAC-SHA256 signature and supply a Unix timestamp in seconds (not milliseconds).
  • You will URL-encode path and query values (e.g. / becomes %2F) wherever values appear in the request URL.

Getting Started

  • Contact your 3 Clicks administrator to obtain your API Key and API Secret

History Logs

Updates made via the Customer-facing API are now recorded in History Logs. You have a complete audit trail of all modifications, regardless of whether they were made through the UI or the API.

  • Access the API documentation at:
    https://[your-api-domain]/api-user-doc
  • Base URL for API requests:
    https://[your-api-domain]/api-user/v1/

Request and Response Format

All API requests should use standard REST conventions with the following specifications:

  • Use JSON in the request body
  • Include the header: Content-Type: application/json

Example Request

curl -X 'PUT' \
  'https://[your-api-domain]/api-user/v1/style/ecommerce/tags-create' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: your-api-key' \
  -H 'X-Api-Signature: your-signature' \
  -H 'X-Api-Timestamp: 1717128481' \
  -d '{
    "style_number": "A00416",
    "name": "Activewear"
  }'

Example Response

{
  "result": {
    "success": true,
    "code": "0",
    "message": "operate successfully."
  },
  "content": null
}

URL Encoding

When a parameter is included in the URL, ensure it is properly encoded.

Example:
If the parameter value is ABC/123, encode it as ABC%2F123:

/api-user/v1/shipping/basic/ABC%2F123

Authentication

Simple Authentication

Add the following headers to your request:

  • X-Api-Key: your API key
  • X-Api-Secret: your API secret
curl -X 'GET' \
  'https://[your-api-domain]/api-user/v1/style/basic/detail?style_number=SO00123' \
  -H 'accept: */*' \
  -H 'X-Api-Key: your-api-key' \
  -H 'X-Api-Secret: your-api-secret'

Strict Authentication

Add these headers:

  • X-Api-Key: your API key
  • X-Api-Signature: the HMAC_SHA256 encrypted signature
  • X-Api-Timestamp: current timestamp in seconds
curl -X 'GET' \
  'https://[your-api-domain]/api-user/v1/style/basic/detail?style_number=SO00123' \
  -H 'accept: */*' \
  -H 'X-Api-Key: your-api-key' \
  -H 'X-Api-Signature: your-signature' \
  -H 'X-Api-Timestamp: 1717127589'

Signature Verification

Step 1: Prepare the Data

Fields required:

  • api_key
  • api_secret
  • method (e.g. get, post)
  • data (JSON string of body)
  • timestamp (Unix time in seconds)

Concatenate all values (no separators):

[api_key][api_secret][method][data][timestamp]

Step 2: Generate Signature

Use HMAC with SHA256 encryption:

String secretKey = "your-api-secret";
String message = "your-message-to-sign";

Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
sha256_HMAC.init(secret_key);

byte[] hash = sha256_HMAC.doFinal(message.getBytes());
String signature = Hex.encodeHexString(hash);
Timestamps

Ensure that the timestamp is accurate to within 600 seconds of the server time.

Troubleshooting

Why am I getting 401 Unauthorized or signature errors?

Strict authentication requires a correct signature built from api_key, api_secret, method, data, and timestamp concatenated in order with no separators. Simple auth requires both X-Api-Key and X-Api-Secret headers. A wrong secret, wrong method casing, or wrong body string will fail verification.

Steps to resolve:

  1. Confirm you are using the authentication mode your endpoint expects (Simple vs Strict) and that all required headers are present.
  2. Rebuild the message string exactly as [api_key][api_secret][method][data][timestamp] where data is the JSON string of the body (use {} or the exact payload for empty bodies).
  3. Verify the X-Api-Signature is the lowercase hex HMAC-SHA256 of that message using your API secret as the key.
Why do requests fail with a timestamp or clock error?

The server allows only a limited skew (documented as 600 seconds) between your X-Api-Timestamp and server time. Stale timestamps, future timestamps, or using milliseconds instead of seconds will be rejected.

Steps to resolve:

  1. Ensure X-Api-Timestamp is Unix time in seconds (10 digits for current-era times).
  2. Sync your application or server clock with a reliable time source (NTP).
  3. Regenerate the signature immediately before sending so the timestamp matches the signed value.
Why does my GET or path parameter return 404 or wrong data?

Values embedded in the URL must be percent-encoded. Characters such as /, spaces, and & change how the path is parsed if left unencoded.

Steps to resolve:

  1. Encode each dynamic segment (e.g. ABC/123 as ABC%2F123) before placing it in the path.
  2. Encode query parameter values the same way when building query strings.
  3. Compare your final URL with the examples in this guide and with https://[your-api-domain]/api-user-doc for the exact path shape your endpoint expects.