{ "openapi": "3.1.0", "info": { "title": "Bizflow eTIMS Customer API", "version": "1.0.0-preview", "description": "Tenant-isolated fiscal records for ERP and POS integrations. No receivables or accounting entries are created. V1 prices and discounts are tax-inclusive KES. Preview: confirm account activation before production use." }, "servers": [ { "url": "https://api.bizflow.africa/api/etims/v1", "description": "Bizflow; environment is fixed by the key and account connection." } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Products" }, { "name": "Stock" }, { "name": "Documents" } ], "paths": { "/products": { "post": { "summary": "Register a product", "description": "Required scope: products:write. Durable acceptance is not fiscal completion.", "tags": [ "Products" ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" }, "description": "Stable for retries of the same logical command." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRequest" }, "example": { "externalReference": "SERVICE-001", "name": "Consultation", "description": "Consultation service", "type": "SERVICES", "taxCategory": "B", "classificationCode": "85121600", "unitCode": "U", "packagingCode": "NT", "originCountry": "KE", "unitPrice": "116.00" } } } }, "responses": { "200": { "description": "Existing or completed record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "202": { "description": "Stored; poll its ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Delay in seconds." } } }, "503": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/products/{id}": { "get": { "summary": "Read product registration and balance", "description": "Required scope: products:read.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current record. Missing receipt fields are omitted, never synthesized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Delay in seconds." } } }, "503": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/stock-balances": { "post": { "summary": "Set an absolute stock balance", "description": "Required scope: stock:write. Durable acceptance is not fiscal completion.", "tags": [ "Stock" ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" }, "description": "Stable for retries of the same logical command." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockRequest" }, "example": { "externalReference": "COUNT-001", "productId": "00000000-0000-4000-8000-000000000001", "expectedBalance": "0.000000", "balance": "20.000000" } } } }, "responses": { "200": { "description": "Existing or completed record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "202": { "description": "Stored; poll its ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Delay in seconds." } } }, "503": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/stock-balances/{id}": { "get": { "summary": "Read a stock command", "description": "Required scope: stock:write.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current record. Missing receipt fields are omitted, never synthesized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Delay in seconds." } } }, "503": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/invoices": { "post": { "summary": "Create a fiscal invoice", "description": "Required scope: invoices:write. Durable acceptance is not fiscal completion.", "tags": [ "Documents" ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" }, "description": "Stable for retries of the same logical command." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRequest" }, "example": { "externalReference": "POS-001", "issuedAt": "2026-10-26T10:00:00+03:00", "currency": "KES", "paymentMethod": "01", "buyer": { "name": "Walk-in customer" }, "items": [ { "productId": "00000000-0000-4000-8000-000000000001", "quantity": "3", "unitPrice": "116.00", "discount": { "type": "PERCENTAGE", "value": "10.00" } } ] } } } }, "responses": { "200": { "description": "Existing or completed record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "202": { "description": "Stored; poll its ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Delay in seconds." } } }, "503": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/invoices/{id}": { "get": { "summary": "Read an invoice and verified receipt", "description": "Required scope: invoices:read.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current record. Missing receipt fields are omitted, never synthesized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Delay in seconds." } } }, "503": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/credit-notes": { "post": { "summary": "Create a credit note", "description": "Required scope: credits:write. Durable acceptance is not fiscal completion.", "tags": [ "Documents" ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" }, "description": "Stable for retries of the same logical command." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditRequest" }, "example": { "externalReference": "RETURN-001", "originalInvoiceId": "00000000-0000-4000-8000-000000000002", "issuedAt": "2026-10-26T12:00:00+03:00", "reasonCode": "01", "items": [ { "originalSequence": 1, "quantity": "1" } ] } } } }, "responses": { "200": { "description": "Existing or completed record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "202": { "description": "Stored; poll its ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Delay in seconds." } } }, "503": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/credit-notes/{id}": { "get": { "summary": "Read a credit note", "description": "Required scope: invoices:read.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current record. Missing receipt fields are omitted, never synthesized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Delay in seconds." } } }, "503": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/documents": { "get": { "summary": "List fiscal-only invoices and credits", "description": "Required scope: invoices:read. Newest first. This list excludes accounting invoices.", "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }, { "in": "query", "name": "size", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Fiscal documents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordPage" } } } }, "400": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Delay in seconds." } } }, "503": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/documents/{id}/pdf": { "get": { "summary": "Download a verified fiscal PDF", "description": "Required scope: invoices:read. Available only after verified completion. Repeated downloads carry COPY. Pending or simulated documents return 409.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "PDF document.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Delay in seconds." } } }, "503": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reference-data": { "get": { "summary": "Read active fiscal codes", "description": "Required scope: products:read. Rate is supplied for tax categories only.", "parameters": [ { "in": "query", "name": "type", "required": true, "schema": { "type": "string", "enum": [ "TAX_TYPE", "UNIT_QUANTITY", "PACKAGING_UNIT", "PAYMENT_METHOD", "CREDIT_NOTE_REASON" ] } } ], "responses": { "200": { "description": "Account reference data.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Reference" } } } } }, "400": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Delay in seconds." } } }, "503": { "description": "Bizflow error. Preserve the request identity after uncertain delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Bizflow API key", "description": "Generate a scoped key in account Settings > Developer API. Never send a tenant header." } }, "schemas": { "Discount": { "type": "object", "additionalProperties": false, "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "NONE", "FIXED", "PERCENTAGE" ] }, "value": { "oneOf": [ { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,2})?$" }, { "type": "number", "minimum": 0, "exclusiveMaximum": 1000000000000, "multipleOf": 0.01 } ], "description": "Non-negative decimal. Strings are recommended to avoid floating-point loss." } } }, "Buyer": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "kraPin": { "type": "string", "pattern": "^[AP][A-Z0-9]{9}[A-Z]$" } } }, "InvoiceLine": { "type": "object", "additionalProperties": false, "required": [ "productId", "quantity", "unitPrice" ], "properties": { "productId": { "type": "string", "format": "uuid" }, "quantity": { "oneOf": [ { "type": "string", "pattern": "^(?=.*[1-9])\\d{1,9}(\\.\\d{1,3})?$" }, { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1000000000, "multipleOf": 0.001 } ], "description": "Positive decimal. Strings are recommended to avoid floating-point loss." }, "unitPrice": { "oneOf": [ { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,2})?$" }, { "type": "number", "minimum": 0, "exclusiveMaximum": 1000000000000, "multipleOf": 0.01 } ], "description": "Non-negative decimal. Strings are recommended to avoid floating-point loss." }, "discount": { "$ref": "#/components/schemas/Discount" } } }, "InvoiceRequest": { "type": "object", "additionalProperties": false, "required": [ "externalReference", "issuedAt", "currency", "paymentMethod", "buyer", "items" ], "properties": { "externalReference": { "type": "string", "pattern": "^[A-Za-z0-9_./-]{1,80}$" }, "issuedAt": { "type": "string", "format": "date-time", "description": "Actual transaction time with timezone offset; no more than five minutes in the future." }, "currency": { "type": "string", "const": "KES" }, "paymentMethod": { "type": "string", "pattern": "^0[1-7]$" }, "buyer": { "$ref": "#/components/schemas/Buyer" }, "discount": { "$ref": "#/components/schemas/Discount" }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/InvoiceLine" } } } }, "CreditLine": { "type": "object", "additionalProperties": false, "required": [ "originalSequence", "quantity" ], "properties": { "originalSequence": { "type": "integer", "minimum": 1 }, "quantity": { "oneOf": [ { "type": "string", "pattern": "^(?=.*[1-9])\\d{1,9}(\\.\\d{1,3})?$" }, { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1000000000, "multipleOf": 0.001 } ], "description": "Positive decimal. Strings are recommended to avoid floating-point loss." } } }, "CreditRequest": { "type": "object", "additionalProperties": false, "required": [ "externalReference", "originalInvoiceId", "issuedAt", "reasonCode", "items" ], "properties": { "externalReference": { "type": "string", "pattern": "^[A-Za-z0-9_./-]{1,80}$" }, "originalInvoiceId": { "type": "string", "format": "uuid" }, "issuedAt": { "type": "string", "format": "date-time", "description": "Actual transaction time with timezone offset; no more than five minutes in the future." }, "reasonCode": { "type": "string", "pattern": "^[0-9]{2}$" }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/CreditLine" } } } }, "ProductRequest": { "type": "object", "additionalProperties": false, "required": [ "externalReference", "name", "type", "taxCategory", "classificationCode", "unitCode", "packagingCode", "originCountry", "unitPrice" ], "properties": { "externalReference": { "type": "string", "pattern": "^[A-Za-z0-9_./-]{1,80}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "GOODS", "SERVICES" ] }, "taxCategory": { "type": "string", "enum": [ "A", "B", "C", "D", "E" ] }, "classificationCode": { "type": "string", "pattern": "^[0-9]{8,10}$" }, "unitCode": { "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$" }, "packagingCode": { "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$" }, "originCountry": { "type": "string", "pattern": "^[A-Z]{2}$" }, "unitPrice": { "oneOf": [ { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,2})?$" }, { "type": "number", "minimum": 0, "exclusiveMaximum": 1000000000000, "multipleOf": 0.01 } ], "description": "Non-negative decimal. Strings are recommended to avoid floating-point loss." } } }, "StockRequest": { "type": "object", "additionalProperties": false, "required": [ "externalReference", "productId", "expectedBalance", "balance" ], "properties": { "externalReference": { "type": "string", "pattern": "^[A-Za-z0-9_./-]{1,80}$" }, "productId": { "type": "string", "format": "uuid" }, "expectedBalance": { "oneOf": [ { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,6})?$" }, { "type": "number", "minimum": 0, "exclusiveMaximum": 10000000000000, "multipleOf": 0.000001 } ], "description": "Non-negative decimal. Strings are recommended to avoid floating-point loss." }, "balance": { "oneOf": [ { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,6})?$" }, { "type": "number", "minimum": 0, "exclusiveMaximum": 10000000000000, "multipleOf": 0.000001 } ], "description": "Non-negative decimal. Strings are recommended to avoid floating-point loss." } } }, "Totals": { "type": "object", "additionalProperties": false, "required": [ "currency", "taxableAmount", "taxAmount", "totalAmount", "discountAmount" ], "properties": { "currency": { "type": "string", "const": "KES" }, "taxableAmount": { "type": "string" }, "taxAmount": { "type": "string" }, "totalAmount": { "type": "string" }, "discountAmount": { "type": "string" } } }, "Receipt": { "type": "object", "additionalProperties": false, "required": [ "receiptSignature", "verificationUrl" ], "properties": { "kraInvoiceNumber": { "type": "string" }, "cuInvoiceNumber": { "type": "string" }, "receiptNumber": { "type": "string" }, "receiptCounter": { "type": "string" }, "scuId": { "type": "string" }, "scuDateTime": { "type": "string" }, "internalData": { "type": "string" }, "receiptSignature": { "type": "string" }, "verificationUrl": { "type": "string", "format": "uri" } } }, "Record": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "externalReference", "environment", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "INVOICE", "CREDIT", "PRODUCT", "STOCK" ] }, "externalReference": { "type": "string", "pattern": "^[A-Za-z0-9_./-]{1,80}$" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "status": { "type": "string", "enum": [ "PENDING", "REGISTERED", "COMPLETED", "ACTION_REQUIRED", "SIMULATED" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "totals": { "$ref": "#/components/schemas/Totals" }, "receipt": { "$ref": "#/components/schemas/Receipt" }, "originalInvoiceId": { "type": "string", "format": "uuid" }, "stockBalance": { "type": "string" }, "stockStatus": { "type": "string" }, "request": { "type": "object" } } }, "Error": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string" } } } } }, "RecordPage": { "type": "object", "additionalProperties": false, "required": [ "items", "page", "hasMore" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } }, "page": { "type": "integer" }, "hasMore": { "type": "boolean" } } }, "Reference": { "type": "object", "additionalProperties": false, "required": [ "code", "name", "rate" ], "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "rate": { "type": [ "string", "null" ] } } } } } }