Public API Integrator Guide

This page is the rendered technical guide for developers or vendors who need to integrate with the KartuStok public API.

Use it together with:

• OpenAPI Specification
• Postman Collection

When to Use This Guide

Use this guide when the integration team needs to:

• test token connectivity
• configure the correct company API base URL
• understand scope requirements
• read warehouse, item, category, or stock data
• handle opaque public IDs and pagination safely

Base URL and Authentication

Always use the company frontend domain, not the member domain.

Correct:

https://your-subdomain.kartustok.com/public/v1

Incorrect:

https://member.kartustok.com/public/v1

All requests require:

Authorization: Bearer <your_api_token>
Accept: application/json

If the host is wrong, the API can return:

{
  "status": "error",
  "message": "Invalid URL"
}

Scope Matrix

Scope	Purpose	Endpoints
meta.read	Connectivity and company metadata	/health, /meta/company
item.read	Item list and item detail	/items, /items/{id}
category.read	Item category list	/item-categories
locator.read	Warehouse list	/locators
stock.read	Stock reports	/stock/summary, /stock/detail

Warehouse Compatibility Note

The current product UI uses Warehouse, but the technical contract still uses:

• /locators
• locator.read
• locator_id

Treat these names as the warehouse API contract for now.

Recommended Integration Flow

1. Call GET /health
2. Call GET /meta/company
3. Sync /item-categories
4. Sync /locators
5. Sync /items
6. Use /stock/summary for balances
7. Use /stock/detail for movement audit

Endpoint Summary

Health

GET /public/v1/health

Scope: meta.read

Company Metadata

GET /public/v1/meta/company

Scope: meta.read

Items

GET /public/v1/items
GET /public/v1/items/{id}

Scope: item.read

Supported list filters:

• page
• per_page
• q
• is_active
• category_id

Item Categories

GET /public/v1/item-categories

Scope: category.read

Warehouses

GET /public/v1/locators

Scope: locator.read

Stock Summary

GET /public/v1/stock/summary

Scope: stock.read

Common filters:

• date_from
• date_to
• locator_id
• item_id
• category_id
• page
• per_page

Stock Detail

GET /public/v1/stock/detail

Scope: stock.read

Required filter:

• locator_id

Optional filters:

• item_id
• transaction_type
• date_from
• date_to
• page
• per_page

Pagination

Endpoints with pagination:

• /items
• /stock/summary
• /stock/detail

Rules:

• page starts at 1
• per_page max is 100
• /items default per_page is 20
• /stock/summary default per_page is 50
• /stock/detail default per_page is 50

Error Handling

401 Unauthorized

Causes:

• missing bearer token
• invalid token
• inactive token
• expired token
• revoked token

403 Forbidden

Causes:

• missing required scope
• client IP is outside Allowed IPs

404

Possible causes:

• wrong company host
• invalid public ID
• resource not found

429 Too Many Requests

Current rate limit:

• 120 requests
• per 60-second window
• per token and client IP

Best Practices

• store tokens in server-side secrets
• use one token per integration
• keep scope as small as possible
• use Allowed IPs for stable server infrastructure
• do not assume opaque IDs are database integers
• do not use browser-side hardcoded tokens
• rotate or revoke tokens when ownership changes

For machine-readable assets, use the OpenAPI specification and Postman collection linked at the top of this page.