Nishchinto AI Product Feed API — merchant integration contract (v1)

Expose this one read-only HTTPS endpoint on your website and Nishchinto AI keeps your catalog in sync automatically: new products appear, prices and stock refresh on a schedule, and the AI agent quotes your live numbers to customers in Messenger and WhatsApp instead of a stale copy.

Your website stays the source of truth. Nishchinto AI never writes to it.

Already have a product feed? You do not have to implement this contract. Nishchinto AI can read a Shopify /products.json, a Google Merchant / Facebook catalog JSON, or any JSON shape at all — a business saves a field mapping in Settings → Product Feed and we adapt to your existing keys. This document describes the default: implement it and no mapping or configuration is needed. Everything below about authentication, pagination and error handling applies either way.

Flow

every 6h or 24h (and whenever the owner clicks "Sync now")
   → Nishchinto AI GETs {base}/alapai/products?page=1&limit=250
   → you return your live catalog page by page
   → Nishchinto AI upserts by external_id: new ones created, existing ones
     refreshed (price, stock, availability), missing ones marked out of stock
   → the agent sells from those numbers

You give Nishchinto AI (Settings → Product Feed):

• Feed URL — e.g. https://yourshop.com.bd/api/alapai/products. Must be public HTTPS; private, loopback and internal hosts are rejected.
• API key — a random secret you generate (32+ characters). Nishchinto AI sends it on every request, including the one-off "read this feed" check the owner runs when connecting, so the key can be pasted in and tested before anything is saved.

Authentication

Required — and enforced by you, not by us.

This is the part of the contract that only your side can implement. Nishchinto AI presents the key on every request; whether an unauthenticated request is refused is decided entirely by your endpoint. If your route does not check the header, the feed is public no matter what is configured on our side, and anyone who learns the URL can read your whole catalog, stock and pricing — competitors and scrapers included. Earlier integrations were exactly that: a plain public URL with nothing in front of it. This contract exists to end that.

So: the key check is your middleware's job.

X-API-Key: <your api key>

Authorization: Bearer <key> is supported as an alternative if it fits your stack better; the owner picks which one in Settings.

Rules — all of these are yours to implement:

• Reject the request yourself. Check the header in middleware, before any catalog query runs. Nishchinto AI cannot make an open endpoint safe.
• Compare with a constant-time function (hash_equals in PHP), never ==.
• Reply 401 with a JSON body when the key is missing or wrong. Do not reply 200 with an empty list — see Never return an empty catalog below.
• Generate the key randomly (php artisan tinker → Str::random(48)), store it in .env, and never commit it.
• To rotate: accept both the old and the new key for a day, have the owner update Settings → Product Feed, then drop the old one.

Already connected with a public feed URL? It keeps working — Nishchinto AI still imports feeds with no authentication, and nothing needs to change on the day you upgrade. But an unauthenticated feed stays readable by anyone with the URL, so add the middleware, generate a key, and paste it into Settings → Product Feed. The switch is one save; there is no re-import and no downtime.

Want more than a shared secret? Ask us for our egress IP address and allowlist it at your firewall or in the middleware — every Nishchinto AI feed fetch comes from one static address. Request signing (HMAC) is not part of v1: Nishchinto AI does not sign feed requests today, so do not require a signature.

The endpoint — GET {base}/alapai/products

Query parameters

Pagination is required. Nishchinto AI always sends these two parameters and walks pages until it receives a page with fewer than limit products (or an empty one). Two consequences:

• Order must be stable across pages and across the whole walk — order by primary key, not by anything that can change mid-crawl (updated_at, price, popularity). An unstable order silently skips and duplicates products.
• You must actually honour page. If you ignore it and return the whole catalog every time, Nishchinto AI stops after detecting the repeat, but you will have served your entire catalog twice for nothing.

If your catalog fits comfortably in one response you can cap limit at whatever your server handles and return a short page — the walk ends there.

Response — 200

{
  "alapai_feed_version": 1,
  "generated_at": "2026-08-12T09:00:00+06:00",
  "count": 2,
  "products": [
    {
      "external_id": "SKU-1042",
      "name": "Awei P13K 20000mAh Power Bank",
      "description": "22.5W fast charging, dual output, LED display.",
      "price": 1850,
      "regular_price": 2250,
      "flash_price": null,
      "brand": "Awei",
      "category": "Power Bank",
      "product_code": "AWP13K",
      "in_stock": true,
      "stock": 7,
      "images": [
        "https://yourshop.com.bd/storage/products/1042-a.jpg",
        "https://yourshop.com.bd/storage/products/1042-b.jpg"
      ],
      "variations": []
    },
    {
      "external_id": "SKU-2210",
      "name": "Cotton Kurti — Sky Blue",
      "description": "Soft cotton, full sleeve.",
      "price": 1290,
      "regular_price": 1590,
      "brand": "",
      "category": "Kurti",
      "product_code": "KRT-2210",
      "in_stock": true,
      "stock": 12,
      "images": ["https://yourshop.com.bd/storage/products/2210.jpg"],
      "variations": [
        {
          "variation_id": "88431",
          "size": "M",
          "color": "Sky Blue",
          "sku": "KRT-2210-M",
          "stock": 5,
          "price": 1290
        },
        {
          "variation_id": "88432",
          "size": "L",
          "color": "Sky Blue",
          "sku": "KRT-2210-L",
          "stock": 7,
          "price": 1290
        }
      ]
    }
  ]
}

Send Content-Type: application/json. count and generated_at are for your own debugging — Nishchinto AI reads products.

Product fields

* Send at least one of stock / in_stock. If both are absent the product is imported out of stock — deliberately fail-closed, so the agent never sells something you did not confirm you have.

Variation fields

Send variations when one product has several sizes or colours the customer must choose between. Without it, a multi-size product collapses into one stock number and the agent can sell a size you do not have.

Send at most 50 variations per product; extras are ignored.

Never return an empty catalog

If your catalog query fails, your database is mid-deploy, or the key is wrong, do not answer 200 {"products": []}. An empty feed would otherwise mean "every product has been discontinued", and a resync marks the whole catalog out of stock — the agent then tells every customer that everything is unavailable.

Return an error status instead (503 is right for "temporarily broken"). Nishchinto AI refuses an empty page from a feed that previously had products and keeps the last known catalog, but that safety net exists for accidents; returning the correct status is what keeps your shop selling.

Error responses

Body shape for errors (any JSON is fine, this is the convention):

{ "error": "unauthorized", "message": "Invalid API key." }

Do not leak internals in error responses. Turn debug mode off in production (APP_DEBUG=false) — a framework stack trace exposes source code, file paths and sometimes credentials to anyone who can reach the URL.

Limits Nishchinto AI enforces

Health check (optional) — GET {base}/alapai/health

{ "status": "ok" }

Useful for the owner to confirm the key works before running a first import.

Reference implementation (Laravel)

Tested against Laravel 10/11. Adjust model and column names to your schema.

.env

ALAPAI_FEED_KEY=<48 random characters>

config/services.php

'alapai' => [
    'feed_key' => env('ALAPAI_FEED_KEY'),
],

app/Http/Middleware/VerifyAlapaiKey.php

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class VerifyAlapaiKey
{
    public function handle(Request $request, Closure $next)
    {
        $expected = (string) config('services.alapai.feed_key');
        $given = (string) ($request->header('X-API-Key')
            ?? $request->bearerToken()
            ?? '');

        // hash_equals is constant-time: it does not leak the key one
        // character at a time through response timing.
        if ($expected === '' || ! hash_equals($expected, $given)) {
            return response()->json(['error' => 'unauthorized'], 401);
        }

        return $next($request);
    }
}

Register it (Laravel 11 — bootstrap/app.php):

->withMiddleware(function (Middleware $middleware) {
    $middleware->alias(['alapai.key' => \App\Http\Middleware\VerifyAlapaiKey::class]);
})

Laravel 10 — add the alias to $middlewareAliases in app/Http/Kernel.php.

routes/api.php

use App\Http\Controllers\AlapaiFeedController;

Route::prefix('alapai')->middleware('alapai.key')->group(function () {
    Route::get('/health', [AlapaiFeedController::class, 'health']);
    Route::get('/products', [AlapaiFeedController::class, 'index']);
});

app/Http/Controllers/AlapaiFeedController.php

<?php

namespace App\Http\Controllers;

use App\Models\Product;
use Illuminate\Http\Request;

class AlapaiFeedController extends Controller
{
    private const MAX_LIMIT = 250;

    public function health()
    {
        return response()->json(['status' => 'ok']);
    }

    public function index(Request $request)
    {
        $limit = min(max((int) $request->query('limit', 250), 1), self::MAX_LIMIT);
        $page = max((int) $request->query('page', 1), 1);

        $query = Product::query()
            ->where('is_published', true)
            ->with(['images', 'variants'])
            ->orderBy('id');           // stable order — required by the walk

        $products = $query->forPage($page, $limit)->get();

        // Never answer 200 with an empty list while the shop actually has
        // products: that reads as "everything is discontinued".
        if ($page === 1 && $products->isEmpty() && $query->clone()->exists()) {
            return response()->json(['error' => 'temporarily_unavailable'], 503);
        }

        return response()->json([
            'alapai_feed_version' => 1,
            'generated_at' => now()->toIso8601String(),
            'count' => $products->count(),
            'products' => $products->map(fn ($p) => $this->transform($p))->values(),
        ]);
    }

    private function transform(Product $p): array
    {
        // Effective selling price: whatever the customer pays today.
        $price = $p->discount_price > 0 ? $p->discount_price : $p->sell_price;

        return [
            'external_id' => (string) $p->id,
            'name' => $p->name,
            'description' => strip_tags((string) $p->details),
            'price' => (int) $price,
            // Only a genuine "before" price; 0/null means there isn't one.
            'regular_price' => $p->sell_price > $price ? (int) $p->sell_price : null,
            'brand' => (string) $p->brand_name,
            'category' => (string) optional($p->category)->name,
            'product_code' => (string) $p->code,
            'stock' => (int) $p->variants->sum('quantity'),
            'in_stock' => $p->variants->sum('quantity') > 0,
            'images' => $p->images
                ->map(fn ($i) => asset('storage/' . $i->path))   // absolute URLs
                ->values(),
            'variations' => $p->variants->map(fn ($v) => [
                'variation_id' => (string) $v->id,   // the id YOUR checkout expects
                'size' => (string) $v->size,
                'color' => (string) $v->color,
                'sku' => (string) $v->sku,
                'stock' => (int) $v->quantity,
            ])->values(),
        ];
    }
}

Test it before handing over the URL:

curl -sS -H "X-API-Key: $ALAPAI_FEED_KEY" \
  "https://yourshop.com.bd/api/alapai/products?page=1&limit=250" | jq '.count, .products[0]'

# must be 401
curl -s -o /dev/null -w '%{http_code}\n' \
  "https://yourshop.com.bd/api/alapai/products"

Checklist before going live

• URL is public HTTPS with a valid certificate.
• No key → 401. Wrong key → 401. Correct key → 200.
• Key compared with hash_equals, read from .env, not committed.
• ?page=2&limit=250 returns the second 250 products, not the first.
• Ordering is by primary key, stable between requests.
• external_id is your permanent product id and never changes.
• Prices are the effective selling price; regular_price only when it is genuinely higher.
• Products with sizes send variations, each with the variation_id your own checkout expects.
• Image URLs are absolute and load in a browser without a session.
• A broken catalog query returns 503, never 200 with [].
• APP_DEBUG=false in production.
• One page responds in well under 30 seconds and 25 MB.

Versioning

alapai_feed_version: 1 identifies this contract. Fields will only ever be added within v1 — unknown fields are ignored, so you can adopt new ones when you are ready. Anything incompatible ships as v2 with both supported in parallel.

Questions, or want your egress-IP allowlist entry? Contact support.