| 37150 |
amit |
1 |
<!DOCTYPE html>
|
|
|
2 |
<html lang="en">
|
|
|
3 |
<head>
|
|
|
4 |
<meta charset="utf-8">
|
|
|
5 |
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
|
6 |
<title>SmartDukaan External API — Partner Documentation</title>
|
|
|
7 |
<style>
|
|
|
8 |
body { font-family: -apple-system, Segoe UI, Roboto, Arial, sans-serif; margin: 0; color: #1f2933; line-height: 1.55; }
|
|
|
9 |
.wrap { max-width: 960px; margin: 0 auto; padding: 24px 20px 80px; }
|
|
|
10 |
h1 { font-size: 1.7em; border-bottom: 2px solid #e4e7eb; padding-bottom: 10px; }
|
|
|
11 |
h2 { font-size: 1.25em; margin-top: 2em; border-bottom: 1px solid #e4e7eb; padding-bottom: 6px; }
|
|
|
12 |
h3 { font-size: 1.05em; margin-top: 1.6em; }
|
|
|
13 |
code, pre { font-family: SFMono-Regular, Consolas, Menlo, monospace; font-size: 0.9em; background: #f5f7fa; border-radius: 4px; }
|
|
|
14 |
code { padding: 1px 5px; }
|
|
|
15 |
pre { padding: 12px 14px; overflow-x: auto; border: 1px solid #e4e7eb; }
|
|
|
16 |
table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 0.93em; }
|
|
|
17 |
th, td { border: 1px solid #d3dae1; padding: 7px 10px; text-align: left; vertical-align: top; }
|
|
|
18 |
th { background: #f5f7fa; }
|
|
|
19 |
.method { display: inline-block; background: #0b7a3e; color: #fff; border-radius: 4px; padding: 1px 8px; font-size: 0.8em; font-weight: 600; margin-right: 8px; }
|
|
|
20 |
.note { background: #fff8e1; border: 1px solid #f0d580; border-radius: 4px; padding: 10px 14px; }
|
|
|
21 |
</style>
|
|
|
22 |
</head>
|
|
|
23 |
<body>
|
|
|
24 |
<div class="wrap">
|
|
|
25 |
|
|
|
26 |
<h1>SmartDukaan External API <small>v1</small></h1>
|
|
|
27 |
<p>Read-only APIs giving approved partners visibility into store-level stock, proposed selling prices
|
|
|
28 |
and catalog master data of SmartDukaan partner stores.</p>
|
|
|
29 |
|
|
|
30 |
<h2>Basics</h2>
|
|
|
31 |
<table>
|
|
|
32 |
<tr><th>Base URL</th><td><code>https://apis.smartdukaan.com/external/v1</code></td></tr>
|
|
|
33 |
<tr><th>Authentication</th><td>Header <code>X-Api-Key: <your key></code> on every request. Keys are issued per partner by SmartDukaan.</td></tr>
|
|
|
34 |
<tr><th>Format</th><td>All endpoints are <code>GET</code> and return JSON.</td></tr>
|
|
|
35 |
<tr><th>Timestamps</th><td>All times are Unix epoch <strong>milliseconds</strong> (IST server clock).</td></tr>
|
|
|
36 |
</table>
|
|
|
37 |
|
|
|
38 |
<h3>Response envelope</h3>
|
|
|
39 |
<p>Every response is wrapped in a standard envelope; the payload is under <code>response</code>:</p>
|
|
|
40 |
<pre>{
|
|
|
41 |
"statusCode": "200 OK",
|
|
|
42 |
"statusMessage": "OK",
|
|
|
43 |
"responseStatus": "SUCCESS",
|
|
|
44 |
"response": { ... }
|
|
|
45 |
}</pre>
|
|
|
46 |
|
|
|
47 |
<h3>Errors</h3>
|
|
|
48 |
<table>
|
|
|
49 |
<tr><th>HTTP</th><th>Code</th><th>Meaning</th></tr>
|
|
|
50 |
<tr><td>401</td><td><code>EXT_401</code></td><td>Missing, invalid or inactive <code>X-Api-Key</code>.</td></tr>
|
|
|
51 |
<tr><td>403</td><td><code>EXT_403</code></td><td><code>storeId</code> is not mapped to your account.</td></tr>
|
|
|
52 |
<tr><td>400</td><td><code>EXT_400</code></td><td>Bad or over-sized id list parameter.</td></tr>
|
|
|
53 |
</table>
|
|
|
54 |
|
|
|
55 |
<h2>Data model</h2>
|
|
|
56 |
<pre>catalogId = a product model (e.g. "Galaxy A15") → content in catalogMaster
|
|
|
57 |
itemId = a sellable SKU, one per color → listed in catalogSkuMaster
|
|
|
58 |
storeId = a physical partner store mapped to you → listed in storeMaster
|
|
|
59 |
stock = (storeId, itemId) → availability → skuMaster / stock</pre>
|
|
|
60 |
<p>Prices per SKU: <code>mop</code> is the proposed selling price; <code>mrp</code> is the maximum retail
|
|
|
61 |
price (strike-through display). A SKU with <code>active: false</code> is delisted and should not be sold.</p>
|
|
|
62 |
|
|
|
63 |
<h2>Master feeds (paginated sync)</h2>
|
|
|
64 |
<p>All feeds accept <code>offset</code> (default 0), <code>limit</code>, and optional
|
|
|
65 |
<code>updatedSince</code> (epoch ms) and return:</p>
|
|
|
66 |
<pre>{
|
|
|
67 |
"serverTime": 1753600000000, // pass back as next updatedSince
|
|
|
68 |
"offset": 0, "limit": 100,
|
|
|
69 |
"totalCount": 5321,
|
|
|
70 |
"records": [ ... ]
|
|
|
71 |
}</pre>
|
|
|
72 |
|
|
|
73 |
<h3><span class="method">GET</span>/catalogMaster</h3>
|
|
|
74 |
<p>Full catalog content documents. <code>limit</code> max 100 (documents are large).</p>
|
|
|
75 |
<pre>GET /external/v1/catalogMaster?offset=0&limit=100
|
|
|
76 |
→ records: [ { "catalogId": 12345, "lastModified": 1753500000000,
|
|
|
77 |
"content": { "name": "...", "keySpecs": [...], "detailedSpecs": [...],
|
|
|
78 |
"images": [...], "defaultImageUrl": "...", ... } } ]</pre>
|
|
|
79 |
|
|
|
80 |
<h3><span class="method">GET</span>/catalogSkuMaster</h3>
|
|
|
81 |
<p>Catalog → SKU map with prices. <code>limit</code> max 500.</p>
|
|
|
82 |
<pre>GET /external/v1/catalogSkuMaster?offset=0&limit=500
|
|
|
83 |
→ records: [ { "catalogId": 12345, "itemId": 101, "brand": "Samsung",
|
|
|
84 |
"modelName": "Galaxy A15", "modelNumber": "SM-A155F", "color": "Blue",
|
|
|
85 |
"mop": 14999.0, "mrp": 17999.0, "active": true, "updatedAt": 1753500000000 } ]</pre>
|
|
|
86 |
|
|
|
87 |
<h3><span class="method">GET</span>/skuMaster</h3>
|
|
|
88 |
<p>Per-store stock + price rows for <em>your mapped stores</em>. <code>limit</code> max 500.
|
|
|
89 |
Optional <code>storeId</code> narrows to one store (must be mapped to you).</p>
|
|
|
90 |
<pre>GET /external/v1/skuMaster?offset=0&limit=500
|
|
|
91 |
→ records: [ { "storeId": 2116665, "itemId": 101, "availability": 7,
|
|
|
92 |
"mop": 14999.0, "mrp": 17999.0, "active": true, "updatedAt": 1753500000000 } ]</pre>
|
|
|
93 |
|
|
|
94 |
<h3><span class="method">GET</span>/storeMaster</h3>
|
|
|
95 |
<p>Your mapped stores with location details. Always the full list (no pagination or delta needed).</p>
|
|
|
96 |
<pre>GET /external/v1/storeMaster
|
|
|
97 |
→ [ { "storeId": 2116665, "code": "NSPRJ39290", "name": "XYZ Mobiles",
|
|
|
98 |
"addressLine1": "...", "addressLine2": "...", "city": "Jaipur",
|
|
|
99 |
"state": "Rajasthan", "pincode": "302001", "latitude": "26.91", "longitude": "75.78" } ]</pre>
|
|
|
100 |
|
|
|
101 |
<h2>Incremental sync (updatedSince)</h2>
|
|
|
102 |
<ol>
|
|
|
103 |
<li>First sync: call each feed <strong>without</strong> <code>updatedSince</code> and page through with
|
|
|
104 |
<code>offset</code>/<code>limit</code>. Full feeds contain active records only.</li>
|
|
|
105 |
<li>Save the <code>serverTime</code> returned by the first page.</li>
|
|
|
106 |
<li>Next sync: pass that value as <code>updatedSince</code>. You receive only records whose stock,
|
|
|
107 |
price, listing or content changed since then — <strong>including delisted records with
|
|
|
108 |
<code>active: false</code></strong>, which you should remove/hide on your side.</li>
|
|
|
109 |
<li>Each delta response again carries a fresh <code>serverTime</code>; use it for the next cycle.</li>
|
|
|
110 |
</ol>
|
|
|
111 |
<div class="note">
|
|
|
112 |
Records deleted outright from our systems do not appear in deltas. Run a <strong>weekly full sync</strong>
|
|
|
113 |
(no <code>updatedSince</code>) to reconcile. Receiving the same record twice is normal — treat every
|
|
|
114 |
record as an upsert keyed by <code>(storeId, itemId)</code> / <code>itemId</code> / <code>catalogId</code>.
|
|
|
115 |
</div>
|
|
|
116 |
|
|
|
117 |
<h2>Real-time lookups</h2>
|
|
|
118 |
|
|
|
119 |
<h3><span class="method">GET</span>/stock</h3>
|
|
|
120 |
<p>Live stock + price for up to 100 SKUs in one mapped store. Every requested <code>itemId</code> is
|
|
|
121 |
returned; no stock row means <code>availability: 0</code>, no active listing means <code>mop/mrp: null</code>.</p>
|
|
|
122 |
<pre>GET /external/v1/stock?storeId=2116665&itemIds=101,102,103
|
|
|
123 |
→ [ { "storeId": 2116665, "itemId": 101, "availability": 7, "mop": 14999.0, "mrp": 17999.0, "active": true },
|
|
|
124 |
{ "storeId": 2116665, "itemId": 102, "availability": 0, "mop": null, "mrp": null, "active": false } ]</pre>
|
|
|
125 |
|
|
|
126 |
<h3><span class="method">GET</span>/catalogs</h3>
|
|
|
127 |
<p>Catalog content for up to 50 catalogIds. Response is an object keyed by catalogId; ids without a
|
|
|
128 |
document are omitted.</p>
|
|
|
129 |
<pre>GET /external/v1/catalogs?catalogIds=12345,12346</pre>
|
|
|
130 |
|
|
|
131 |
<h3><span class="method">GET</span>/catalogSkus</h3>
|
|
|
132 |
<p>Active-listed SKUs (with prices) of up to 50 catalogIds, as flat rows.</p>
|
|
|
133 |
<pre>GET /external/v1/catalogSkus?catalogIds=12345,12346</pre>
|
|
|
134 |
|
|
|
135 |
<h2>Quick start</h2>
|
|
|
136 |
<pre>curl -H 'X-Api-Key: YOUR_KEY' 'https://apis.smartdukaan.com/external/v1/storeMaster'
|
|
|
137 |
curl -H 'X-Api-Key: YOUR_KEY' 'https://apis.smartdukaan.com/external/v1/skuMaster?limit=500'
|
|
|
138 |
curl -H 'X-Api-Key: YOUR_KEY' 'https://apis.smartdukaan.com/external/v1/stock?storeId=STORE&itemIds=101,102'</pre>
|
|
|
139 |
|
|
|
140 |
<h2>Fair use</h2>
|
|
|
141 |
<ul>
|
|
|
142 |
<li>Sync feeds at most every 15 minutes; use <code>/stock</code> for point-in-time checks.</li>
|
|
|
143 |
<li>Keep your API key secret; it identifies your organisation. Contact SmartDukaan to rotate or revoke.</li>
|
|
|
144 |
</ul>
|
|
|
145 |
|
|
|
146 |
</div>
|
|
|
147 |
</body>
|
|
|
148 |
</html>
|