4klyft API (1.0.0)

This API provides endpoints for managing:

• Catalog (PIM/DAM): products, variants, attributes, options, categories, brands, collections, assortments, and media
• Sales: orders, customers, merchants, sales channels, and channel order import
• Inventory: stock items, levels, lots, and serial units across custodians
• Warehousing & Operations: goods receipt/issue, holds, and custodian operations
• Fulfilment: fulfilment orders dispatched to third-party (3PL) providers
• Shipping: carriers, shipments, labels, tracking, returns, and proof of delivery
• Finance & Billing: payments, settlements, invoices, credit notes, tax, and subscriptions
• Integration: sales-channel connections, providers, webhooks, and catalog/order sync
• Documents: operational document generation and requests
• Storage: file/drive storage with chunked upload and signed access
• Identity & Access (IAM): authentication, users, roles, permissions, and tenants
• Platform services: notifications, scheduling, numbering, data exchange, analytics, and workspace tables & views

All API endpoints (except /api/docs and /api/v1/iam/auth/*) require JWT Bearer token authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Every /api/ request is rate-limited per caller — by your authenticated identity when a token is present, otherwise by client IP. The authentication endpoints (/auth/login, /auth/refresh, /auth/request-password-reset) carry stricter, IP-based limits.

Each response advertises your current budget via headers:

• X-RateLimit-Limit — the bucket size
• X-RateLimit-Remaining — tokens left in the current window
• X-RateLimit-Reset — Unix timestamp when a token next frees up

Exceeding a limit returns 429 Too Many Requests (RFC 6585) with a Retry-After header (seconds to wait). Back off and retry after the indicated delay rather than hammering the endpoint.

The API uses RFC 7807 Problem Details for error responses.

A purchase order — the buy-side counterpart of a Sales Order. Placed against a supplier, carries priced lines referencing purchased items by opaque ResourceUri, and moves through Draft → Approved → Issued → Acknowledged → PartiallyReceived → Received → Closed (or Cancelled).

Receiving is NOT a user action on this resource — to receive against a PO you create a Goods Receipt with the PO as its subject; the received quantities flow back onto the PO lines automatically.

A purchase return (return-to-vendor / RTV) — the buy-side mirror of the customer RMA. Returns goods to a supplier, optionally citing a source purchase order and/or inbound delivery, and moves through Draft → Approved → Issued → Completed (or Cancelled).

Issued is where goods physically leave back to the vendor; Completed is where a vendor debit note posts to Finance. Neither the physical (GoodsIssue) nor financial (debit note) leg is exposed on this resource yet — they are P1 follow-ups that attach to the Issued / Completed transitions.

A supplier (vendor) — the buy-side counterpart of a shipping Client. Links an existing Partner (carrying the Supplier role) to supplier-master fields: payment terms, lead time, and default currency.

Tenant-managed reference data.