Sales Order API (2.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 to /api/v1/sales-orders or /api/v2/sales-orders with the required authentication headers
5. Test with Postman — Use our Postman documentation and run the E2E Flow folder for end-to-end testing

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

We provide a Postman collection for integration testing. View the interactive documentation at:

PMPS Sales Order API — Postman Documentation

Use the E2E Flow folder in the Postman collection to run a full integration test:

1. Login — Obtain a JWT access token
2. Generate Signature — Generate X-SIGNATURE and X-TIMESTAMP headers (testing only)
3. Create Sales Order V1 or Create Sales Order V2 — Submit a sales order with authentication headers

The Generate Signature request in Postman calls POST /api/v1/auth/signature/generate, a helper endpoint for development and testing environments.

Important: This endpoint is not available in production. When NODE_ENV=production, the API returns 404 Not Found. In production, you must generate X-SIGNATURE locally using your RSA private key and the algorithm described in the Authentication section.

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

A single request may include more than 15 products. The API automatically splits the product list into multiple sales orders, with a maximum of 15 products per sales order. Each resulting order receives its own unique sales order code.

For example, a request with 34 products creates 3 sales orders containing 15, 15, and 4 products respectively.

On v1, the response shape is unchanged: data.code contains a comma-separated list of all created codes (e.g. SOP12500001,SOP12500002,SOP12500003). data.status and data.created_at reflect the first created order.

For a structured list of all created orders, use the v2 endpoint instead.

Version 2 sales order endpoints. Use v2 when you need the full list of created sales orders returned as an array — for example, when a large product list is split into multiple orders.