Developer guide

For the person who connects a till, ERP or stock system to ProdID-Check. If you only need a scanner or the till helper, use the Brand setup guide instead.

1. 1. Get an integration key
2. 2. Make a call
3. 3. Factory and stock system
4. 4. Till and store system
5. 5. Check a code (public)
6. 6. Errors and limits
7. 7. Keep it safe

1. Get an integration key

1. A brand admin signs in at app.html and opens the Integrations tab.
2. Name the key (for example “ERP” or “Till 1”) and press Create key. Copy it at once. It is shown once and we keep only a hash of it.
3. A brand key works like a factory operator: it can register, dispatch and look up items. A store key (made by a store admin) works like a till teller: it can receive, sell and look up items in that store.
4. A key cannot manage people or other keys, and it can never sign in to the website. Use one key per system so you can stop one without touching the rest. Revoke a key on the same tab and it stops working at once.

2. Make a call

All calls go to https://prodidcheck.co.za/v1. Send your key in the X-Api-Key header. Send and receive JSON.

curl -s https://prodidcheck.co.za/v1/stores \
  -H "X-Api-Key: pck_YOUR_KEY_HERE"

A key looks like pck_ followed by letters and numbers. Treat it like a password.

3. Factory and stock system (brand key)

Register one item. Returns the new item with its ID code.

POST https://prodidcheck.co.za/v1/products
{"sku": "JKT-001-M", "name": "Winter jacket, medium", "description": "Black"}

201 -> {"code": "...", "sku": "JKT-001-M", "name": "...", "state": "...", ...}

Register many. Up to 5,000 items in one call. Every unit gets its own code.

POST https://prodidcheck.co.za/v1/products/bulk
{"items": [
  {"sku": "JKT-001-M", "name": "Winter jacket, medium", "quantity": 120},
  {"sku": "JKT-001-L", "name": "Winter jacket, large", "quantity": 80}
]}

201 -> [ {"code": "..."}, ... ]

The code is what you print in the tag QR. The QR holds the address https://prodidcheck.co.za/verify.html?code=THE_CODE.

List your stores to get their ids:

GET https://prodidcheck.co.za/v1/stores
200 -> [ {"storeId": "...", "label": "Sandton"}, ... ]

Dispatch an item to a store:

POST https://prodidcheck.co.za/v1/products/dispatch
{"code": "THE_CODE", "storeId": "THE_STORE_ID"}

List or look up items: GET /products?state=REGISTERED lists items (states: REGISTERED, DISPATCHED, IN_STORE, SOLD); POST /products/lookup with {"code": "..."} returns one item with its owners and history.

Flag a stolen or lost item: POST /products/flag with {"code": "...", "flag": "STOLEN", "note": "..."}. The flag is STOLEN or LOST. Clear it with POST /products/unflag.

Offline or batch sync: if your system makes the codes itself, POST /products/offline accepts up to 500 items of {"code", "sku", "name", "description"} and answers each code with CREATED, ALREADY (you sent it before) or REJECTED (with a reason). The codes must be valid ProdID codes made by our tag tools.

4. Till and store system (store key)

Receive stock when it arrives in the store:

POST https://prodidcheck.co.za/v1/products/receive
{"code": "THE_CODE"}

Register a sale at the till. The buyer must agree to their name being recorded, so buyerConsent must be true or the call fails.

POST https://prodidcheck.co.za/v1/products/sell
{"code": "THE_CODE", "buyerName": "A. Buyer", "buyerContact": "optional",
  "buyerConsent": true, "showFullName": false}

200 -> {"product": {...}, "handoverCode": "..."}

Print the handoverCode on the customer’s slip. The buyer needs it to pass the item on or to report it stolen. It is not shown again, so store or print it at once. The till helper does this for you if you use it.

Other store calls: POST /products/lookup (details), POST /products/sales-search (find a sale by name or SKU), POST /products/reissue-handover (new handover code for a sold item).

5. Check a code (public, no key)

GET https://prodidcheck.co.za/v1/verify/THE_CODE

200 -> {"genuine": true, "name": "...", "manufacturer": "...", "status": "...", ...}
404 -> {"genuine": false, ...}

Use this on your own site or app. Lookups are limited per address, so cache answers for a short time. For a ready-made button, see the Website tab in the app.

6. Errors and limits

• Errors come back as {"error": "A plain sentence"} with a normal HTTP status: 400 for a bad request, 401 for a missing or revoked key, 403 for something the key may not do, 404 for an unknown code, 429 for too many requests.
• Writes are rate limited per key. If you get 429, wait a few seconds and send again.
• If the brand’s invoice is overdue, registering new items is paused. Dispatching, selling and checking still work.
• Your plan sets how many new items you may register each month (500 on Starter, 5,000 on Growth). One bulk call can create at most 5,000.
• Keep your own record of what you sent, and retry safely: sending the same code and SKU again through /products/offline answers ALREADY and creates nothing twice.

7. Keep it safe

• Keep keys on your server or till PC, never in a web page or a phone app.
• Use one key per system. Revoke any key you no longer use, or that anyone who left your company had.
• Only send buyer details with the buyer’s agreement. See the privacy policy and the Brand Agreement.

Stuck? Email info@prodidcheck.co.za with the call you made and the error you got. Never include your key.