Open API Documentation

Environment URLs

Authentication

All /openapi/v1 endpoints require signed request headers.

String to Sign

METHOD + "\n" +
PATH + "\n" +
TIMESTAMP + "\n" +
NONCE + "\n" +
SHA256(RAW_BODY)

Notes:

• Use uppercase METHOD, for example GET or POST.
• PATH contains only the request path, excluding domain and query string, for example /openapi/v1/orders.
• RAW_BODY must be the exact HTTP request body. For GET requests with no body, hash an empty string.
• X-Signature is the lowercase hexadecimal result of hash_hmac('sha256', stringToSign, AppSecret).

Node.js Signature Example

const crypto = require('crypto')

function sign({ method, path, timestamp, nonce, body, appSecret }) {
  const rawBody = body || ''
  const bodyHash = crypto.createHash('sha256').update(rawBody).digest('hex')
  const payload = [
    method.toUpperCase(),
    path,
    String(timestamp),
    nonce,
    bodyHash,
  ].join('\n')

  return crypto.createHmac('sha256', appSecret).update(payload).digest('hex')
}

PHP Signature Example

function openApiSign(string $method, string $path, string $timestamp, string $nonce, string $rawBody, string $appSecret): string
{
    $payload = strtoupper($method) . "\n"
        . $path . "\n"
        . $timestamp . "\n"
        . $nonce . "\n"
        . hash('sha256', $rawBody);

    return hash_hmac('sha256', $payload, $appSecret);
}

Conventions

Success Response Format

{
  "code": 200,
  "message": "success",
  "data": {}
}

Account Balance

Returns the current account balance and available amount.

{
  "code": 200,
  "message": "success",
  "data": {
    "account_id": 1,
    "name": "Partner A",
    "balance_usd_cents": 100000,
    "credit_limit_usd_cents": 0,
    "available_usd_cents": 100000
  }
}

Products

{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "product_id": 1001,
        "short_code": "ABC",
        "product_name": "Product A",
        "product_spec": "10mg",
        "warehouse_id": 1,
        "stock": 50,
        "weight_grams": 100,
        "unit_price_usd_cents": 1200,
        "is_promotion": 0
      }
    ],
    "total": 1
  }
}

Order Preview

Calculates product amount, shipping fee, total amount, and checks stock shortage or review status before creating the order.

{
  "external_order_no": "TP202605290001",
  "warehouse_id": 1,
  "shipping_method": "zhang",
  "customer_name": "John",
  "contact_type": "phone",
  "contact_value": "123456",
  "delivery_address": "Address line",
  "remark": "Partner order",
  "items": [
    {
      "product_id": 1001,
      "quantity": 2
    }
  ]
}

{
  "code": 200,
  "message": "success",
  "data": {
    "external_order_no": "TP202605290001",
    "status": "waiting_shipment",
    "presale_flag": 0,
    "anomaly_flag": 0,
    "goods_amount_usd_cents": 2400,
    "shipping_amount_usd_cents": 800,
    "total_amount_usd_cents": 3200,
    "linked_amount_usd_cents": 0,
    "payment_links": []
  }
}

Create Order

Creating an order deducts the amount from the Open API account balance and creates a confirmed Open API Balance payment record in ERP.

{
  "external_order_no": "TP202605290001",
  "warehouse_id": 1,
  "shipping_method": "zhang",
  "customer_name": "John",
  "contact_type": "phone",
  "contact_value": "123456",
  "delivery_address": "Address line",
  "remark": "Partner order",
  "confirm_presale": false,
  "items": [
    {
      "product_id": 1001,
      "quantity": 2
    }
  ]
}

{
  "code": 200,
  "message": "success",
  "data": {
    "external_order_no": "TP202605290001",
    "order_id": 123,
    "order_number": "V2605290001",
    "customer_order_number": "C2605290001",
    "status": "waiting_shipment",
    "amount_usd_cents": 3200,
    "payment_id": 456,
    "balance_usd_cents": 96800,
    "goods_amount_usd_cents": 2400,
    "shipping_amount_usd_cents": 800,
    "total_amount_usd_cents": 3200,
    "packages": [],
    "created_at": "2026-05-29 12:00:00"
  }
}

Order Detail

Query order status, amounts, and package information by partner order number.

Tracking

{
  "code": 200,
  "message": "success",
  "data": {
    "external_order_no": "TP202605290001",
    "order_number": "V2605290001",
    "status": "in_transit",
    "packages": [
      {
        "carrier": "Carrier",
        "tracking_number": "TRACK123",
        "tracking_image": "",
        "shipped_at": "2026-05-30 10:00:00"
      }
    ]
  }
}

Error Handling

For business failures, the HTTP status is usually still 200, but response code is not 200. Client systems should primarily check the response body code.

Failure Response Example

{
  "code": 500,
  "message": "Open API account balance is insufficient",
  "data": []
}

Integration Checklist

• You have received the production Base URL, AppKey, and AppSecret.
• Your server outbound IP has been provided to JYC for allowlisting.
• Call order preview before creating an order to confirm the amount.
• Order creation implements idempotent retry with external_order_no and Idempotency-Key.
• All amounts are handled in USD cents to avoid floating-point errors.