واجهة برمجة متجر NShop

1. Sign in to NShop as an admin and make sure the E-commerce add-on is enabled.
2. Open Add-ons, E-commerce and select the API tab.
3. Choose Create API key, name it (for example "Production storefront") and tick only the scopes it needs.
4. Copy the key now. It starts with nsk_live_ and is shown only once; NShop stores just a hash.

Each company can hold up to 10 active keys. Revoke a key at any time from the same tab; it stops working immediately.

Send the key in the Authorization header (or X-API-Key). The company is resolved from the key, so you never pass a company id. Call the API from your server, never from browser code.

Key safety. Store keys in environment variables, never commit them, use one key per application and give it the minimum scopes. A storefront normally needs store:read, catalog:read, orders:write and orders:read. If a key leaks, revoke it and create a new one.

Check the connection (no key needed), then list products with your key.

The same call from Node.js / Next.js server code:

Placing an order (see the order guide):

Prefer a typed client? Copy this single file into your project. It wraps every endpoint, throws a typed NShopApiError and keeps the same cache tags your storefront already uses.

Envelope. Success is { "data": ... }, plus meta for paginated lists. Errors are always:

Pagination. /products takes limit (1-100, default 24) and page or offset. meta returns { total, limit, page, has_more }.

Caching. Read endpoints send Cache-Control: private, max-age=…: store configuration 300 s, catalog 60 s. Orders are never cached. Cache on your side with fetch tags and revalidate when the shop changes.

Rate limits. 120 requests/minute per key and endpoint (order creation: 20/minute; public endpoints: 60/minute per IP). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 adds Retry-After (seconds).

Request ids. Each response includes X-Request-Id. Log it; support can trace the request with it.

Idempotency. Send Idempotency-Key (8-128 chars) on POST /orders. A retry with the same key and body returns the original response with Idempotent-Replayed: true; the same key with a different body returns 409.

Machine-readable spec: /api/v1/openapi.json (OpenAPI 3.1, import it into Postman, Insomnia or a code generator).

Field-by-field description of every object the API accepts or returns. A field marked required is always present; | null means the value can be null. Ignore fields you do not know: new fields can be added to responses at any time (see versioning).

Send ids and quantities only. The server prices every line from live data (including active offers), takes the shipping cost from the selected city and applies no tax and no manual discount. Show the cart total as an estimate and the order response as the source of truth. Stock is not enforced yet: the API does not reject an order that exceeds stock, so the shop reviews every order in NShop. stock_quantity and in_stock are for display only.

Retries. Generate one Idempotency-Key per checkout attempt (for example when the customer opens checkout) and reuse it on retries after timeouts or 502s. You will never create two orders.

Tracking. Ask the customer for their order number and the last four digits of their phone. A wrong combination answers 404 not_found, identical to an unknown order, and the phone is returned masked.

status can be pending, confirmed, processing, shipped, delivered, cancelled or refunded; payment_status can be pending, paid, failed or refunded. The shop owner changes them in NShop; the API only reads them. The API creates orders as cash on delivery, so status and payment_status both start as pending and becomes paid when the shop records the payment. tracking_number and shipping_method are filled in by the shop when it ships. Poll GET /orders/{n} (no more than every few minutes) to refresh a tracking page.

NShop does not push changes to your site. Your storefront decides how fresh the catalog is, in one of two ways: cache reads with a short TTL, or keep a local copy and sync it incrementally with updated_since.

Option 1: cache with a TTL. Fetch on demand and cache on your side (Next.js: fetch with next: { revalidate: 60, tags: ["storefront-catalog"] }). Suggested TTLs: products and categories 60-600 s, store settings, theme, shipping cities and banners 300-3600 s, orders never. To refresh sooner, call your own revalidate endpoint (for example /api/revalidate with revalidateTag) whenever you need a refresh, such as from a scheduled job. This replaces the old push from the POS.

Option 2: incremental sync. GET /products?updated_since=<ISO-8601> returns only products whose updated_at is on or after that instant (a full ISO-8601 datetime such as 2026-09-21T06:45:26+00:00; a date-only value like 2026-09-21 returns 400 validation_error) (still name-sorted and paginated). Store the timestamp of your last successful sync, subtract a few minutes of overlap, and merge the result by product id. An invalid value returns 400 validation_error.

Limitation. A product that was unpublished, deactivated or deleted stops appearing in listings; it is not reported as deleted. After an incremental sync, drop local products that are missing from a full listing: run a full refresh periodically (for example daily, or at night) by paging through /products without updated_since. Always re-read price (and stock_quantity, which is informational) from the API at checkout time (GET /products?ids=), never from your copy.

Set a client timeout of about 10 seconds. Retry only 429, 500, 502 and network errors, with exponential backoff plus jitter (and honour Retry-After on 429). Never retry other 4xx errors: the request itself is wrong (fix it). When you retry POST /orders, send the same Idempotency-Key so the order can never be created twice. Log the X-Request-Id of failed calls.

Server-to-server only (CORS). CORS is not enabled on the API endpoints (only the public openapi.json file is readable from anywhere), so browsers cannot call the API directly, and they must never hold a key anyway. Call NShop from your server (route handlers, server components, a backend) and expose only the data you need to your front end.

Money and currency. Amounts are JSON numbers with up to 2 decimals, in the shop currency (GET /store returns company.ecommerce_currency, falling back to company.currency). Do not add or multiply prices as floats: compute in integer cents or a decimal library and round only for display. Offers are already inside price; do not subtract them again. Use compare_at_price only for a crossed-out price.

Search. q (max 100 chars) is a case-insensitive substring match on product name, SKU and barcode. It is not fuzzy and does not rank results; listings are sorted by name.

Images. images holds public URLs, main image first, and is an empty array when a product has none. Treat them like any external image: cache them, or serve them through your image optimizer (for example next/image with the host allowed in remotePatterns), and show a placeholder when the array is empty.

Postman and code generators. Import /api/v1/openapi.json into Postman or Insomnia, then create a collection variable apiKey and set the collection authorization to Bearer Token with {{apiKey}}. The same file works with OpenAPI Generator to produce a client in your language.

The version is in the path (/api/v1). Inside v1 we only make additive changes: new endpoints, new optional query parameters, new response fields and new enum values. Your client must ignore unknown fieldsand tolerate unknown enum values. A breaking change (removing or renaming a field, changing a type or meaning) ships as v2, and v1 keeps working for at least 6 months after v2 is announced. Every change is listed in the changelog below.

Contact NShop on WhatsApp: 00972595856529. Always include the X-Request-Id response header of the failing call (and the time, the endpoint and the HTTP status); it lets us find the exact request. Never send your full API key: the first characters (for example nsk_live_ab12cd) are enough to identify it.

Replace each database function with the matching API call and delete the Supabase client. Your server components keep working: only the data functions change. Keep the storefront-config (1 h) and storefront-catalog(10 min) tags on your fetch calls so your existing /api/revalidate hook still busts the cache. The full step-by-step guide is in docs/api/storefront-migration.md.