Sales Order API (1.0)

Welcome to the Sales Order API. This API enables Versuni system to create sales orders in our database through secure API requests.

The Sales Order API is designed to handle sales order creation and management with robust authentication and security measures.

This API serves as a bridge between the Versuni system and our database, allowing secure creation and management of sales orders. The system validates partner credentials and ensures data integrity through JWT authentication and RSA signature verification.

To start using this API:

1. Obtain Credentials: Contact our team to get your client_id and client_secret
2. Generate Keys: Create an RSA key pair and send us your public key in x.509 format
3. Authenticate: Use the /api/v1/auth/login endpoint to obtain a JWT token
4. Create Orders: Send sales order requests with proper authentication headers

The Versuni Sales Order API uses a two-layer authentication system to ensure secure communication:

1. JWT Token Authentication: Bearer token for API access
2. RSA Signature Verification: Request signature validation using X-SIGNATURE header

Before making any API requests, you must obtain a JWT token by calling the /api/v1/auth/login endpoint with your client_id and client_secret.

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
}

The JWT token will be valid for 12 hours. After expiration, you can refresh it using the /api/v1/auth/refresh endpoint.

For creating sales orders, you must include an X-SIGNATURE header in addition to the JWT token. This signature ensures the request authenticity.

X-SIGNATURE Generation Formula:

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

Requirements:

• PrivateKey: Your RSA private key (keep this secret!)
• PublicKey: You must provide your public key in x.509 format to our team for signature verification

Example Public Key Format (x.509):

-----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-----

When creating a sales order, include the following headers:

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

Header Validation:

• The client_id from the JWT token must match the X-CLIENT-ID header
• The X-SIGNATURE will be verified using your registered public key
• The X-TIMESTAMP should be the current timestamp used in signature generation

If your JWT token expires, you can refresh it without re-authenticating:

Request Example:

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

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

Response:

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

• Never share your client_secret or private key
• Store credentials securely using environment variables or secret management systems
• Rotate your keys periodically for enhanced security
• Monitor your API usage for any suspicious activity