Developer Platform

Build with FMCG Cloud

Five AI-powered APIs for FMCG distribution. RESTful design, HMAC & JWT authentication, real-time webhooks, and comprehensive SDKs. Ship in hours, not months.

Getting Started

01

Get Your API Key

Sign up for a free account and generate your API credentials from the dashboard. You'll get an API key and HMAC secret for service-to-service authentication.

02

Make Your First Call

Use the cURL example to call the Shelf Recognition API. Replace the bearer token with your API key and point to any shelf image URL.

Terminal
POST/v1/shelf/analyze
curl -X POST https://api.fmcgcloud.com/v1/shelf/analyze \
  -H "Authorization: Bearer fmcg_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://cdn.example.com/shelf.jpg",
    "store_id": "STR-001",
    "options": {
      "detect_brands": true,
      "count_facings": true
    }
  }'
03

Go to Production

Load credits, configure webhooks for async results, set up sub-accounts if needed, and you're live. No staging environment required — sandbox and production use the same APIs.

Authentication

HMAC Signature

For service-to-service calls, sign requests with HMAC-SHA256. Combine the timestamp and request body, sign with your API secret, and include the signature in the request headers.

HMAC Signature
const crypto = require("crypto");

const secret = process.env.FMCG_API_SECRET;
const timestamp = Date.now().toString();
const body = JSON.stringify(payload);

const signature = crypto
  .createHmac("sha256", secret)
  .update(timestamp + body)
  .digest("hex");

headers["X-FMCG-Timestamp"] = timestamp;
headers["X-FMCG-Signature"] = signature;

JWT Bearer Token

For user-context requests, include a JWT bearer token in the Authorization header. Tokens are issued via the authentication endpoint and include tenant and user scopes.

JWT Bearer
// Bearer token authentication
const response = await fetch(
  "https://api.fmcgcloud.com/v1/shelf/analyze",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer ",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ image_url: "..." }),
  }
);

Product APIs

Shelf Recognition

POST /v1/shelf/analyze
GET /v1/shelf/results/:id
GET /v1/shelf/history
View Docs

Suggested Order

POST /v1/orders/suggest
GET /v1/orders/:id
GET /v1/orders/history
View Docs

Customer Segmentation

POST /v1/segments/analyze
GET /v1/segments/:id
GET /v1/segments/list
View Docs

Caller ID

POST /v1/caller/identify
GET /v1/caller/profile/:id
GET /v1/caller/history
View Docs

Route Optimization

POST /v1/routes/optimize
GET /v1/routes/:id
GET /v1/routes/active
View Docs

Sub-Account Architecture

Credit Pooling

Purchase credits at the parent level and allocate them to sub-accounts. Set spending limits, track consumption per sub-account, and top up allocations via API.

Data Isolation

Each sub-account's data is fully isolated — product catalogs, customer lists, and analysis results are never shared. Enforced at the database level, not application logic.

Usage Tracking

Per-sub-account usage reports with credit consumption breakdown by product, operation type, and time period. Export via API for integration with your billing system.

Your Account
Vendor Platform
50,000 credits|5 products
Acme Foods
ACM-001
5,000/mo
Isolated data
Northwind
NWD-001
10,000/mo
Isolated data
Globex
GLX-001
Unlimited
Isolated data
Credit pooling·Data isolation·Usage tracking

Webhooks & Events

Webhook Flow
Your App
API Call
FMCG Cloud
Process
Webhook
Your Server
recognition.completedPOST → your-server.com/webhooks
order.suggestedPOST → your-server.com/webhooks
credit.deductedPOST → your-server.com/webhooks
EventDescription
recognition.completed
Shelf analysis completed — results ready for retrieval
order.suggested
Order suggestion generated for a customer visit
credit.deducted
Credits consumed for an API operation
segment.updated
Customer segment membership has changed
route.optimized
Route optimization completed for a fleet

SDKs & Tools

TypeScript SDK

Available

Python SDK

Coming Soon

Postman Collection

Available

OpenAPI Spec

Available

Rate Limits & SLAs

ProductRate LimitResponse TimeUptime
Shelf Recognition100 req/min< 3s99.9%
Suggested Order200 req/min< 1s99.9%
Segmentation150 req/min< 2s99.9%
Caller ID300 req/min< 500ms99.95%
Route Optimization50 req/min< 5s99.9%

Developer FAQ

Start Building Today

Get your API credentials in minutes. Full sandbox access. No credit card required.