{"openapi":"3.0.3","info":{"title":"AltiTax API","description":"Public AltiTax API for KRA eTIMS Integrator. Authenticate with the X-API-Key header using a Business API Key (business-scoped endpoints) or a Branch API Key (branch operations). Enumeration values are documented under [Code Definitions](/docs/code-definitions).","version":"1.0.0"},"servers":[{"url":"http://localhost:8000"}],"tags":[{"name":"Business","description":""},{"name":"Credits & Subscriptions","description":""},{"name":"Customers","description":""},{"name":"Suppliers","description":""},{"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)."},{"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` — see [Stock Movement Type](/docs/code-definitions#stock-movement-type)."},{"name":"Sales","description":"\nSales credit notes are issued against successful sales. Reverse-invoice credit notes live under\n[Reverse Invoicing](#reverse-invoicing)."},{"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."},{"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."},{"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)."},{"name":"Reports","description":"\nBusiness-level reporting across all branches of the authenticated business.\nTotals include only transactions with successful KRA/eTIMS synchronization (`status = 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)."}],"components":{"securitySchemes":{"BusinessApiKey":{"type":"apiKey","name":"X-API-Key","in":"header","description":"Business API Key — authenticates requests within the scope of the associated business. Use for business-scoped endpoints such as credits, listing branches, and suppliers. Obtain from Settings > API Settings. Placeholder: YOUR_BUSINESS_API_KEY"},"BranchApiKey":{"type":"apiKey","name":"X-API-Key","in":"header","description":"Branch API Key — authenticates requests within the scope of the associated branch only. Required for sales, items, stock, device initialization, credit notes, and related branch workflows. May also call business-scoped endpoints for the same business. Placeholder: YOUR_BRANCH_API_KEY"}}},"security":[{"BranchApiKey":[]},{"BusinessApiKey":[]}],"paths":{"/api/v1/branches":{"get":{"summary":"List all branches for the authenticated business.","operationId":"listAllBranchesForTheAuthenticatedBusiness","description":"**Authentication:** Accepts a Business API Key or a Branch API Key for the same business.","parameters":[{"in":"header","name":"X-API-Key","description":"Business API Key or Branch API Key for this business-scoped endpoint.","example":"YOUR_BUSINESS_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Business"],"security":[{"BusinessApiKey":[]},{"BranchApiKey":[]}]}},"/api/v1/credits/balance":{"get":{"summary":"Get the current credit balance for the authenticated business.","operationId":"getTheCurrentCreditBalanceForTheAuthenticatedBusiness","description":"**Authentication:** Accepts a Business API Key or a Branch API Key for the same business.","parameters":[{"in":"header","name":"X-API-Key","description":"Business API Key or Branch API Key for this business-scoped endpoint.","example":"YOUR_BUSINESS_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Credits & Subscriptions"],"security":[{"BusinessApiKey":[]},{"BranchApiKey":[]}]}},"/api/v1/customers/taxpayer-info":{"post":{"summary":"Look up taxpayer information for a customer KRA PIN.","operationId":"lookUpTaxpayerInformationForACustomerKRAPIN","description":"Retrieves taxpayer information associated with the supplied customer KRA PIN.\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":[],"tags":["Customers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_pin":{"type":"string","description":"Must match the regex /^[A-Z][0-9]{9}[A-Z]$/. Must be 11 characters.","example":"bngzmiyvdlj"},"refresh":{"type":"boolean","description":"","example":false}},"required":["customer_pin"]}}}},"security":[{"BranchApiKey":[]}]}},"/api/v1/customers":{"get":{"summary":"Get a list of business customers.","operationId":"getAListOfBusinessCustomers","description":"Returns customers belonging to the authenticated business. Supports\nsearch, is_active filter, and pagination via per_page.\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Customers"],"security":[{"BranchApiKey":[]}]},"post":{"summary":"Create a new customer within the authenticated branch.","operationId":"createANewCustomerWithinTheAuthenticatedBranch","description":"**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":[],"tags":["Customers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_pin":{"type":"string","description":"Must match the regex /^[A-Z][0-9]{9}[A-Z]$/. Must be 11 characters.","example":"bngzmiyvdlj"},"customer_name":{"type":"string","description":"Must not be greater than 255 characters.","example":"n"},"customer_type":{"type":"string","description":"","example":"government","enum":["individual","company","government","non_profit"]},"phone":{"type":"string","description":"Must not be greater than 20 characters.","example":"ikhwaykcmyuwpwlv","nullable":true},"email":{"type":"string","description":"Must be a valid email address. Must not be greater than 255 characters.","example":"leo34@example.net","nullable":true},"address":{"type":"string","description":"Must not be greater than 500 characters.","example":"t","nullable":true},"county":{"type":"string","description":"Must not be greater than 100 characters.","example":"c","nullable":true},"district":{"type":"string","description":"Must not be greater than 100 characters.","example":"p","nullable":true},"sector":{"type":"string","description":"Must not be greater than 100 characters.","example":"s","nullable":true},"location_description":{"type":"string","description":"Must not be greater than 500 characters.","example":"c","nullable":true},"notes":{"type":"string","description":"Must not be greater than 1000 characters.","example":"q","nullable":true},"is_active":{"type":"boolean","description":"","example":false}},"required":["customer_pin","customer_name"]}}}},"security":[{"BranchApiKey":[]}]}},"/api/v1/customers/{id}":{"get":{"summary":"Retrieve a customer by public customer ID.","operationId":"retrieveACustomerByPublicCustomerID","description":"**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Customers"],"security":[{"BranchApiKey":[]}]},"put":{"summary":"Update an existing customer.","operationId":"updateAnExistingCustomer","description":"**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":[],"tags":["Customers"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_name":{"type":"string","description":"Must not be greater than 255 characters.","example":"b"},"customer_type":{"type":"string","description":"","example":"individual","enum":["individual","company","government","non_profit"]},"phone":{"type":"string","description":"Must not be greater than 20 characters.","example":"ngzmiyvdljnikhwa","nullable":true},"email":{"type":"string","description":"Must be a valid email address. Must not be greater than 255 characters.","example":"breitenberg.gilbert@example.com","nullable":true},"address":{"type":"string","description":"Must not be greater than 500 characters.","example":"u","nullable":true},"county":{"type":"string","description":"Must not be greater than 100 characters.","example":"w","nullable":true},"district":{"type":"string","description":"Must not be greater than 100 characters.","example":"p","nullable":true},"sector":{"type":"string","description":"Must not be greater than 100 characters.","example":"w","nullable":true},"location_description":{"type":"string","description":"Must not be greater than 500 characters.","example":"l","nullable":true},"notes":{"type":"string","description":"Must not be greater than 1000 characters.","example":"v","nullable":true},"is_active":{"type":"boolean","description":"","example":true}}}}}},"security":[{"BranchApiKey":[]}]},"parameters":[{"in":"path","name":"id","description":"The ID of the customer.","example":"architecto","required":true,"schema":{"type":"string"}}]},"/api/v1/suppliers":{"get":{"summary":"List suppliers for the authenticated business.","operationId":"listSuppliersForTheAuthenticatedBusiness","description":"**Authentication:** Accepts a Business API Key or a Branch API Key for the same business.","parameters":[{"in":"header","name":"X-API-Key","description":"Business API Key or Branch API Key for this business-scoped endpoint.","example":"YOUR_BUSINESS_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Suppliers"],"security":[{"BusinessApiKey":[]},{"BranchApiKey":[]}]},"post":{"summary":"Create a new supplier for the business.","operationId":"createANewSupplierForTheBusiness","description":"**Authentication:** Accepts a Business API Key or a Branch API Key for the same business.","parameters":[{"in":"header","name":"X-API-Key","description":"Business API Key or Branch API Key for this business-scoped endpoint.","example":"YOUR_BUSINESS_API_KEY","schema":{"type":"string"}}],"responses":[],"tags":["Suppliers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"supplier_pin":{"type":"string","description":"Must match the regex /^[A-Z][0-9]{9}[A-Z]$/. Must be 11 characters.","example":"bngzmiyvdlj"},"supplier_name":{"type":"string","description":"Must not be greater than 255 characters.","example":"n"},"supplier_type":{"type":"string","description":"","example":"non_profit","enum":["individual","company","government","non_profit"]},"default_branch_id":{"type":"string","description":"Must be 2 characters.","example":"ik","nullable":true},"phone":{"type":"string","description":"Must not be greater than 20 characters.","example":"hwaykcmyuwpwlvqw","nullable":true},"email":{"type":"string","description":"Must be a valid email address. Must not be greater than 255 characters.","example":"imclaughlin@example.org","nullable":true},"address":{"type":"string","description":"Must not be greater than 500 characters.","example":"c","nullable":true},"county":{"type":"string","description":"Must not be greater than 100 characters.","example":"p","nullable":true},"district":{"type":"string","description":"Must not be greater than 100 characters.","example":"s","nullable":true},"sector":{"type":"string","description":"Must not be greater than 100 characters.","example":"c","nullable":true},"location_description":{"type":"string","description":"Must not be greater than 500 characters.","example":"q","nullable":true},"notes":{"type":"string","description":"Must not be greater than 1000 characters.","example":"l","nullable":true},"is_active":{"type":"boolean","description":"","example":false}},"required":["supplier_pin","supplier_name"]}}}},"security":[{"BusinessApiKey":[]},{"BranchApiKey":[]}]}},"/api/v1/suppliers/{id}":{"get":{"summary":"Retrieve a supplier by public supplier ID.","operationId":"retrieveASupplierByPublicSupplierID","description":"**Authentication:** Accepts a Business API Key or a Branch API Key for the same business.","parameters":[{"in":"header","name":"X-API-Key","description":"Business API Key or Branch API Key for this business-scoped endpoint.","example":"YOUR_BUSINESS_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Suppliers"],"security":[{"BusinessApiKey":[]},{"BranchApiKey":[]}]},"put":{"summary":"Update an existing supplier.","operationId":"updateAnExistingSupplier","description":"**Authentication:** Accepts a Business API Key or a Branch API Key for the same business.","parameters":[{"in":"header","name":"X-API-Key","description":"Business API Key or Branch API Key for this business-scoped endpoint.","example":"YOUR_BUSINESS_API_KEY","schema":{"type":"string"}}],"responses":[],"tags":["Suppliers"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"supplier_pin":{"type":"string","description":"Must match the regex /^[A-Z][0-9]{9}[A-Z]$/. Must be 11 characters.","example":"bngzmiyvdlj"},"supplier_name":{"type":"string","description":"Must not be greater than 255 characters.","example":"n"},"supplier_type":{"type":"string","description":"","example":"individual","enum":["individual","company","government","non_profit"]},"default_branch_id":{"type":"string","description":"Must be 2 characters.","example":"ik","nullable":true},"phone":{"type":"string","description":"Must not be greater than 20 characters.","example":"hwaykcmyuwpwlvqw","nullable":true},"email":{"type":"string","description":"Must be a valid email address. Must not be greater than 255 characters.","example":"imclaughlin@example.org","nullable":true},"address":{"type":"string","description":"Must not be greater than 500 characters.","example":"c","nullable":true},"county":{"type":"string","description":"Must not be greater than 100 characters.","example":"p","nullable":true},"district":{"type":"string","description":"Must not be greater than 100 characters.","example":"s","nullable":true},"sector":{"type":"string","description":"Must not be greater than 100 characters.","example":"c","nullable":true},"location_description":{"type":"string","description":"Must not be greater than 500 characters.","example":"q","nullable":true},"notes":{"type":"string","description":"Must not be greater than 1000 characters.","example":"l","nullable":true},"is_active":{"type":"boolean","description":"","example":true}}}}}},"security":[{"BusinessApiKey":[]},{"BranchApiKey":[]}]},"parameters":[{"in":"path","name":"id","description":"The ID of the supplier.","example":"architecto","required":true,"schema":{"type":"string"}}]},"/api/v1/items":{"get":{"summary":"List products/items for the authenticated branch.","operationId":"listProductsitemsForTheAuthenticatedBranch","description":"Returns active items for the branch. Responses use public `item_id` and tax-inclusive `price`.\nSynchronization and internal stock metadata are not included.\n\nKRA enumeration fields reference [Code Definitions](/docs/code-definitions). `price` is the tax-inclusive selling price. Public identifier is `item_id`.\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Items / Products"],"security":[{"BranchApiKey":[]}]},"post":{"summary":"Create a new product/item and sync to KRA when applicable.","operationId":"createANewProductitemAndSyncToKRAWhenApplicable","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.\n\nKRA enumeration fields reference [Code Definitions](/docs/code-definitions). `price` is the tax-inclusive selling price. Public identifier is `item_id`.\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":[],"tags":["Items / Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"item_name":{"type":"string","description":"Display name of the product/item.","example":"Consulting Service"},"item_classification_code":{"type":"string","description":"KRA item classification code. See [Item Classification](/docs/code-definitions#item-classification). See [Code Definitions — Item Classification](/docs/code-definitions#item-classification).","example":"5059690800"},"tax_type_code":{"type":"string","description":"KRA tax type. See [Tax Type](/docs/code-definitions#tax-type). See [Code Definitions — Tax Type](/docs/code-definitions#tax-type).","example":"B"},"price":{"type":"number","description":"Tax-inclusive selling price.","example":1500},"item_type_code":{"type":"integer","description":"KRA product type. See [Product Type](/docs/code-definitions#product-type). See [Code Definitions — Product Type](/docs/code-definitions#product-type).","example":3},"packaging_unit_code":{"type":"string","description":"Optional KRA packaging unit (defaults to NT). See [Packaging Unit](/docs/code-definitions#packaging-unit). See [Code Definitions — Packaging Unit](/docs/code-definitions#packaging-unit).","example":"NT","nullable":true},"quantity_unit_code":{"type":"string","description":"KRA unit of quantity. See [Unit of Quantity](/docs/code-definitions#unit-of-quantity). See [Code Definitions — Unit of Quantity](/docs/code-definitions#unit-of-quantity).","example":"BA"},"barcode":{"type":"string","description":"Optional barcode.","example":"6001234567890","nullable":true},"origin_country_code":{"type":"string","description":"Optional ISO country code (defaults to KE). See [Country Codes](/docs/code-definitions#country-codes). See [Code Definitions — Country Codes](/docs/code-definitions#country-codes).","example":"KE","nullable":true},"is_active":{"type":"boolean","description":"Optional. Defaults to true.","example":true,"nullable":true},"insurance_applicable":{"type":"string","description":"Whether insurance applies (`Y`/`N`). Defaults to `N`.","example":"N","enum":["Y","N"],"nullable":true},"additional_info":{"type":"string","description":"Optional free-text notes sent to KRA as additional information.","example":null,"nullable":true},"quantity":{"type":"number","description":"Optional opening stock quantity.","example":0,"nullable":true},"external_product_id":{"type":"string","description":"Optional external system product ID.","example":"SKU-1001","nullable":true},"low_stock_threshold":{"type":"number","description":"Optional low-stock alert threshold. Must be at least 0.","example":10,"nullable":true}},"required":["item_name","item_classification_code","tax_type_code","price","item_type_code","quantity_unit_code"]}}}},"security":[{"BranchApiKey":[]}]}},"/api/v1/items/{itemId}":{"get":{"summary":"Retrieve a product/item by item_id.","operationId":"retrieveAProductitemByItemId","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.\n\nKRA enumeration fields reference [Code Definitions](/docs/code-definitions). `price` is the tax-inclusive selling price. Public identifier is `item_id`.\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Items / Products"],"security":[{"BranchApiKey":[]}]},"put":{"summary":"Update an existing product/item.","operationId":"updateAnExistingProductitem","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.\n\nKRA enumeration fields reference [Code Definitions](/docs/code-definitions). `price` is the tax-inclusive selling price. Public identifier is `item_id`.\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":[],"tags":["Items / Products"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"item_name":{"type":"string","description":"Optional updated name.","example":"Consulting Service"},"price":{"type":"number","description":"Optional tax-inclusive selling price.","example":1500},"tax_type_code":{"type":"string","description":"Optional KRA tax type. See [Tax Type](/docs/code-definitions#tax-type). See [Code Definitions — Tax Type](/docs/code-definitions#tax-type).","example":"B"},"external_product_id":{"type":"string","description":"Optional external system product ID.","example":"SKU-1001","nullable":true},"low_stock_threshold":{"type":"number","description":"Optional low-stock threshold.","example":10}}}}}},"security":[{"BranchApiKey":[]}]},"parameters":[{"in":"path","name":"itemId","description":"Public item ID.","example":"item_01M1RWCB448HVT2EERNK5Y4RQK","required":true,"schema":{"type":"string"}}]},"/api/v1/stock/adjust":{"post":{"summary":"Adjust item stock.","operationId":"adjustItemStock","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 |\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":[],"tags":["Inventory & Stock"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"item_id":{"type":"string","description":"Public item ID.","example":"item_01M1RWCB448HVT2EERNK5Y4RQK"},"action":{"type":"string","description":"Either `add` or `deduct`.","example":"add"},"quantity":{"type":"number","description":"Quantity to add or deduct.","example":10},"reason_code":{"type":"string","description":"Optional local stock-adjustment reason. When omitted, add uses `06` and deduct uses `16`. Must not be greater than 10 characters. See [Code Definitions — Credit Note Reason](/docs/code-definitions#credit-note-reason).","example":"PR","nullable":true}},"required":["item_id","action","quantity"]}}}},"security":[{"BranchApiKey":[]}]}},"/api/v1/stock/transfer":{"post":{"summary":"Transfer stock to another branch.","operationId":"transferStockToAnotherBranch","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).\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":[],"tags":["Inventory & Stock"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"item_id":{"type":"string","description":"Public item ID at the source branch.","example":"item_01M1RWCB448HVT2EERNK5Y4RQK"},"destination_branch_id":{"type":"string","description":"Public destination branch ID.","example":"branch_01M1RWCBA8KVT2EERNK5Y4RQK"},"quantity":{"type":"number","description":"Quantity to transfer.","example":10}},"required":["item_id","destination_branch_id","quantity"]}}}},"security":[{"BranchApiKey":[]}]}},"/api/v1/sales":{"get":{"summary":"Get sales.","operationId":"getSales","description":"Requires `date_from`. Lists local sales for the authenticated branch.\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"query","name":"date_from","description":"date Start date (inclusive).","example":"2026-09-01","required":true,"schema":{"type":"string","description":"date Start date (inclusive).","example":"2026-09-01"}},{"in":"query","name":"to_date","description":"date Optional end date.","example":"2026-09-30","required":false,"schema":{"type":"string","description":"date Optional end date.","example":"2026-09-30"}},{"in":"query","name":"status","description":"Optional status filter.","example":"success","required":false,"schema":{"type":"string","description":"Optional status filter.","example":"success"}},{"in":"query","name":"per_page","description":"Optional page size.","example":15,"required":false,"schema":{"type":"integer","description":"Optional page size.","example":15}},{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Sales"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date_from":{"type":"string","description":"Must be a valid date.","example":"2026-09-29T21:30:10"},"per_page":{"type":"integer","description":"Must be at least 1. Must not be greater than 100.","example":1,"nullable":true},"cursor":{"type":"string","description":"Must not be greater than 64 characters.","example":"n","nullable":true},"limit":{"type":"integer","description":"Must be at least 1. Must not be greater than 1000.","example":7,"nullable":true},"status":{"type":"string","description":"","example":"failed","enum":["pending","success","failed"],"nullable":true},"from_date":{"type":"string","description":"Must be a valid date.","example":"2026-09-29T21:30:10","nullable":true},"to_date":{"type":"string","description":"Must be a valid date. Must be a date after or equal to <code>date_from</code>.","example":"2052-10-22","nullable":true},"customer_pin":{"type":"string","description":"Must be 11 characters.","example":"ngzmiyvdljn","nullable":true}},"required":["date_from"]}}}},"security":[{"BranchApiKey":[]}]},"post":{"summary":"Create and process a sale/invoice for the branch.","operationId":"createAndProcessASaleinvoiceForTheBranch","description":"Add sale. Identify line items with public `item_id` (for example `item_01…`).\nThe application resolves KRA item attributes from the local product record.\nEnumeration fields: [Code Definitions](/docs/code-definitions)\n(`sales_type` → Transaction Type, `payment_type` → Payment Method, tax types, units).\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":[],"tags":["Sales"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"external_sale_id":{"type":"string","description":"Must not be greater than 255 characters.","example":"b","nullable":true},"invoice_number":{"type":"string","description":"Must not be greater than 50 characters.","example":"n","nullable":true},"original_invoice_number":{"type":"string","description":"Must not be greater than 50 characters.","example":"g","nullable":true},"customer_id":{"type":"string","description":"Public customer ID.","example":"customer_01M1RWCB448HVT2EERNK5Y4RQK"},"customer_pin":{"type":"string","description":"Must match the regex /^[A-Z][0-9]{9}[A-Z]$/. Must be 11 characters.","example":"ngzmiyvdljn"},"customer_name":{"type":"string","description":"Must not be greater than 255 characters.","example":"i"},"customer_mobile":{"type":"string","description":"Must not be greater than 20 characters.","example":"khwaykcmyuwpwlvq","nullable":true},"sales_type":{"type":"string","description":"Sales / transaction type. See [Transaction Type](/docs/code-definitions#transaction-type). See [Code Definitions — Transaction Type](/docs/code-definitions#transaction-type).","example":"N"},"receipt_type":{"type":"string","description":"See [Code Definitions — Sales Receipt Type](/docs/code-definitions#sales-receipt-type).","example":"S","enum":["S","R"]},"payment_type":{"type":"string","description":"Payment method. See [Payment Method](/docs/code-definitions#payment-method). See [Code Definitions — Payment Method](/docs/code-definitions#payment-method).","example":"01"},"sale_date":{"type":"date","description":"Sale date.","example":"2026-09-10"},"items":{"type":"array","description":"Line items. Each line requires `item_id`.","example":[[]],"items":{"type":"object","properties":{"item_id":{"type":"string","description":"Public item ID.","example":"item_01M1RWCB448HVT2EERNK5Y4RQK","nullable":true},"item_code":{"type":"string","description":"This field is required when <code>items.*.item_id</code> is not present. Must not be greater than 50 characters.","example":"c","nullable":true},"item_classification_code":{"type":"string","description":"Must not be greater than 50 characters. See [Code Definitions — Item Classification](/docs/code-definitions#item-classification).","example":"p","nullable":true},"item_name":{"type":"string","description":"Must not be greater than 255 characters.","example":"s","nullable":true},"quantity":{"type":"number","description":"Quantity.","example":1},"unit_price":{"type":"number","description":"Optional tax-inclusive unit price (defaults from item).","example":116,"nullable":true},"tax_type_code":{"type":"string","description":"See [Code Definitions — Tax Type](/docs/code-definitions#tax-type).","example":"C","enum":["A","B","C","D"],"nullable":true},"supply_amount":{"type":"number","description":"Must be at least 0.","example":50,"nullable":true},"discount_amount":{"type":"number","description":"Must be at least 0.","example":16,"nullable":true},"taxable_amount":{"type":"number","description":"Must be at least 0.","example":38,"nullable":true},"tax_amount":{"type":"number","description":"Must be at least 0.","example":57,"nullable":true},"total_amount":{"type":"number","description":"Must be at least 0.","example":52,"nullable":true},"packaging_unit_code":{"type":"string","description":"Must not be greater than 2 characters. See [Code Definitions — Packaging Unit](/docs/code-definitions#packaging-unit).","example":"rw","nullable":true},"quantity_unit_code":{"type":"string","description":"Must not be greater than 3 characters. See [Code Definitions — Unit of Quantity](/docs/code-definitions#unit-of-quantity).","example":"t","nullable":true},"package_quantity":{"type":"number","description":"Must be at least 0.","example":33,"nullable":true},"discount_rate":{"type":"number","description":"Must be at least 0. Must not be greater than 100.","example":3,"nullable":true},"barcode":{"type":"string","description":"Must not be greater than 100 characters.","example":"w","nullable":true}},"required":["item_id","quantity"]}},"purchaser_acceptance":{"type":"boolean","description":"","example":false,"nullable":true},"remark":{"type":"string","description":"Must not be greater than 500 characters.","example":"b","nullable":true},"receipt_top_message":{"type":"string","description":"Must not be greater than 20 characters.","example":"ngzmiyvdljnikhwa","nullable":true},"receipt_bottom_message":{"type":"string","description":"Must not be greater than 20 characters.","example":"ykcmyuwpwlvqwrsi","nullable":true}},"required":["customer_id","customer_pin","customer_name","sales_type","payment_type","sale_date","items"]}}}},"security":[{"BranchApiKey":[]}]}},"/api/v1/sales/credit-notes":{"get":{"summary":"Get credit notes.","operationId":"getCreditNotes","description":"Requires `date_from`. Returns sales credit notes only (not reverse-invoice credit notes).\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"query","name":"date_from","description":"date Start date (inclusive).","example":"2026-09-01","required":true,"schema":{"type":"string","description":"date Start date (inclusive).","example":"2026-09-01"}},{"in":"query","name":"per_page","description":"Optional page size.","example":15,"required":false,"schema":{"type":"integer","description":"Optional page size.","example":15}},{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Sales"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date_from":{"type":"string","description":"Must be a valid date.","example":"2026-09-29T21:30:10"},"per_page":{"type":"integer","description":"Must be at least 1. Must not be greater than 100.","example":1}},"required":["date_from"]}}}},"security":[{"BranchApiKey":[]}]},"post":{"summary":"Add credit note.","operationId":"addCreditNote","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`).\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":[],"tags":["Sales"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"original_invoice_number":{"type":"string","description":"Original sale invoice number.","example":"architecto"},"reason_code":{"type":"string","description":"Credit Note Reason Code (01–06). See [Credit Note Reason](/docs/code-definitions#credit-note-reason). See [Code Definitions — Credit Note Reason](/docs/code-definitions#credit-note-reason).","example":"06"},"reason_description":{"type":"string","description":"Optional details.","example":"architecto","nullable":true},"items":{"type":"array","description":"Optional partial lines; omit to credit the entire receipt.","example":[[]],"items":{"type":"object","nullable":true,"properties":{"item_id":{"type":"string","description":"Public item ID when items are provided.","example":"item_01M1RWCB448HVT2EERNK5Y4RQK","nullable":true},"item_code":{"type":"string","description":"This field is required when <code>items.*.item_id</code> is not present. Must not be greater than 50 characters.","example":"z","nullable":true},"item_name":{"type":"string","description":"Must not be greater than 255 characters.","example":"m","nullable":true},"quantity":{"type":"number","description":"This field is required when <code>items</code> is present. Must be at least 0.01.","example":8},"unit_price":{"type":"number","description":"Must be at least 0.","example":76,"nullable":true},"tax_type_code":{"type":"string","description":"See [Code Definitions — Tax Type](/docs/code-definitions#tax-type).","example":"A","enum":["A","B","C","D","E"],"nullable":true},"tax_amount":{"type":"number","description":"Must be at least 0.","example":60,"nullable":true},"total_amount":{"type":"number","description":"Must be at least 0.","example":42,"nullable":true},"item_classification_code":{"type":"string","description":"Must not be greater than 50 characters. See [Code Definitions — Item Classification](/docs/code-definitions#item-classification).","example":"l","nullable":true},"packaging_unit_code":{"type":"string","description":"Must be 2 characters. See [Code Definitions — Packaging Unit](/docs/code-definitions#packaging-unit).","example":"jn","nullable":true},"quantity_unit_code":{"type":"string","description":"Must not be greater than 3 characters. See [Code Definitions — Unit of Quantity](/docs/code-definitions#unit-of-quantity).","example":"i","nullable":true},"package_quantity":{"type":"number","description":"Must be at least 0.","example":75,"nullable":true}}}}},"required":["original_invoice_number","reason_code"]}}}},"security":[{"BranchApiKey":[]}]}},"/api/v1/sales/credit-notes/{creditNoteId}":{"get":{"summary":"Get sales credit note details.","operationId":"getSalesCreditNoteDetails","description":"Retrieve a sales credit note by public `credit_note_` ID or credit note number.\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Sales"],"security":[{"BranchApiKey":[]}]},"parameters":[{"in":"path","name":"creditNoteId","description":"Public credit note ID or number.","example":"credit_note_01M1RWCB448HVT2EERNK5Y4RQK","required":true,"schema":{"type":"string"}}]},"/api/v1/sales/{saleId}/with-credit-note":{"get":{"summary":"Get Sales — Including Credit Notes.","operationId":"getSalesIncludingCreditNotes","description":"Returns the sale together with any associated sales credit notes in the same response:\n\n    Sales\n       └── Associated Sales Credit Notes\n\nUses public `sale_` / `credit_note_` IDs. Line items expose public `item_id` (not KRA `itemCd`).\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Sales"],"security":[{"BranchApiKey":[]}]},"parameters":[{"in":"path","name":"saleId","description":"Sale public ID or invoice number.","example":"sale_01M1RWCB448HVT2EERNK5Y4RQK","required":true,"schema":{"type":"string"}}]},"/api/v1/sales/{invoiceNumber}":{"get":{"summary":"Get sale details.","operationId":"getSaleDetails","description":"Retrieve a sale by public `sale_` ID or invoice number.\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Sales"],"security":[{"BranchApiKey":[]}]},"parameters":[{"in":"path","name":"invoiceNumber","description":"Sale public ID or invoice number.","example":"sale_01M1RWCB448HVT2EERNK5Y4RQK","required":true,"schema":{"type":"string"}}]},"/api/v1/purchases":{"get":{"summary":"Get list of purchases pulled from eTIMS.","operationId":"getListOfPurchasesPulledFromETIMS","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.\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"query","name":"date_from","description":"date Start date for the eTIMS pull (inclusive).","example":"2026-09-01","required":true,"schema":{"type":"string","description":"date Start date for the eTIMS pull (inclusive).","example":"2026-09-01"}},{"in":"query","name":"per_page","description":"Optional page size.","example":15,"required":false,"schema":{"type":"integer","description":"Optional page size.","example":15}},{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Purchases"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date_from":{"type":"string","description":"Must be a valid date.","example":"2026-09-29T21:30:10"},"per_page":{"type":"integer","description":"Must be at least 1. Must not be greater than 100.","example":1}},"required":["date_from"]}}}},"security":[{"BranchApiKey":[]}]}},"/api/v1/purchases/{purchaseId}":{"get":{"summary":"Get specific purchase details.","operationId":"getSpecificPurchaseDetails","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.\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Purchases"],"security":[{"BranchApiKey":[]}]},"parameters":[{"in":"path","name":"purchaseId","description":"Public purchase ID.","example":"purchase_01M1RWCB448HVT2EERNK5Y4RQK","required":true,"schema":{"type":"string"}}]},"/api/v1/reverse-invoices":{"get":{"summary":"Get reverse invoices.","operationId":"getReverseInvoices","description":"Requires `date_from`. Returns only locally created reverse invoices from the database\n(not eTIMS-imported purchases).\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"query","name":"date_from","description":"date Start date (inclusive).","example":"2026-09-01","required":true,"schema":{"type":"string","description":"date Start date (inclusive).","example":"2026-09-01"}},{"in":"query","name":"per_page","description":"Optional page size.","example":15,"required":false,"schema":{"type":"integer","description":"Optional page size.","example":15}},{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Reverse Invoicing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date_from":{"type":"string","description":"Must be a valid date.","example":"2026-09-29T21:30:10"},"per_page":{"type":"integer","description":"Must be at least 1. Must not be greater than 100.","example":1}},"required":["date_from"]}}}},"security":[{"BranchApiKey":[]}]},"post":{"summary":"Add reverse invoice.","operationId":"addReverseInvoice","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.\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":[],"tags":["Reverse Invoicing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"external_purchase_id":{"type":"string","description":"Must not be greater than 255 characters.","example":"b","nullable":true},"supplier_id":{"type":"string","description":"Public supplier ID.","example":"supplier_01H…","nullable":true},"invoice_number":{"type":"string","description":"Must not be greater than 50 characters.","example":"n","nullable":true},"supplier_pin":{"type":"string","description":"Supplier KRA PIN when supplier_id is omitted.","example":"P051402944X"},"supplier_name":{"type":"string","description":"Supplier name when creating/using PIN.","example":"Acme Supplies"},"supplier_branch_id":{"type":"string","description":"Must be 2 characters.","example":"hw","nullable":true},"supplier_invoice_number":{"type":"string","description":"Must not be greater than 50 characters.","example":"a","nullable":true},"purchase_date":{"type":"date","description":"Purchase date.","example":"2026-09-10"},"purchase_type_code":{"type":"string","description":"See [Code Definitions — Transaction Type](/docs/code-definitions#transaction-type).","example":"C","enum":["N","C"],"nullable":true},"receipt_type_code":{"type":"string","description":"See [Code Definitions — Purchase Receipt Type](/docs/code-definitions#purchase-receipt-type).","example":"R","enum":["P","R"],"nullable":true},"registration_type_code":{"type":"string","description":"See [Code Definitions — Registration Type](/docs/code-definitions#registration-type).","example":"A","enum":["M","A"],"nullable":true},"items":{"type":"array","description":"Line items. Identify each product with public `item_id`.","example":[[]],"items":{"type":"object","properties":{"item_id":{"type":"string","description":"Public item ID.","example":"item_01M1RWCB448HVT2EERNK5Y4RQK","nullable":true},"item_code":{"type":"string","description":"This field is required when <code>items.*.item_id</code> is not present. Must not be greater than 50 characters.","example":"i","nullable":true},"item_name":{"type":"string","description":"Must not be greater than 255 characters.","example":"y","nullable":true},"quantity":{"type":"number","description":"Quantity.","example":1},"unit_price":{"type":"number","description":"Optional tax-inclusive unit price (defaults from item).","example":116,"nullable":true},"tax_type_code":{"type":"string","description":"See [Code Definitions — Tax Type](/docs/code-definitions#tax-type).","example":"E","enum":["A","B","C","D","E"],"nullable":true},"supply_amount":{"type":"number","description":"Must be at least 0.","example":37,"nullable":true},"taxable_amount":{"type":"number","description":"Must be at least 0.","example":9,"nullable":true},"tax_amount":{"type":"number","description":"Must be at least 0.","example":52,"nullable":true},"total_amount":{"type":"number","description":"Must be at least 0.","example":8,"nullable":true},"item_classification_code":{"type":"string","description":"Must not be greater than 50 characters. See [Code Definitions — Item Classification](/docs/code-definitions#item-classification).","example":"k","nullable":true},"packaging_unit_code":{"type":"string","description":"Must not be greater than 2 characters. See [Code Definitions — Packaging Unit](/docs/code-definitions#packaging-unit).","example":"hw","nullable":true},"quantity_unit_code":{"type":"string","description":"Must not be greater than 3 characters. See [Code Definitions — Unit of Quantity](/docs/code-definitions#unit-of-quantity).","example":"a","nullable":true},"package_quantity":{"type":"number","description":"Must be at least 0.","example":50,"nullable":true}},"required":["item_id","quantity"]}},"payment_type":{"type":"string","description":"Payment method. See [Payment Method](/docs/code-definitions#payment-method). See [Code Definitions — Payment Method](/docs/code-definitions#payment-method).","example":"01"},"remarks":{"type":"string","description":"Must not be greater than 1000 characters.","example":"b","nullable":true},"total_taxable_amount":{"type":"number","description":"Must be at least 0.","example":39,"nullable":true},"total_tax_amount":{"type":"number","description":"Must be at least 0.","example":84,"nullable":true},"total_amount":{"type":"number","description":"Must be at least 0.","example":12,"nullable":true}},"required":["purchase_date","items","payment_type"]}}}},"security":[{"BranchApiKey":[]}]}},"/api/v1/reverse-invoices/credit-notes":{"get":{"summary":"Get reverse credit notes.","operationId":"getReverseCreditNotes","description":"Requires `date_from`. Returns only credit notes issued against reverse invoices.\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"query","name":"date_from","description":"date Start date (inclusive).","example":"2026-09-01","required":true,"schema":{"type":"string","description":"date Start date (inclusive).","example":"2026-09-01"}},{"in":"query","name":"per_page","description":"Optional page size.","example":15,"required":false,"schema":{"type":"integer","description":"Optional page size.","example":15}},{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Reverse Invoicing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date_from":{"type":"string","description":"Must be a valid date.","example":"2026-09-29T21:30:10"},"per_page":{"type":"integer","description":"Must be at least 1. Must not be greater than 100.","example":1}},"required":["date_from"]}}}},"security":[{"BranchApiKey":[]}]},"post":{"summary":"Add reverse credit note.","operationId":"addReverseCreditNote","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.\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":[],"tags":["Reverse Invoicing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"purchase_id":{"type":"string","description":"Public reverse invoice ID.","example":"purchase_01M1RWCB448HVT2EERNK5Y4RQK"},"reason_code":{"type":"string","description":"Credit Note Reason Code (01–06). See [Credit Note Reason](/docs/code-definitions#credit-note-reason). See [Code Definitions — Credit Note Reason](/docs/code-definitions#credit-note-reason).","example":"06"},"reason_description":{"type":"string","description":"Optional additional details.","example":"Supplier refund","nullable":true}},"required":["purchase_id","reason_code"]}}}},"security":[{"BranchApiKey":[]}]}},"/api/v1/reverse-invoices/credit-notes/{creditNoteId}":{"get":{"summary":"Get reverse credit note details.","operationId":"getReverseCreditNoteDetails","description":"Retrieves a reverse-invoice credit note from the local database by public `credit_note_` ID\nor human `credit_note_number`.\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Reverse Invoicing"],"security":[{"BranchApiKey":[]}]},"parameters":[{"in":"path","name":"creditNoteId","description":"Public credit note ID or number.","example":"credit_note_01M1RWCB448HVT2EERNK5Y4RQK","required":true,"schema":{"type":"string"}}]},"/api/v1/reverse-invoices/{purchaseId}":{"get":{"summary":"Get reverse invoice details.","operationId":"getReverseInvoiceDetails","description":"Retrieves a reverse invoice from the local database by public `purchase_id`.\nReturns 404 if the ID refers to an eTIMS-imported purchase.\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Reverse Invoicing"],"security":[{"BranchApiKey":[]}]},"parameters":[{"in":"path","name":"purchaseId","description":"Public purchase ID.","example":"purchase_01M1RWCB448HVT2EERNK5Y4RQK","required":true,"schema":{"type":"string"}}]},"/api/v1/imported-items":{"get":{"summary":"Get list of import items received from eTIMS.","operationId":"getListOfImportItemsReceivedFromETIMS","description":"Requires `date_from`. Requests import items from KRA/eTIMS, synchronizes them into the\nlocal database (idempotent — duplicates are not created), assigns `import_` public IDs,\nthen returns the local records. Does not return the raw KRA response.\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"query","name":"date_from","description":"date Start date for the eTIMS pull (inclusive).","example":"2026-09-01","required":true,"schema":{"type":"string","description":"date Start date for the eTIMS pull (inclusive).","example":"2026-09-01"}},{"in":"query","name":"per_page","description":"Optional page size.","example":15,"required":false,"schema":{"type":"integer","description":"Optional page size.","example":15}},{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Imported Items"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date_from":{"type":"string","description":"Must be a valid date.","example":"2026-09-29T21:30:10"},"per_page":{"type":"integer","description":"Must be at least 1. Must not be greater than 100.","example":1}},"required":["date_from"]}}}},"security":[{"BranchApiKey":[]}]},"post":{"summary":"Create import item.","operationId":"createImportItem","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).\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":[],"tags":["Imported Items"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"item_id":{"type":"string","description":"Public item ID.","example":"item_01M1RWCB448HVT2EERNK5Y4RQK"},"task_code":{"type":"string","description":"KRA import task code.","example":"202409001"},"declaration_date":{"type":"date","description":"Declaration date.","example":"2026-09-01"},"item_seq":{"type":"integer","description":"Optional item sequence (defaults to 1).","example":1,"nullable":true},"hs_code":{"type":"string","description":"Optional HS code.","example":"00","nullable":true},"remark":{"type":"string","description":"Optional remark sent to KRA.","example":"architecto","nullable":true}},"required":["item_id","task_code","declaration_date"]}}}},"security":[{"BranchApiKey":[]}]}},"/api/v1/reports/business":{"get":{"summary":"Get Business Report.","operationId":"getBusinessReport","description":"Returns a consolidated report for `date_from` → `date_to` with:\n\n- `business_report` — totals for the entire authenticated business\n- `branches` — 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.","parameters":[{"in":"query","name":"date_from","description":"date Start of the reporting period (YYYY-MM-DD).","example":"2026-09-01","required":true,"schema":{"type":"string","description":"date Start of the reporting period (YYYY-MM-DD).","example":"2026-09-01"}},{"in":"query","name":"date_to","description":"date End of the reporting period (YYYY-MM-DD).","example":"2026-09-17","required":true,"schema":{"type":"string","description":"date End of the reporting period (YYYY-MM-DD).","example":"2026-09-17"}},{"in":"header","name":"X-API-Key","description":"Business API Key or Branch API Key for this business-scoped endpoint.","example":"YOUR_BUSINESS_API_KEY","schema":{"type":"string"}}],"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"type":"object","example":{"status":"success","data":{"date_from":"2026-09-01","date_to":"2026-09-17","business_report":{"sales":{"successful_synced_value":1160,"vat":160},"credit_notes":{"successful_synced_value":116,"vat":16},"purchases":{"successful_synced_value":2320,"vat":320}},"branches":[{"branch_id":"branch_01M1RWCB448HVT2EERNK5Y4RQK","branch_name":"Main Branch","report":{"sales":{"successful_synced_value":1160,"vat":160},"credit_notes":{"successful_synced_value":116,"vat":16},"purchases":{"successful_synced_value":2320,"vat":320}}}]}},"properties":{"status":{"type":"string","example":"success"},"data":{"type":"object","properties":{"date_from":{"type":"string","example":"2026-09-01"},"date_to":{"type":"string","example":"2026-09-17"},"business_report":{"type":"object","properties":{"sales":{"type":"object","properties":{"successful_synced_value":{"type":"number","example":1160},"vat":{"type":"number","example":160}}},"credit_notes":{"type":"object","properties":{"successful_synced_value":{"type":"number","example":116},"vat":{"type":"number","example":16}}},"purchases":{"type":"object","properties":{"successful_synced_value":{"type":"number","example":2320},"vat":{"type":"number","example":320}}}}},"branches":{"type":"array","example":[{"branch_id":"branch_01M1RWCB448HVT2EERNK5Y4RQK","branch_name":"Main Branch","report":{"sales":{"successful_synced_value":1160,"vat":160},"credit_notes":{"successful_synced_value":116,"vat":16},"purchases":{"successful_synced_value":2320,"vat":320}}}],"items":{"type":"object","properties":{"branch_id":{"type":"string","example":"branch_01M1RWCB448HVT2EERNK5Y4RQK"},"branch_name":{"type":"string","example":"Main Branch"},"report":{"type":"object","properties":{"sales":{"type":"object","properties":{"successful_synced_value":{"type":"number","example":1160},"vat":{"type":"number","example":160}}},"credit_notes":{"type":"object","properties":{"successful_synced_value":{"type":"number","example":116},"vat":{"type":"number","example":16}}},"purchases":{"type":"object","properties":{"successful_synced_value":{"type":"number","example":2320},"vat":{"type":"number","example":320}}}}}}}}}}}}}}}},"tags":["Reports"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date_from":{"type":"string","description":"Must be a valid date.","example":"2026-09-29T21:30:10"},"date_to":{"type":"string","description":"Must be a valid date. Must be a date after or equal to <code>date_from</code>.","example":"2052-10-22"}},"required":["date_from","date_to"]}}}},"security":[{"BusinessApiKey":[]},{"BranchApiKey":[]}]}},"/api/v1/notices":{"get":{"summary":"Get list of KRA notices for business.","operationId":"getListOfKRANoticesForBusiness","description":"Returns notices already stored in the local database. Does not call KRA unless\nan explicit refresh is requested (hidden from public docs).\n\n**Authentication:** Requires a Branch API Key.","parameters":[{"in":"query","name":"search","description":"Optional search.","example":"VAT","required":false,"schema":{"type":"string","description":"Optional search.","example":"VAT"}},{"in":"query","name":"per_page","description":"Optional page size.","example":20,"required":false,"schema":{"type":"integer","description":"Optional page size.","example":20}},{"in":"header","name":"X-API-Key","description":"Branch API Key for this endpoint.","example":"YOUR_BRANCH_API_KEY","schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"status":"error","message":"Invalid API key","error_code":"INVALID_API_KEY"},"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Invalid API key"},"error_code":{"type":"string","example":"INVALID_API_KEY"}}}}}}},"tags":["Notices"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"refresh":{"type":"boolean","description":"","example":false},"search":{"type":"string","description":"Must not be greater than 255 characters.","example":"b"},"per_page":{"type":"integer","description":"Must be at least 1. Must not be greater than 100.","example":22}}}}}},"security":[{"BranchApiKey":[]}]}}}}