{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "http:\/\/localhost:8000" } ], "info": { "name": "KRA eTIMS Integrator API", "_postman_id": "edee4966-f854-47cc-86d6-ba63721685b2", "description": "Public KRA eTIMS Integrator API. Authenticate with X-API-Key using either a Business API key (business-scoped endpoints) or a Branch API key (branch operations).", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "Business", "description": "", "item": [ { "name": "List all branches for the authenticated business.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/branches", "query": [], "raw": "{{baseUrl}}\/api\/v1\/branches" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "4ffca312-fe30-4e15-a13e-5d2b13a0f5b9" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "59" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] } ] }, { "name": "Credits & Subscriptions", "description": "", "item": [ { "name": "Get the current credit balance for the authenticated business.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/credits\/balance", "query": [], "raw": "{{baseUrl}}\/api\/v1\/credits\/balance" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "36443396-d996-49fc-9520-e8f2b5ce1f77" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "58" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] } ] }, { "name": "Customers", "description": "", "item": [ { "name": "Look up taxpayer information for a customer KRA PIN.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/customers\/taxpayer-info", "query": [], "raw": "{{baseUrl}}\/api\/v1\/customers\/taxpayer-info" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"customer_pin\":\"bngzmiyvdlj\",\"refresh\":false}" }, "description": "Retrieves taxpayer information associated with the supplied customer KRA PIN." }, "response": [] }, { "name": "Get a list of business customers.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/customers", "query": [], "raw": "{{baseUrl}}\/api\/v1\/customers" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns customers belonging to the authenticated business. Supports\nsearch, is_active filter, and pagination via per_page." }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "ab4072c2-1005-4227-9c68-7c9bad89864a" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "54" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] }, { "name": "Create a new customer within the authenticated branch.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/customers", "query": [], "raw": "{{baseUrl}}\/api\/v1\/customers" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"customer_pin\":\"bngzmiyvdlj\",\"customer_name\":\"n\",\"customer_type\":\"government\",\"phone\":\"ikhwaykcmyuwpwlv\",\"email\":\"leo34@example.net\",\"address\":\"t\",\"county\":\"c\",\"district\":\"p\",\"sector\":\"s\",\"location_description\":\"c\",\"notes\":\"q\",\"is_active\":false}" }, "description": "" }, "response": [] }, { "name": "Retrieve a customer by public customer ID.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/customers\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/customers\/:id", "variable": [ { "id": "id", "key": "id", "value": "architecto", "description": "The ID of the customer." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "6c72d074-3c33-450d-829b-66627d57ac98" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "53" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] }, { "name": "Update an existing customer.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/customers\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/customers\/:id", "variable": [ { "id": "id", "key": "id", "value": "architecto", "description": "The ID of the customer." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"customer_name\":\"b\",\"customer_type\":\"individual\",\"phone\":\"ngzmiyvdljnikhwa\",\"email\":\"breitenberg.gilbert@example.com\",\"address\":\"u\",\"county\":\"w\",\"district\":\"p\",\"sector\":\"w\",\"location_description\":\"l\",\"notes\":\"v\",\"is_active\":true}" }, "description": "" }, "response": [] } ] }, { "name": "Suppliers", "description": "", "item": [ { "name": "List suppliers for the authenticated business.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/suppliers", "query": [], "raw": "{{baseUrl}}\/api\/v1\/suppliers" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "c968c8cb-3f4e-45eb-9a44-e9f2ebd196d4" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "57" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] }, { "name": "Create a new supplier for the business.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/suppliers", "query": [], "raw": "{{baseUrl}}\/api\/v1\/suppliers" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"supplier_pin\":\"bngzmiyvdlj\",\"supplier_name\":\"n\",\"supplier_type\":\"non_profit\",\"default_branch_id\":\"ik\",\"phone\":\"hwaykcmyuwpwlvqw\",\"email\":\"imclaughlin@example.org\",\"address\":\"c\",\"county\":\"p\",\"district\":\"s\",\"sector\":\"c\",\"location_description\":\"q\",\"notes\":\"l\",\"is_active\":false}" }, "description": "" }, "response": [] }, { "name": "Retrieve a supplier by public supplier ID.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/suppliers\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/suppliers\/:id", "variable": [ { "id": "id", "key": "id", "value": "architecto", "description": "The ID of the supplier." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "2cd8a13e-ba4d-4731-a92d-9f9024201baa" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "56" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] }, { "name": "Update an existing supplier.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/suppliers\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/suppliers\/:id", "variable": [ { "id": "id", "key": "id", "value": "architecto", "description": "The ID of the supplier." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"supplier_pin\":\"bngzmiyvdlj\",\"supplier_name\":\"n\",\"supplier_type\":\"individual\",\"default_branch_id\":\"ik\",\"phone\":\"hwaykcmyuwpwlvqw\",\"email\":\"imclaughlin@example.org\",\"address\":\"c\",\"county\":\"p\",\"district\":\"s\",\"sector\":\"c\",\"location_description\":\"q\",\"notes\":\"l\",\"is_active\":true}" }, "description": "" }, "response": [] } ] }, { "name": "Items \/ Products", "description": "\nManage products\/items for the authenticated branch. Public identifiers use `item_id`\n(for example `item_01M1RWCB448HVT2EERNK5Y4RQK`). KRA `item_code` values are generated\nautomatically by the application on create and are not exposed in public responses.\n\n`price` is always the **tax-inclusive** selling price.\n\nKRA enumeration codes used by these endpoints are documented in\n[Code Definitions](\/docs\/code-definitions).", "item": [ { "name": "List products\/items for the authenticated branch.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/items", "query": [], "raw": "{{baseUrl}}\/api\/v1\/items" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns active items for the branch. Responses use public `item_id` and tax-inclusive `price`.\nSynchronization and internal stock metadata are not included." }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "6ac022f0-4dc2-4418-8eb5-bd3fe61bfeb0" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "52" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] }, { "name": "Retrieve a product\/item by item_id.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/items\/:itemId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/items\/:itemId", "variable": [ { "id": "itemId", "key": "itemId", "value": "item_01M1RWCB448HVT2EERNK5Y4RQK", "description": "Public item ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Look up an item using the public `item_id` (for example `item_01M1RWCB448HVT2EERNK5Y4RQK`).\nDo not use the internal numeric database ID or KRA `item_code` for public integrations." }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "e4a61764-b6f0-4853-b567-c910148cf2a6" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "51" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] }, { "name": "Create a new product\/item and sync to KRA when applicable.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/items", "query": [], "raw": "{{baseUrl}}\/api\/v1\/items" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"item_name\":\"Consulting Service\",\"item_classification_code\":\"5059690800\",\"tax_type_code\":\"B\",\"price\":1500,\"item_type_code\":3,\"packaging_unit_code\":\"NT\",\"quantity_unit_code\":\"BA\",\"barcode\":\"6001234567890\",\"origin_country_code\":\"KE\",\"is_active\":true,\"insurance_applicable\":\"N\",\"quantity\":0,\"external_product_id\":\"SKU-1001\",\"low_stock_threshold\":10}" }, "description": "The application **automatically generates** a unique KRA `item_code` using country of origin,\nproduct type, packaging unit, quantity unit, and a sequential number (for example `KE2NTBA0000012`).\nDo not send `item_code` in the request body.\n\nAfter local persistence, the item is synchronized with KRA. Opening stock initialization may be queued." }, "response": [] }, { "name": "Update an existing product\/item.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/items\/:itemId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/items\/:itemId", "variable": [ { "id": "itemId", "key": "itemId", "value": "item_01M1RWCB448HVT2EERNK5Y4RQK", "description": "Public item ID." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"item_name\":\"Consulting Service\",\"price\":1500,\"tax_type_code\":\"B\",\"external_product_id\":\"SKU-1001\",\"low_stock_threshold\":10}" }, "description": "Identify the item with public `item_id`. Only business-facing fields may be updated;\n`item_code`, stock quantity, classification, and unit codes remain immutable here." }, "response": [] } ] }, { "name": "Inventory & Stock", "description": "\nAdjust stock or transfer stock between branches. Identify items with public `item_id`.\nFor adjustments, `action` (`add` \/ `deduct`) maps automatically to KRA Stock Movement Types\n`06` and `16` \u2014 see [Stock Movement Type](\/docs\/code-definitions#stock-movement-type).", "item": [ { "name": "Adjust item stock.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/stock\/adjust", "query": [], "raw": "{{baseUrl}}\/api\/v1\/stock\/adjust" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"item_id\":\"item_01M1RWCB448HVT2EERNK5Y4RQK\",\"action\":\"add\",\"quantity\":10,\"reason_code\":\"PR\"}" }, "description": "Add or deduct stock for an item using its public `item_id`. The application resolves\nitem details and maps `action` to the KRA stock movement type:\n\n| action | KRA code | Meaning |\n| --- | --- | --- |\n| `add` | `06` | Adjustment Incoming |\n| `deduct` | `16` | Adjustment Outgoing |" }, "response": [] }, { "name": "Transfer stock to another branch.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/stock\/transfer", "query": [], "raw": "{{baseUrl}}\/api\/v1\/stock\/transfer" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"item_id\":\"item_01M1RWCB448HVT2EERNK5Y4RQK\",\"destination_branch_id\":\"branch_01M1RWCBA8KVT2EERNK5Y4RQK\",\"quantity\":10}" }, "description": "Move quantity from the authenticated branch to another branch in the same business.\nThe item is identified by public `item_id`. KRA movements use `13` (out) then `04` (in)." }, "response": [] } ] }, { "name": "Sales", "description": "\nSales credit notes are issued against successful sales. Reverse-invoice credit notes live under\n[Reverse Invoicing](#reverse-invoicing).", "item": [ { "name": "Get sales.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/sales", "query": [ { "key": "date_from", "value": "2026-09-01", "description": "date Start date (inclusive).", "disabled": false }, { "key": "to_date", "value": "2026-09-30", "description": "date Optional end date.", "disabled": false }, { "key": "status", "value": "success", "description": "Optional status filter.", "disabled": false }, { "key": "per_page", "value": "15", "description": "Optional page size.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/sales?date_from=2026-09-01&to_date=2026-09-30&status=success&per_page=15" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"date_from\":\"2026-09-29T21:30:10\",\"per_page\":1,\"cursor\":\"n\",\"limit\":7,\"status\":\"failed\",\"from_date\":\"2026-09-29T21:30:10\",\"to_date\":\"2052-10-22\",\"customer_pin\":\"ngzmiyvdljn\"}" }, "description": "Requires `date_from`. Lists local sales for the authenticated branch." }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "ef2ee6d2-fda8-44d5-9980-c26eb07ab5b7" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "49" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] }, { "name": "Get credit notes.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/sales\/credit-notes", "query": [ { "key": "date_from", "value": "2026-09-01", "description": "date Start date (inclusive).", "disabled": false }, { "key": "per_page", "value": "15", "description": "Optional page size.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/sales\/credit-notes?date_from=2026-09-01&per_page=15" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"date_from\":\"2026-09-29T21:30:10\",\"per_page\":1}" }, "description": "Requires `date_from`. Returns sales credit notes only (not reverse-invoice credit notes)." }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "f2a2890c-6738-4c92-9567-4a41788ccbcc" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "48" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] }, { "name": "Get sales credit note details.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/sales\/credit-notes\/:creditNoteId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/sales\/credit-notes\/:creditNoteId", "variable": [ { "id": "creditNoteId", "key": "creditNoteId", "value": "credit_note_01M1RWCB448HVT2EERNK5Y4RQK", "description": "Public credit note ID or number." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retrieve a sales credit note by public `credit_note_` ID or credit note number." }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "85988b21-9eee-4037-8bd7-cd40bb3b8850" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "47" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] }, { "name": "Get Sales \u2014 Including Credit Notes.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/sales\/:saleId\/with-credit-note", "query": [], "raw": "{{baseUrl}}\/api\/v1\/sales\/:saleId\/with-credit-note", "variable": [ { "id": "saleId", "key": "saleId", "value": "sale_01M1RWCB448HVT2EERNK5Y4RQK", "description": "Sale public ID or invoice number." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the sale together with any associated sales credit notes in the same response:\n\n Sales\n \u2514\u2500\u2500 Associated Sales Credit Notes\n\nUses public `sale_` \/ `credit_note_` IDs. Line items expose public `item_id` (not KRA `itemCd`)." }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "8ee05015-592d-436f-97f7-756b1bb04315" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "46" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] }, { "name": "Get sale details.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/sales\/:invoiceNumber", "query": [], "raw": "{{baseUrl}}\/api\/v1\/sales\/:invoiceNumber", "variable": [ { "id": "invoiceNumber", "key": "invoiceNumber", "value": "sale_01M1RWCB448HVT2EERNK5Y4RQK", "description": "Sale public ID or invoice number." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retrieve a sale by public `sale_` ID or invoice number." }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "10862cbe-dcfc-4664-9ea7-e991abc8bd25" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "45" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] }, { "name": "Create and process a sale\/invoice for the branch.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/sales", "query": [], "raw": "{{baseUrl}}\/api\/v1\/sales" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"external_sale_id\":\"b\",\"invoice_number\":\"n\",\"original_invoice_number\":\"g\",\"customer_id\":\"customer_01M1RWCB448HVT2EERNK5Y4RQK\",\"customer_pin\":\"ngzmiyvdljn\",\"customer_name\":\"i\",\"customer_mobile\":\"khwaykcmyuwpwlvq\",\"sales_type\":\"N\",\"receipt_type\":\"S\",\"payment_type\":\"01\",\"sale_date\":\"2026-09-10\",\"items\":[{\"item_id\":\"item_01M1RWCB448HVT2EERNK5Y4RQK\",\"item_code\":\"c\",\"item_classification_code\":\"p\",\"item_name\":\"s\",\"quantity\":1,\"unit_price\":116,\"tax_type_code\":\"C\",\"supply_amount\":50,\"discount_amount\":16,\"taxable_amount\":38,\"tax_amount\":57,\"total_amount\":52,\"packaging_unit_code\":\"rw\",\"quantity_unit_code\":\"t\",\"package_quantity\":33,\"discount_rate\":3,\"barcode\":\"w\"}],\"purchaser_acceptance\":false,\"remark\":\"b\",\"receipt_top_message\":\"ngzmiyvdljnikhwa\",\"receipt_bottom_message\":\"ykcmyuwpwlvqwrsi\"}" }, "description": "Add sale. Identify line items with public `item_id` (for example `item_01\u2026`).\nThe application resolves KRA item attributes from the local product record.\nEnumeration fields: [Code Definitions](\/docs\/code-definitions)\n(`sales_type` \u2192 Transaction Type, `payment_type` \u2192 Payment Method, tax types, units)." }, "response": [] }, { "name": "Add credit note.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/sales\/credit-notes", "query": [], "raw": "{{baseUrl}}\/api\/v1\/sales\/credit-notes" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"original_invoice_number\":\"architecto\",\"reason_code\":\"06\",\"reason_description\":\"architecto\",\"items\":[{\"item_id\":\"item_01M1RWCB448HVT2EERNK5Y4RQK\",\"item_code\":\"z\",\"item_name\":\"m\",\"quantity\":8,\"unit_price\":76,\"tax_type_code\":\"A\",\"tax_amount\":60,\"total_amount\":42,\"item_classification_code\":\"l\",\"packaging_unit_code\":\"jn\",\"quantity_unit_code\":\"i\",\"package_quantity\":75}]}" }, "description": "Issues a whole-receipt credit note against a successful sale.\nReason codes: see [Credit Note Reason](\/docs\/code-definitions#credit-note-reason).\nWhen supplying partial lines, identify products with public `item_id` (not KRA `itemCd`)." }, "response": [] } ] }, { "name": "Purchases", "description": "\nPurchases imported from eTIMS\/KRA into the local database (`purchase_source = etims`).\nThese are distinct from [Reverse Invoicing](#reverse-invoicing) records created in this application.", "item": [ { "name": "Get list of purchases pulled from eTIMS.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/purchases", "query": [ { "key": "date_from", "value": "2026-09-01", "description": "date Start date for the eTIMS pull (inclusive).", "disabled": false }, { "key": "per_page", "value": "15", "description": "Optional page size.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/purchases?date_from=2026-09-01&per_page=15" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"date_from\":\"2026-09-29T21:30:10\",\"per_page\":1}" }, "description": "Requires `date_from`. Synchronizes applicable purchases from eTIMS\/KRA into the local\ndatabase (idempotent), then returns the local eTIMS-imported purchase records with\npublic `purchase_` IDs. Does not return raw KRA payloads or reverse invoices." }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "524c4a1f-c7ea-4a49-b948-f559cf03a56b" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "44" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] }, { "name": "Get specific purchase details.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/purchases\/:purchaseId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/purchases\/:purchaseId", "variable": [ { "id": "purchaseId", "key": "purchaseId", "value": "purchase_01M1RWCB448HVT2EERNK5Y4RQK", "description": "Public purchase ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retrieves an eTIMS-imported purchase from the local database by public `purchase_id`.\nDoes not call KRA. Returns 404 for reverse invoices or purchases outside this branch." }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "baf0aeea-ec91-4172-9501-89d065484cf0" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "43" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] } ] }, { "name": "Reverse Invoicing", "description": "\nReverse invoices are purchases created within this application and submitted to KRA\/eTIMS.\nThey are stored with `purchase_source = reverse_invoice` and are distinct from\n[Purchases](#purchases) imported from eTIMS.", "item": [ { "name": "Get reverse invoices.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/reverse-invoices", "query": [ { "key": "date_from", "value": "2026-09-01", "description": "date Start date (inclusive).", "disabled": false }, { "key": "per_page", "value": "15", "description": "Optional page size.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/reverse-invoices?date_from=2026-09-01&per_page=15" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"date_from\":\"2026-09-29T21:30:10\",\"per_page\":1}" }, "description": "Requires `date_from`. Returns only locally created reverse invoices from the database\n(not eTIMS-imported purchases)." }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "dbcf1015-872e-4592-95af-69875f71ff0d" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "42" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] }, { "name": "Get reverse credit notes.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/reverse-invoices\/credit-notes", "query": [ { "key": "date_from", "value": "2026-09-01", "description": "date Start date (inclusive).", "disabled": false }, { "key": "per_page", "value": "15", "description": "Optional page size.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/reverse-invoices\/credit-notes?date_from=2026-09-01&per_page=15" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"date_from\":\"2026-09-29T21:30:10\",\"per_page\":1}" }, "description": "Requires `date_from`. Returns only credit notes issued against reverse invoices." }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "0bfa15fc-09ff-4369-ab40-649184942079" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "41" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] }, { "name": "Get reverse credit note details.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/reverse-invoices\/credit-notes\/:creditNoteId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/reverse-invoices\/credit-notes\/:creditNoteId", "variable": [ { "id": "creditNoteId", "key": "creditNoteId", "value": "credit_note_01M1RWCB448HVT2EERNK5Y4RQK", "description": "Public credit note ID or number." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retrieves a reverse-invoice credit note from the local database by public `credit_note_` ID\nor human `credit_note_number`." }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "76d9a79c-daee-4d02-aeab-dcd3a7d5ea1b" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "40" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] }, { "name": "Get reverse invoice details.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/reverse-invoices\/:purchaseId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/reverse-invoices\/:purchaseId", "variable": [ { "id": "purchaseId", "key": "purchaseId", "value": "purchase_01M1RWCB448HVT2EERNK5Y4RQK", "description": "Public purchase ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retrieves a reverse invoice from the local database by public `purchase_id`.\nReturns 404 if the ID refers to an eTIMS-imported purchase." }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "3d577fbc-976d-4c05-8094-dae6be3b37fb" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "39" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] }, { "name": "Add reverse invoice.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/reverse-invoices", "query": [], "raw": "{{baseUrl}}\/api\/v1\/reverse-invoices" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"external_purchase_id\":\"b\",\"supplier_id\":\"supplier_01H\u2026\",\"invoice_number\":\"n\",\"supplier_pin\":\"P051402944X\",\"supplier_name\":\"Acme Supplies\",\"supplier_branch_id\":\"hw\",\"supplier_invoice_number\":\"a\",\"purchase_date\":\"2026-09-10\",\"purchase_type_code\":\"C\",\"receipt_type_code\":\"R\",\"registration_type_code\":\"A\",\"items\":[{\"item_id\":\"item_01M1RWCB448HVT2EERNK5Y4RQK\",\"item_code\":\"i\",\"item_name\":\"y\",\"quantity\":1,\"unit_price\":116,\"tax_type_code\":\"E\",\"supply_amount\":37,\"taxable_amount\":9,\"tax_amount\":52,\"total_amount\":8,\"item_classification_code\":\"k\",\"packaging_unit_code\":\"hw\",\"quantity_unit_code\":\"a\",\"package_quantity\":50}],\"payment_type\":\"01\",\"remarks\":\"b\",\"total_taxable_amount\":39,\"total_tax_amount\":84,\"total_amount\":12}" }, "description": "Creates a purchase locally as a reverse invoice, assigns a public `purchase_` ID,\nand synchronizes it to KRA\/eTIMS using the existing purchase integration." }, "response": [] }, { "name": "Add reverse credit note.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/reverse-invoices\/credit-notes", "query": [], "raw": "{{baseUrl}}\/api\/v1\/reverse-invoices\/credit-notes" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"purchase_id\":\"purchase_01M1RWCB448HVT2EERNK5Y4RQK\",\"reason_code\":\"06\",\"reason_description\":\"Supplier refund\"}" }, "description": "Issues a whole-receipt credit note against a reverse invoice that was successfully\nsynchronized to KRA. Submitted via the purchase transaction endpoint (`insertTrnsPurchase`)\nwith `rcptTyCd = R` and `orgInvcNo` set from the original reverse invoice." }, "response": [] } ] }, { "name": "Imported Items", "description": "\nImport items received from eTIMS\/KRA and create import approvals against local products.\nPublic identifiers use the `import_` prefix. Linked products are referenced with public `item_id`.\nKRA enumeration fields: [Code Definitions](\/docs\/code-definitions).", "item": [ { "name": "Get list of import items received from eTIMS.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/imported-items", "query": [ { "key": "date_from", "value": "2026-09-01", "description": "date Start date for the eTIMS pull (inclusive).", "disabled": false }, { "key": "per_page", "value": "15", "description": "Optional page size.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/imported-items?date_from=2026-09-01&per_page=15" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"date_from\":\"2026-09-29T21:30:10\",\"per_page\":1}" }, "description": "Requires `date_from`. Requests import items from KRA\/eTIMS, synchronizes them into the\nlocal database (idempotent \u2014 duplicates are not created), assigns `import_` public IDs,\nthen returns the local records. Does not return the raw KRA response." }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "49477a7c-4f30-4c85-ab98-e5908c294657" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "50" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] }, { "name": "Create import item.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/imported-items", "query": [], "raw": "{{baseUrl}}\/api\/v1\/imported-items" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"item_id\":\"item_01M1RWCB448HVT2EERNK5Y4RQK\",\"task_code\":\"202409001\",\"declaration_date\":\"2026-09-01\",\"item_seq\":1,\"hs_code\":\"00\",\"remark\":\"architecto\"}" }, "description": "Links an existing local product via public `item_id`. The application resolves KRA fields\n(`itemCd`, `itemClsCd`, etc.) from that product and submits the import update to eTIMS.\nSee [Import Item Status](\/docs\/code-definitions#import-item-status)." }, "response": [] } ] }, { "name": "Reports", "description": "\nBusiness-level reporting across all branches of the authenticated business.\nTotals include only transactions with successful KRA\/eTIMS synchronization (`status = success`).", "item": [ { "name": "Get Business Report.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/reports\/business", "query": [ { "key": "date_from", "value": "2026-09-01", "description": "date Start of the reporting period (YYYY-MM-DD).", "disabled": false }, { "key": "date_to", "value": "2026-09-17", "description": "date End of the reporting period (YYYY-MM-DD).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/reports\/business?date_from=2026-09-01&date_to=2026-09-17" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"date_from\":\"2026-09-29T21:30:10\",\"date_to\":\"2052-10-22\"}" }, "description": "Returns a consolidated report for `date_from` \u2192 `date_to` with:\n\n- `business_report` \u2014 totals for the entire authenticated business\n- `branches` \u2014 the same structure broken down by each business branch\n\n**Included figures (successfully synced to KRA only):**\n- Sales: `status = success`, filtered by `sale_date`\n- Sales credit notes: sales document type only (`document_type = sale`), `status = success`, filtered by `created_at`\n- Purchases: eTIMS-imported purchases **and** reverse invoices with `status = success`, filtered by `purchase_date`\n\nReverse-invoice (purchase) credit notes are **not** included in the sales credit-note figures\nand are not netted from purchase totals in this report.\n\nAuthentication: Business API Key or Branch API Key for the same business." }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"success\",\n \"data\": {\n \"date_from\": \"2026-09-01\",\n \"date_to\": \"2026-09-17\",\n \"business_report\": {\n \"sales\": {\"successful_synced_value\": 1160.0, \"vat\": 160.0},\n \"credit_notes\": {\"successful_synced_value\": 116.0, \"vat\": 16.0},\n \"purchases\": {\"successful_synced_value\": 2320.0, \"vat\": 320.0}\n },\n \"branches\": [\n {\n \"branch_id\": \"branch_01M1RWCB448HVT2EERNK5Y4RQK\",\n \"branch_name\": \"Main Branch\",\n \"report\": {\n \"sales\": {\"successful_synced_value\": 1160.0, \"vat\": 160.0},\n \"credit_notes\": {\"successful_synced_value\": 116.0, \"vat\": 16.0},\n \"purchases\": {\"successful_synced_value\": 2320.0, \"vat\": 320.0}\n }\n }\n ]\n }\n}", "name": "success" } ] } ] }, { "name": "Notices", "description": "\nLocally stored KRA notices for the authenticated business\/branch context.\nCode definitions are documented separately under [Code Definitions](\/docs\/code-definitions).", "item": [ { "name": "Get list of KRA notices for business.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/notices", "query": [ { "key": "search", "value": "VAT", "description": "Optional search.", "disabled": false }, { "key": "per_page", "value": "20", "description": "Optional page size.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/notices?search=VAT&per_page=20" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"refresh\":false,\"search\":\"b\",\"per_page\":22}" }, "description": "Returns notices already stored in the local database. Does not call KRA unless\nan explicit refresh is requested (hidden from public docs)." }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-transaction-reference", "value": "86d0810a-25c6-481a-865d-c7f02dbd7d06" }, { "key": "x-ratelimit-limit", "value": "60" }, { "key": "x-ratelimit-remaining", "value": "55" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-allow-methods", "value": "GET, POST, PUT, PATCH, DELETE, OPTIONS" }, { "key": "access-control-allow-headers", "value": "Content-Type, X-API-Key, X-Transaction-Reference, Accept, Authorization" }, { "key": "access-control-allow-credentials", "value": "true" }, { "key": "access-control-expose-headers", "value": "X-Transaction-Reference, X-RateLimit-Limit, X-RateLimit-Remaining" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "x-xss-protection", "value": "1; mode=block" }, { "key": "content-security-policy", "value": "default-src 'self' https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:\/\/cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https:\/\/cdn.jsdelivr.net; img-src 'self' data: https:; font-src 'self' https: data:;" } ], "code": 401, "body": "{\"status\":\"error\",\"message\":\"Invalid API key\",\"error_code\":\"INVALID_API_KEY\"}", "name": "" } ] } ] } ], "auth": { "type": "apikey", "apikey": [ { "key": "in", "value": "header", "type": "string" }, { "key": "key", "value": "X-API-Key", "type": "string" } ] } }