Subversion Repositories SmartDukaan

Rev

Rev 37219 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
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: &lt;your key&gt;</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>
37219 amit 56 
<pre>categoryId = a product category exposed to you        → listed in categoryMaster
57 
catalogId  = a product model (e.g. "Galaxy A15")     → content in catalogMaster
37150 amit 58 
itemId     = a sellable SKU, one per color            → listed in catalogSkuMaster
59 
storeId    = a physical partner store mapped to you   → listed in storeMaster
60 
stock      = (storeId, itemId) → availability          → skuMaster / stock</pre>
61 
<p>Prices per SKU: <code>mop</code> is the proposed selling price; <code>mrp</code> is the maximum retail
62 
price (strike-through display). A SKU with <code>active: false</code> is delisted and should not be sold.</p>
37219 amit 63 
<div class="note">
64 
  <strong>Category scoping:</strong> your account is mapped to specific categories (see
65 
  <code>/categoryMaster</code>). Every feed and lookup only ever returns catalogs, SKUs and stock within
66 
  those categories. <code>title</code> is present and non-empty on catalog, SKU and stock records — the
67 
  same derived product title everywhere.
68 
</div>
37150 amit 69 
 
70 
<h2>Master feeds (paginated sync)</h2>
37219 amit 71 
 
72 
<h3><span class="method">GET</span>/categoryMaster</h3>
73 
<p>The categories your key may access, each with its spec schema (the keys you will find in
74 
<code>categorySpecs</code> on catalog content). Full list, no pagination.</p>
75 
<pre>GET /external/v1/categoryMaster
76 
→ [ { "categoryId": 10006, "label": "Mobile", "displayName": "Mobile Phones",
77 
      "specs": [ { "key": "ram", "label": "RAM", "position": 1 },
78 
                 { "key": "memory", "label": "Internal Storage", "position": 2 } ] } ]</pre>
37150 amit 79 
<p>All feeds accept <code>offset</code> (default 0), <code>limit</code>, and optional
80 
<code>updatedSince</code> (epoch ms) and return:</p>
81 
<pre>{
82 
  "serverTime": 1753600000000,   // pass back as next updatedSince
83 
  "offset": 0, "limit": 100,
84 
  "totalCount": 5321,
85 
  "records": [ ... ]
86 
}</pre>
87 
 
88 
<h3><span class="method">GET</span>/catalogMaster</h3>
37219 amit 89 
<p>Full catalog content documents of your categories. <code>limit</code> max 100 (documents are large).
90 
<code>content.title</code> is always non-empty; <code>content.categorySpecs</code> holds the
91 
category-governed key specs (see <code>/categoryMaster</code> for the schema).</p>
37150 amit 92 
<pre>GET /external/v1/catalogMaster?offset=0&amp;limit=100
93 
→ records: [ { "catalogId": 12345, "lastModified": 1753500000000,
37219 amit 94 
               "content": { "title": "Samsung Galaxy A15 SM-A155F", "categoryId": 10006,
95 
                            "categorySpecs": [ { "key": "ram", "label": "RAM", "value": "8GB" },
96 
                                               { "key": "memory", "label": "Internal Storage", "value": "256GB" } ],
97 
                            "name": "...", "keySpecs": [...], "detailedSpecs": [...],
37150 amit 98 
                            "images": [...], "defaultImageUrl": "...", ... } } ]</pre>
99 
 
100 
<h3><span class="method">GET</span>/catalogSkuMaster</h3>
37219 amit 101 
<p>Catalog → SKU map with prices. <code>limit</code> max 500. <code>brandIdentifier</code> is the
102 
brand's own article/SKU code where known (else <code>null</code>).</p>
37150 amit 103 
<pre>GET /external/v1/catalogSkuMaster?offset=0&amp;limit=500
37219 amit 104 
→ records: [ { "catalogId": 12345, "itemId": 101, "title": "Samsung Galaxy A15 SM-A155F",
105 
               "brand": "Samsung", "modelName": "Galaxy A15", "modelNumber": "SM-A155F",
106 
               "color": "Blue", "brandIdentifier": "SM-A155FZKW",
37150 amit 107 
               "mop": 14999.0, "mrp": 17999.0, "active": true, "updatedAt": 1753500000000 } ]</pre>
108 
 
109 
<h3><span class="method">GET</span>/skuMaster</h3>
37219 amit 110 
<p>Per-store stock + price rows for <em>your mapped stores</em>, with full item identity on every row.
111 
<code>limit</code> max 500. Optional <code>storeId</code> narrows to one store (must be mapped to you).</p>
37150 amit 112 
<pre>GET /external/v1/skuMaster?offset=0&amp;limit=500
37219 amit 113 
→ records: [ { "storeId": 2116665, "itemId": 101, "title": "Samsung Galaxy A15 SM-A155F",
114 
               "brand": "Samsung", "modelName": "Galaxy A15", "modelNumber": "SM-A155F",
115 
               "color": "Blue", "brandIdentifier": "SM-A155FZKW", "availability": 7,
37150 amit 116 
               "mop": 14999.0, "mrp": 17999.0, "active": true, "updatedAt": 1753500000000 } ]</pre>
117 
 
118 
<h3><span class="method">GET</span>/storeMaster</h3>
37224 amit 119 
<p>Your mapped stores with location and GST details, in the standard paginated envelope
120 
(<code>limit</code> max 500; no <code>updatedSince</code> — store data has no delta feed, sync it fully).</p>
121 
<pre>GET /external/v1/storeMaster?offset=0&amp;limit=100
122 
→ records: [ { "storeId": 2116665, "code": "NSPRJ39290", "name": "XYZ Mobiles",
123 
               "addressLine1": "...", "addressLine2": "...", "city": "Jaipur",
124 
               "state": "Rajasthan", "pincode": "302001", "latitude": "26.91", "longitude": "75.78",
125 
               "gstNumber": "08ABCDE1234F1Z5" } ]</pre>
37150 amit 126 
 
127 
<h2>Incremental sync (updatedSince)</h2>
128 
<ol>
129 
  <li>First sync: call each feed <strong>without</strong> <code>updatedSince</code> and page through with
130 
      <code>offset</code>/<code>limit</code>. Full feeds contain active records only.</li>
131 
  <li>Save the <code>serverTime</code> returned by the first page.</li>
132 
  <li>Next sync: pass that value as <code>updatedSince</code>. You receive only records whose stock,
133 
      price, listing or content changed since then — <strong>including delisted records with
134 
      <code>active: false</code></strong>, which you should remove/hide on your side.</li>
135 
  <li>Each delta response again carries a fresh <code>serverTime</code>; use it for the next cycle.</li>
136 
</ol>
137 
<div class="note">
138 
  Records deleted outright from our systems do not appear in deltas. Run a <strong>weekly full sync</strong>
139 
  (no <code>updatedSince</code>) to reconcile. Receiving the same record twice is normal — treat every
140 
  record as an upsert keyed by <code>(storeId, itemId)</code> / <code>itemId</code> / <code>catalogId</code>.
141 
</div>
142 
 
143 
<h2>Real-time lookups</h2>
144 
 
145 
<h3><span class="method">GET</span>/stock</h3>
37219 amit 146 
<p>Live stock + price in one mapped store, with item identity on every row. Two modes:</p>
147 
<ul>
148 
  <li><strong>By ids</strong> — pass <code>itemIds</code> (up to 100). Every requested <code>itemId</code> is
149 
      returned; no stock row means <code>availability: 0</code>, no active listing means
150 
      <code>mop/mrp: null</code>. Ids outside your categories come back as id-only rows with
151 
      <code>availability: 0</code>.</li>
152 
  <li><strong>Full store</strong> — omit <code>itemIds</code> to page through the store's entire stock with
153 
      <code>offset</code>/<code>limit</code> (max 500); the response is the standard paginated envelope
154 
      (<code>serverTime</code>/<code>totalCount</code>/<code>records</code>). One loop replaces batching ids
155 
      across many calls.</li>
156 
</ul>
157 
<pre>GET /external/v1/stock?storeId=2116665&amp;itemIds=101,102
158 
→ [ { "storeId": 2116665, "itemId": 101, "title": "Samsung Galaxy A15 SM-A155F",
159 
      "brand": "Samsung", "modelName": "Galaxy A15", "modelNumber": "SM-A155F", "color": "Blue",
160 
      "brandIdentifier": "SM-A155FZKW", "availability": 7, "mop": 14999.0, "mrp": 17999.0, "active": true },
161 
    { "storeId": 2116665, "itemId": 102, "title": null, "availability": 0, "mop": null, "mrp": null, "active": false } ]
37150 amit 162 
 
37219 amit 163 
GET /external/v1/stock?storeId=2116665&amp;offset=0&amp;limit=500
164 
→ { "serverTime": ..., "offset": 0, "limit": 500, "totalCount": 812, "records": [ ...same row shape... ] }</pre>
165 
 
37150 amit 166 
<h3><span class="method">GET</span>/catalogs</h3>
167 
<p>Catalog content for up to 50 catalogIds. Response is an object keyed by catalogId; ids without a
168 
document are omitted.</p>
169 
<pre>GET /external/v1/catalogs?catalogIds=12345,12346</pre>
170 
 
171 
<h3><span class="method">GET</span>/catalogSkus</h3>
172 
<p>Active-listed SKUs (with prices) of up to 50 catalogIds, as flat rows.</p>
173 
<pre>GET /external/v1/catalogSkus?catalogIds=12345,12346</pre>
174 
 
175 
<h2>Quick start</h2>
176 
<pre>curl -H 'X-Api-Key: YOUR_KEY' 'https://apis.smartdukaan.com/external/v1/storeMaster'
177 
curl -H 'X-Api-Key: YOUR_KEY' 'https://apis.smartdukaan.com/external/v1/skuMaster?limit=500'
178 
curl -H 'X-Api-Key: YOUR_KEY' 'https://apis.smartdukaan.com/external/v1/stock?storeId=STORE&amp;itemIds=101,102'</pre>
179 
 
180 
<h2>Fair use</h2>
181 
<ul>
182 
  <li>Sync feeds at most every 15 minutes; use <code>/stock</code> for point-in-time checks.</li>
183 
  <li>Keep your API key secret; it identifies your organisation. Contact SmartDukaan to rotate or revoke.</li>
184 
</ul>
185 
 
186 
</div>
187 
</body>
188 
</html>