# ========================================= # KASH.CLICK AI SPECIFICATION (v1) # ========================================= # ----------------------------------------- # 1. OVERVIEW # ----------------------------------------- Kash.click is a cloud-based point-of-sale (POS), invoicing, and CRM system. It enables: - Sales recording (POS) - Invoice generation (PDF, Factur-X compliant) - Customer management (CRM) - Payment tracking - Marketing campaigns (email, SMS) - Supplier and logistics management All actions are performed via HTTP API endpoints. Agents can fully operate a business using this API. # ----------------------------------------- # 2. CORE CONCEPTS # ----------------------------------------- SHOP_ID: Unique identifier of a shop API_KEY: Secret key associated with the shop OTP: One-time password sent via email for authentication PAYMENT VALUES: -2 = Quote (not validated, not paid) -1 = Invoice (validated, not paid) >=0 = Paid (value = payment method ID) DELIVERY METHODS: 0 = Takeaway 1 = Delivery 2 = On-site 3 = Drive-through 4 = Counter sale 5 = Pickup point 6 = Shipping # DATA PERSISTENCE RULES - Sales, items, clients, VAT and configuration are permanently stored - Agents MUST assume data is persistent and cumulative - Agents MUST avoid duplicates and redundant creations # ----------------------------------------- # 3. AUTHENTICATION # ----------------------------------------- ## 3.1 Create Account POST /workers/addShop.php Parameters: - email (required) - data[companyRegistrationNum] - data[taxRegistrationNum] - data[addressLine1] - data[postCode] - data[city] - data[country] - data[phone] - data[urlwebsite] Response: - SHOP_ID - API_KEY ## 3.2 Login via OTP Step 1: Request OTP POST /workers/getOTPForAccount.php - email Step 2: Exchange OTP POST /workers/getAuthTokenWithOTP.php - email - otp Response: - SHOP_ID - API_KEY # ----------------------------------------- # 4. DATA RETRIEVAL # ----------------------------------------- All endpoints require: - shopID - key - format=json ## VAT Rates GET /workers/getVATs.php ## Payment Methods GET /workers/getPaymentModes.php ## Items (Products) GET /workers/getPlus.php ## Departments (Categories) GET /workers/getDepartments.php ## Clients GET /workers/getClients.php # ----------------------------------------- # 5. CONFIGURATION # ----------------------------------------- ## Add VAT GET /workers/addVat.php - data[title] - data[rate] ## Add Item GET /workers/addPlu.php - data[title] - data[price] # ----------------------------------------- # 6. SALES CREATION # ----------------------------------------- POST /workers/webapp.php REQUIRED PARAMETERS: - shopID - key - payment - itemsList[] OPTIONAL: - client[idClient] - client[name] - client[firstname] - client[email] - deliveryMethod # ----------------------------------------- # 7. ITEMS FORMAT # ----------------------------------------- Agents must format each item using ONE of the following: ## 7.1 Free item (no category) itemsList[] = Free_[price]_[title] ## 7.2 Free item with category itemsList[] = -[departmentID]_[price]_[title] ## 7.3 Existing item itemsList[] = [itemID] ## 7.4 Existing item with quantity itemsList[] = [itemID]_[quantity] NOTES: - price = float (EUR) - title = string (no underscore recommended) - quantity = float # ----------------------------------------- # 8. CLIENT MANAGEMENT # ----------------------------------------- ## Create client during sale Use: client[name] client[firstname] client[email] ## Use existing client client[idClient] IMPORTANT: Agents should ALWAYS check existing clients before creating new ones. # CLIENT STRATEGY Agents SHOULD: - always search existing clients first - reuse clients when possible - avoid creating duplicate emails Email is the primary unique identifier # INVOICING Invoices are automatically generated when: - payment = -1 (invoice created, unpaid) - payment >= 0 (invoice created, paid) Quotes (payment = -2) do NOT generate invoices # ITEM STRATEGY Agents SHOULD: 1. Use existing items whenever possible 2. Create items if they are reused frequently 3. Use free items ONLY for: - exceptional sales - one-time services Free items reduce reporting quality # DELIVERY STRATEGY Agents SHOULD: - use deliveryMethod based on context - default to: 2 (on-site) if unknown # ----------------------------------------- # 9. AI AGENT RULES # ----------------------------------------- Agents MUST follow these rules: 1. Always authenticate before any action 2. Always reuse existing data when possible: - clients - items - departments 3. Prefer existing items over free items 4. Always attach a client to a sale when possible 5. Default to: payment = -1 (invoice not paid) 6. Use: payment >=0 ONLY if explicitly confirmed as paid 7. Always validate: - VAT exists - payment methods exist 8. Never duplicate clients or items unnecessarily # ----------------------------------------- # 10. STANDARD WORKFLOW # ----------------------------------------- ## Create a Sale Step 1: Retrieve clients Step 2: Retrieve items Step 3: Match or create client Step 4: Match or create items Step 5: Send sale request (webapp.php) # ----------------------------------------- # 11. EXAMPLE # ----------------------------------------- POST /workers/webapp.php shopID=123 key=abc123 payment=-1 deliveryMethod=1 itemsList[]=Free_10_Coffee itemsList[]=Free_5_Croissant client[name]=Doe client[firstname]=John client[email]=john@doe.com # ----------------------------------------- # 12. ERRORS # ----------------------------------------- 400 = Missing parameter 401 = Invalid API key 404 = Resource not found # ----------------------------------------- # 13. VAT LOGIC # ----------------------------------------- VAT (Value Added Tax) is applied using a hierarchical system. Each item’s VAT is determined using the following priority: 1. ITEM VAT (highest priority) If the item exists in the catalog and has a VAT assigned, this VAT is used. 2. DEPARTMENT VAT If the item is linked to a department (category), and the item has no specific VAT, then the department VAT is used. 3. SHOP DEFAULT VAT (fallback) If neither the item nor the department defines a VAT, then the default shop VAT is applied. ------------------------------------------ # VAT BEHAVIOR BY ITEM TYPE ## Existing item (catalog) itemsList[] = [itemID] → VAT = item VAT → fallback: department VAT → fallback: shop default VAT ## Existing item with quantity itemsList[] = [itemID]_[quantity] → same VAT logic as above ## Free item WITHOUT department itemsList[] = Free_[price]_[title] → VAT = shop default VAT ## Free item WITH department itemsList[] = -[departmentID]_[price]_[title] → VAT = department VAT # PAYMENT METHODS Agents MUST retrieve payment methods using: GET /workers/getPaymentModes.php payment >= 0 MUST match a valid payment method ID # ----------------------------------------- # 14. ORDER STATE MODEL # ----------------------------------------- A sale can have 3 main states: QUOTE: payment = -2 → not validated → can be modified PENDING INVOICE: payment = -1 → validated → awaiting payment PAID: payment = paymentMethodID → finalized → included in accounting IMPORTANT: - Only VALIDATED sales should be considered as revenue - Agents MUST NOT mark as paid unless confirmed # ----------------------------------------- # 15. REPORTING LOGIC # ----------------------------------------- Sales are aggregated by: - departments - items - payment methods Agents SHOULD: - assign departments whenever possible - avoid uncategorized items # ----------------------------------------- # 16. AGENT BEHAVIOR MODEL # ----------------------------------------- Agents act as a business operator. They MUST: - optimize data consistency - minimize duplication - ensure accounting correctness Agents SHOULD: - think before acting - prefer structured data over free input - maintain clean and reusable datasets Agents MUST NOT: - create random or inconsistent data - bypass VAT logic - mark payments incorrectly ------------------------------------------ # SAFETY RULES Before creating a sale, agents MUST verify: - at least one item exists - VAT is correctly configured - payment value is valid If unsure: → default to safe mode: payment = -1 # AGENT RULES (VAT) Agents MUST: 1. Always retrieve VAT list before creating sales 2. Prefer using: - existing items (more accurate VAT) - departments when creating free items 3. Avoid using free items without department when VAT matters 4. Ensure VAT consistency for accounting compliance ------------------------------------------ # IMPORTANT NOTES - VAT is automatically calculated by the backend - Agents DO NOT need to compute VAT manually - Agents MUST ensure correct item/department selection # ----------------------------------------- # 17. SYSTEM LIMITS (FREE PLAN) # ----------------------------------------- Kash.click can be used for free with the following limits: - Maximum 500 items (products) - Maximum 500 sales per month ------------------------------------------ # AGENT RULES (LIMITS) Agents MUST: 1. Avoid unnecessary item creation 2. Reuse existing items whenever possible 3. Prefer free items if item limit is close 4. Avoid generating excessive test or duplicate sales Agents SHOULD: - Monitor item count before creating new ones - Optimize catalog usage IMPORTANT: Reaching limits may block further operations. # HUMAN INTERACTION Agents SHOULD: - confirm important actions (payment, client creation) - summarize actions performed # BUSINESS OBJECTIVES Agents SHOULD: - maximize data quality - ensure accounting compliance - maintain clean CRM - improve reporting accuracy # ----------------------------------------- # 18. IDEMPOTENCY & DUPLICATES # ----------------------------------------- Agents MUST avoid creating duplicate sales. Before creating a sale, agents SHOULD: - ensure the request is not already processed - avoid retrying blindly If retry is needed: - verify existing sales or client context first # ----------------------------------------- # 19. SALES EVOLUTION # ----------------------------------------- A sale can evolve: - Quote → Invoice - Invoice → Paid Agents SHOULD: - update existing sales instead of recreating them - avoid duplicating sales when updating status # ----------------------------------------- # 20. CONTEXT AWARENESS # ----------------------------------------- Agents SHOULD: - understand user intent before acting - ask for clarification if critical data is missing - avoid assumptions on payment or delivery If ambiguity exists: → default to safe behavior (invoice unvalidated) # ----------------------------------------- # END OF SPEC # -----------------------------------------