Sales Order API (1.0)

The Sales Order API provides a secure integration interface for authorized third-party applications to create and manage sales orders programmatically.

This API is intended for external partner systems that need to submit sales orders into our platform. All requests are authenticated and validated to ensure data integrity and secure communication.

The API acts as a secure gateway between external partner applications and our order management system. Partner credentials are validated on every request, and payload integrity is enforced through JWT authentication and RSA signature verification.

Follow these steps to begin integration:

1. Obtain credentials — Request a client_id and client_secret from our integration team
2. Register your public key — Generate an RSA key pair and submit your public key in X.509 PEM format
3. Authenticate — Call /api/v1/auth/login to obtain a JWT access token
4. Submit orders — Send sales order requests with the required authentication headers

This API uses a two-layer authentication model to protect all integration endpoints:

1. JWT bearer token — Grants API access for the authenticated partner session
2. RSA request signature — Validates request authenticity via the X-SIGNATURE header

Before calling protected endpoints, obtain a JWT access token by sending your client_id and client_secret to /api/v1/auth/login.

Request Example:

POST /api/v1/auth/login
Content-Type: application/json

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expired_at": 1704067200
}

Access tokens are valid for 12 hours. When a token expires, renew it using /api/v1/auth/refresh without re-submitting your client credentials.

Sales order requests require an X-SIGNATURE header in addition to the JWT bearer token. The signature confirms that the request originated from the registered partner and has not been tampered with.

Signature Algorithm

X-SIGNATURE = SHA256withRSA(PrivateKey, StringToSign)
StringToSign = client_id + "|" + X-TIMESTAMP

Key Requirements

• Private key — Your RSA private key; store securely and never share it
• Public key — Submit your public key in X.509 PEM format to our integration team for registration

Public Key Format (X.509 PEM)

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAomV+Vm1xlRXanmh108Ku
sls7SSKec0oCejtc9QGObpd4RnQ+7gihm2k6etnSNP7b+XrpY+fBkiQNaBInii9M
10kW9Bhf/M9GH/edL3IqnzDNSi7tcoQgnO7h8xmzLNWHTjtR6bkrsdBS5dry6hto
taF5KXomuoYgztCdGDOa0W20aeLzYSXIoW7s/Ay5yIXt0xaXTll3/bmezleguFPn
wQZq5EqZFWlUZvutDi+f2l9rTRY0Fb64y+VAf+mnIbEovGqsPEeF/p97YWxcY7CW
m8NsT0lwBVOtkmEl967Brz5yvEObF5bJgVodi6mNVsN1ki0MCitIhYO8shcE7eUi
lQIDAQAB
-----END PUBLIC KEY-----

Include the following headers when creating a sales order:

Required headers

Authorization: Bearer <JWT_TOKEN>
X-CLIENT-ID: <your-client-id>
X-TIMESTAMP: <current-unix-timestamp>
X-SIGNATURE: <generated-signature>
Content-Type: application/json

Validation Rules

• The client_id embedded in the JWT must match the X-CLIENT-ID header value
• The X-SIGNATURE is verified against your registered public key
• The X-TIMESTAMP must match the timestamp used when generating the signature

To renew an expired access token without re-authenticating:

Request Example:

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expired_at": 1704110400
}

• Never expose your client_secret or RSA private key in source code or logs
• Store credentials in environment variables or a dedicated secrets management service
• Rotate API credentials and signing keys on a regular schedule
• Monitor API activity and report any unauthorized access promptly

Endpoints for creating and managing sales orders submitted by authorized partner applications.