Orders Service API v1.0 Production Ready

Create Order API

Creates a new sales order transaction in Ananta 4PL logistics system, inserting header, audit history, and line item records with atomic transaction rollback safety.

POST https://www.ananta4pl.in/order/

Authentication & Permission Scopes

All requests require a valid API key supplied in the X-API-Key HTTP request header. The key is authenticated against active database credentials using SHA-512 with timing-safe hash comparison (hash_equals).

Mandatory Scope: The authenticated API key must include the write:orders scope (or the wildcard *). Requests without this permission fail immediately with HTTP 403 Forbidden.

Strict HTTPS SSL/HTTPS is mandatory; non-TLS returns 403 Forbidden.

X-API-Key Header Extracted and verified against active client records.

SHA-512 Timing-Safe Compared via hash_equals to prevent timing side-channels.

Rate Limiter Fixed 60-second window (default 60 req/min).

Headers & Preflight (CORS)

Header	Type	Requirement	Description
`X-API-Key`	string	Required	Client API secret token.
`Content-Type`	string	Required	Must be `application/json; charset=UTF-8`.
`Accept`	string	Optional	Expected response format: `application/json`.

CORS & Preflight: An HTTP OPTIONS request is supported and returns 200 OK with headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-API-Key

Order Header Schema

Field	Type	Requirement	Default	Description / Validation Rules
txn_date	string	Required	—	Transaction date. Formatted to `YYYY-MM-DD`.
assoc_ref	string	Required	—	External client order ID. Unique per client. Duplicate triggers `422 Unprocessable Entity`.
assoc_ref_date	string	Required	—	Date of the external reference (`YYYY-MM-DD`).
bill_to	string	Required	—	Billing account/client identifier (e.g. `CU001`).
cons_name	string	Required	—	Consignee recipient contact or business name.
cons_address	string	Required	—	Delivery shipping address.
cons_city	string	Required	—	Destination city (e.g. `Panchkula`).
cons_state	string	Required	—	2-digit Indian State Code (e.g. `06`, `07`).
cons_pin	string	Required	—	6-digit Indian PIN Code (e.g. `134109`).
items	array	Required	—	Non-empty array of line item objects.
doc_id	string	Optional	`SALO`	Order voucher/document series.
cons_phone	string	Optional	`NULL`	Consignee mobile phone number.
cons_gst	string	Optional	`NULL`	15-character GSTIN number of consignee.
backorder	string	Optional	`N`	Backorder allowance flag (`Y` or `N`).
txn_status	string	Optional	`Pending`	Initial transaction state.

Order Detail Items Schema

Field	Type	Requirement	Default	Description
prod_id	string	Required	—	Product SKU or identifier in Ananta 4PL catalog.
order_qty	number	Required	—	Quantity ordered.
price	number	Required	—	Selling unit price.
mrp	number	Required	—	Maximum Retail Price per unit.
unit	string	Optional	`EACH`	Unit of Measure (`EACH`, `BOX`, `KG`).
price_cur	string	Optional	`INR`	ISO currency code.
exch_rate	number	Optional	`1.00`	Exchange multiplier.
disc_p	number	Optional	`0`	Discount percentage.

Status Codes & Error Matrix

201 Created

Order Created

Order header, history, and detail lines inserted within transaction.

422 Unprocessable

Duplicate Order Ref

assoc_ref already exists in client history.

422 Validation Error

Missing Fields

Missing or empty required parameters (e.g. cons_pin or items).

401 Unauthorized

Auth Failure

Missing, malformed, deactivated API key or SHA-512 mismatch.

403 Forbidden

SSL / Scope Deficit

Non-HTTPS connection or key lacking write:orders scope.

400 Bad Request

Invalid JSON

Malformed syntax or empty body in HTTP POST.

429 Rate Limited

Limit Saturated

60 req/min threshold exceeded. Check X-RateLimit headers.

500 Server Error

Storage Exception

Database exception occurs; transaction rolled back.

Interactive API Playground

Order Dispatch Console

Simulate API behavior or inspect live headers.

Preset:

X-API-Key Header verification

JSON Request Body

Response Console

Awaiting dispatch...

// Ready to send. Responses will display status codes, headers, and payload here.

Integration Code Samples

curl --request POST \
  --url https://www.ananta4pl.in/order/ \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "txn_date": "2026-09-18",
    "doc_id": "SALO",
    "assoc_ref": "2026-27/001",
    "assoc_ref_date": "2026-09-18",
    "bill_to": "CU001",
    "cons_name": "Malhotra Books",
    "cons_address": "SCF-14, Sect-15",
    "cons_city": "Panchkula",
    "cons_state": "06",
    "cons_pin": "134109",
    "cons_phone": "9988776655",
    "items": [
      {
        "prod_id": "TESTPRD0001",
        "order_qty": 200,
        "price": 399,
        "mrp": 499
      }
    ]
  }'

<?php
$payload = [
    "txn_date"       => "2026-09-18",
    "doc_id"         => "SALO",
    "assoc_ref"      => "2026-27/001",
    "assoc_ref_date" => "2026-09-18",
    "bill_to"        => "CU001",
    "cons_name"      => "Malhotra Books",
    "cons_address"   => "SCF-14, Sect-15",
    "cons_city"      => "Panchkula",
    "cons_state"     => "06",
    "cons_pin"       => "134109",
    "cons_phone"     => "9988776655",
    "items"          => [
        [
            "prod_id"   => "TESTPRD0001",
            "order_qty" => 200,
            "price"     => 399,
            "mrp"       => 499
        ]
    ]
];

$ch = curl_init("https://www.ananta4pl.in/order/");
$json = json_encode($payload);

curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $json,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_HTTPHEADER     => [
        "X-API-Key: " . $apiKey,
        "Content-Type: application/json; charset=UTF-8",
        "Content-Length: " . strlen($json)
    ]
]);

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);
if ($http_code === 201) {
    echo "Order created successfully! Ref: " . $result['assoc_ref'];
} else {
    echo "Error [{$http_code}]: " . ($result['message'] ?? 'Unknown Error');
}

const response = await fetch('https://www.ananta4pl.in/order/', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ANANTA_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    txn_date: '2026-09-18',
    doc_id: 'SALO',
    assoc_ref: '2026-27/001',
    assoc_ref_date: '2026-09-18',
    bill_to: 'CU001',
    cons_name: 'Malhotra Books',
    cons_address: 'SCF-14, Sect-15',
    cons_city: 'Panchkula',
    cons_state: '06',
    cons_pin: '134109',
    cons_phone: '9988776655',
    items: [
      { prod_id: 'TESTPRD0001', order_qty: 200, price: 399, mrp: 499 }
    ]
  })
});

const data = await response.json();
console.log(`Status: ${response.status}`, data);

import requests

url = "https://www.ananta4pl.in/order/"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "txn_date": "2026-09-18",
    "doc_id": "SALO",
    "assoc_ref": "2026-27/001",
    "assoc_ref_date": "2026-09-18",
    "bill_to": "CU001",
    "cons_name": "Malhotra Books",
    "cons_address": "SCF-14, Sect-15",
    "cons_city": "Panchkula",
    "cons_state": "06",
    "cons_pin": "134109",
    "cons_phone": "9988776655",
    "items": [
        {"prod_id": "TESTPRD0001", "order_qty": 200, "price": 399, "mrp": 499}
    ]
}

response = requests.post(url, json=payload, headers=headers, timeout=30)
print(response.status_code, response.json())

Service Planned / In Design

Endpoint Name

This endpoint is scheduled for release in the Ananta 4PL API Roadmap.

POST /path

API Specification In Progress

This endpoint contract is currently being designed and drafted. As soon as the specification is added, its full interactive playground, schema tables, and mock sandbox will appear here automatically.